Receiz/Developers/Public Contract

Developers

One user. One subject. One audit trail.

Proof, login, delegated actions, settlement, and live interaction stay on one contract.

Your app gets one user, one subject, and one audit trail across login, actions, payments, and public interaction. You do not run a password reset funnel or watch the same person fork into two accounts. Every state change and trust claim stays traceable to code, evidence, manifests, and governance artifacts.

Open Site KitEmbed the front doorAdd action cards
DeterministicPortableStandards-basedPublic ContractLeast PrivilegeProductionDeterministicPortableStandards-basedPublic Contract
Create OIDC ClientConnect GuidePublic LedgerGive users a front doorReach people outside the profile
Story ladder
VerifyLive TwinPaymentsAutomationDevelopers
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.
One contract, fewer moving parts

Proof, login, settlement, and live interaction stay on one published contract instead of separate systems and shadow state.

Exact routes, not black boxes

You can call the exact routes where proof is checked, users log in, payments happen, and live threads move.

One user everywhere

The same user can start on your domain, a Receiz experience, or an external app and remain the same user.

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

Issue, verify, and inspect artifacts without leaving the public contract.

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

Canonical identity issuance, discovery, authorization, 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 over the same wallet, proof, and automation surfaces.

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

Replayable public settlement feeds for transfer, note, and wallet state.

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

Public settlement entrypoints for card checkout and note-upload claims.

POSTNo AuthBoth
/api/payments/embed/checkout

Create embedded or 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.

Live Twin and World

Public identity threads, embeds, messaging, streaming, and governed outreach surfaces.

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 Live Twin surface, public world profile, availability preview, and visitor thread context.

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

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

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

Send a visitor message to a Live 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"
Live Twin Load
curl -X GET "https://receiz.com/api/world/profile/bjklock?visitorKey=<VISITOR_KEY>&threadKey=<THREAD_KEY>"
Live 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>"
  }'
Live Twin Stream
curl -N -X GET "https://receiz.com/api/world/profile/bjklock/stream?visitorKey=<VISITOR_KEY>&threadKey=<THREAD_KEY>"