Receiz/Developers/Public Contract

Developers

Production APIs for verification, identity, settlement, Public Twin, and World.

Public routes cover verification, settlement, OIDC, delegated actions, Public Twin, and World.

Private tools stay private. Configuration, deeper communications controls, and performance controls stay first-party.

Receiz is a deterministic verification-and-settlement platform: original bytes are authoritative for verification, replayable ledger math is authoritative for settlement, and every trust claim is mapped to code and evidence artifacts.

Settlement authority is append-only ledger replay over persisted integer value fields and deterministic rate math.

DeterministicPortableStandards-basedPublic ContractLeast PrivilegeProductionDeterministicPortableStandards-basedPublic Contract
Create OIDC ClientConnect GuidePublic LedgerPublic TwinReceiz World
Disclosure Boundary

Public contract. Private controls.

  • Admin, webhook, signer-service, and other private operational routes are intentionally excluded from public documentation.
  • Client-secret management and privileged issuer/admin operations are available only in authenticated operator surfaces.
  • Rate-limiting implementation details, anti-abuse controls, key material, and infrastructure topology are not publicly documented.
  • Owner-only twin controls, memory imports, performance enrollment, and internal media worker surfaces remain outside the public developer contract.
Deterministic Core

Verification and settlement with canonical schema contracts, offline parity, and machine-safe error envelopes.

Integration Fit

OAuth/OIDC, delegated scopes, and production onboarding that fit existing auth stacks.

Public by Design

Public routes are documented. Public trust claims map back to code and evidence.

Production Flow
  1. Seal a file with /api/document-seal (or /api/receiz for legacy PNG-compatible flows).
  2. Persist returned bytes exactly as received.
  3. Verify with /api/document-verify or /api/verify.
  4. Use OIDC Authorization Code + PKCE for identity and delegated actions, then call /api/connect/* with bearer access tokens.
  5. Use /api/wallet/ledger/public for externally verifiable transfer and note event history.
  6. Use /api/economy/conformance plus /economy traceability tables for requirement-to-code and evidence checks.
  7. Use /governance for control ownership, approval paths, and periodic control-evidence cadence.
  8. Treat OIDC sub as the permanent identity key in your system.
Security Guardrails
  • Use exact redirect URI matching and HTTPS in production.
  • Store client secrets server-side only.
  • Key your user model by OIDC sub, not by mutable email.
  • Enforce least-privilege scopes and rotate credentials on schedule.
  • Abuse monitoring is active; malicious clients can be suspended immediately.
Verification Primitives

Public artifact and claim verification contracts.

POSTNo AuthBoth
/api/document-seal

Seal uploaded files into portable Receiz artifacts.

POSTNo AuthBoth
/api/document-verify

Verify sealed files and package artifacts deterministically.

POSTNo AuthBoth
/api/verify

Verify claim coordinates and return canonical verdict envelopes.

GETNo AuthBoth
/api/verification/conformance

Publish live verification conformance report with source/runtime controls and revision anchors.

GETNo AuthDevelopers
/api/receiz

Legacy Receiz mint/record surface for compatible integrations.

Identity and OIDC

Standards-based identity issuance and token lifecycle.

GETNo AuthDevelopers
/api/connect/login/bootstrap/[username]

Username-based login bootstrap surface returning OIDC launch configuration for copy-paste login embeds.

GETNo AuthDevelopers
/api/oidc/authorize

OIDC Authorization Code + PKCE authorization endpoint.

POSTOAuth Client AuthDevelopers
/api/oidc/token

OIDC token exchange and refresh token rotation endpoint.

GETPOSTBearer Access TokenDevelopers
/api/oidc/userinfo

OpenID user claims endpoint scoped by issued access tokens.

GETNo AuthDevelopers
/api/oidc/jwks

JWKS publication endpoint for OIDC token verification.

POSTOAuth Client AuthDevelopers
/api/oidc/revoke

OAuth token revocation endpoint (RFC 7009 behavior).

POSTOAuth Client AuthDevelopers
/api/oidc/introspect

OAuth token introspection endpoint for backend trust decisions.

Delegated Connect APIs

User-approved actions with scoped bearer access tokens.

POSTBearer Access TokenDevelopers
/api/connect/record

Delegated record action (`receiz:record`) on behalf of users.

POSTBearer Access TokenDevelopers
/api/connect/seal

Delegated seal action (`receiz:seal`) on behalf of users.

POSTBearer Access TokenDevelopers
/api/connect/verify

Delegated verify action (`receiz:verify`) on behalf of users.

GETBearer Access TokenDevelopers
/api/connect/wallet/me

Read delegated wallet summary (`receiz:wallet.read`).

POSTBearer Access TokenDevelopers
/api/connect/transfers

Execute delegated wallet transfers (`receiz:wallet.transfer`).

POSTBearer Access TokenDevelopers
/api/connect/payments/checkout

Create delegated checkout sessions for merchant payments (`receiz:payments.create`).

GETBearer Access TokenDevelopers
/api/connect/payments/session

Read delegated checkout session payment status (`receiz:payments.read`).

POSTBearer Access TokenDevelopers
/api/connect/payments/notes/mint

Mint delegated offline payment notes from wallet balance (`receiz:notes.mint`).

POSTBearer Access TokenDevelopers
/api/connect/payments/notes/claim

Claim delegated offline payment notes into wallet balance (`receiz:notes.claim`).

GETBearer Access TokenDevelopers
/api/connect/payments/notes/[noteId]/download

Download delegated offline payment note artifacts (`receiz:notes.read`).

Wallet Economy Surface

Public ledger observability for transfer and note settlement events.

GETNo AuthBoth
/api/wallet/ledger/public

Public wallet ledger feed exposing transfer and note events with deterministic value fields and pseudonymous actor identities.

GETNo AuthBoth
/api/ledger/actions/public

Public append-only global action ledger feed for auth, receiz, wallet, and identity-key events.

Embeddable Payment Surface

No-auth website embed endpoints for card checkout and note-upload settlement.

POSTNo AuthBoth
/api/payments/embed/checkout

Create hosted checkout sessions that settle directly to a target Receiz username wallet.

POSTNo AuthBoth
/api/payments/embed/note-claim

Accept uploaded note artifacts (or note tokens) and claim value directly into a target Receiz username wallet.

Public Twin and World

Public profile load, messaging, streaming, and embed routes.

GETNo AuthBoth
/api/world/public

Read the public Receiz World snapshot with open districts, featured ventures, and world-level discovery surfaces.

GETNo AuthBoth
/api/world/profile/[username]

Load a profile's Public Twin surface, public world profile, availability preview, and visitor thread context.

POSTNo AuthBoth
/api/world/profile/[username]/stream

Stream Public Twin updates for live retrieval, message continuity, and incremental public profile responses.

POSTNo AuthBoth
/api/world/profile/[username]

Send a visitor message to a Public Twin or request booking through the public profile surface, subject to policy and rate limits.

Seal (cURL)
curl -X POST https://receiz.com/api/document-seal \
  -F "file=@invoice.pdf" \
  -F "visualStamp=0"
Token Exchange
curl -X POST https://receiz.com/api/oidc/token \
  -H "content-type: application/x-www-form-urlencoded" \
  --data "grant_type=authorization_code" \
  --data "code=<AUTH_CODE>" \
  --data "redirect_uri=https://app.example.com/auth/receiz/callback" \
  --data "client_id=<CLIENT_ID>" \
  --data "client_secret=<CLIENT_SECRET>" \
  --data "code_verifier=<PKCE_VERIFIER>"
Delegated Verify
curl -X POST https://receiz.com/api/connect/verify \
  -H "authorization: Bearer <ACCESS_TOKEN>" \
  -F "file=@sealed-artifact.receiz"
Public Ledger Feed
curl -X GET "https://receiz.com/api/wallet/ledger/public?limit=40"
Public Twin Load
curl -X GET "https://receiz.com/api/world/profile/bjklock?visitorKey=<VISITOR_KEY>&threadKey=<THREAD_KEY>"
Public Twin Message
curl -X POST https://receiz.com/api/world/profile/bjklock \
  -H "content-type: application/json" \
  --data '{
    "message": "What is the best next step?",
    "visitorKey": "<VISITOR_KEY>",
    "threadKey": "<THREAD_KEY>"
  }'
Public Twin Stream
curl -N -X GET "https://receiz.com/api/world/profile/bjklock/stream?visitorKey=<VISITOR_KEY>&threadKey=<THREAD_KEY>"