orangecheck · HTTP API

The hosted me.ochk.io substrate exposes the contracts the SDK calls into. The SDK is the canonical integration path; this page is the raw HTTP surface for clients that aren't TypeScript or that want to bypass the SDK.

Every endpoint is at https://me.ochk.io/api/... unless noted. Auth is by cross-subdomain oc_session cookie (Domain=.ochk.io, HttpOnly, SameSite=None, Secure) issued by the auth host at https://ochk.io, OR by an Authorization: Bearer <jwt> header (cross-domain integrators that captured the session token from the popup-signin postMessage). Mutating endpoints are rate-limited per IP per bucket; limits are returned in X-RateLimit-* headers.

Sign-in endpoints (auth host · https://ochk.io)

The session cookie is issued by the family auth host, not by me.ochk.io directly. The sign-in popup at me.ochk.io/popup/signin calls these endpoints cross-origin with credentials — they are CORS-allowed for any *.ochk.io browser origin. ochk.app, on its own domain, calls them without credentials and keeps the token they return in its own cookie.

See oc-me-web/src/pages/popup/signin.tsx for the canonical client implementation against these endpoints.

Public endpoints

Authenticated endpoints (oc_session required)

Integrator-facing endpoints (/api/integrator/event, /api/integrator/event/batch, /api/payment/authorize) additionally accept an Authorization: Bearer <token> header — a cross-domain integrator's backend is on a different eTLD+1 and never receives the Domain=.ochk.io oc_session cookie, so it forwards the popup-issued JWT instead. The remaining endpoints in this section require the cookie.

Authenticated · sessions (Per session)

Authenticated · payment authorization (Per action)

Authenticated · integrator event ingestion

project_key (in the body) identifies the billing project. The earner is either user_address — the user's did_oc, inside the body you sign, which is how a backend fires — or, from a browser, the signed-in user's cookie or Authorization: Bearer token (see the note above). Sign the request with the project signing secret (X-OC-Signature) — in both test and live mode. A user session proves a user, never the paying project, so an unsigned POST is admitted only when the session belongs to the project's own owner (the CLI test-fire path). Anything else gets 401 project_auth_required.

Outside the project's pay periods both answer 200 with earned: false (not_paying per event in a batch) and record nothing. Paying users is optional.

Authenticated · integrator project lifecycle

Moving a verified domain

A verified domain is what consent screens name and what every receipt records, so it never changes in one step. POST /api/me/projects/[id]/domain on a verified project opens a move: the project gets a pending_domain with its own token, and keeps running on its current domain. Publish that token at the new domain, exactly as for a first verification, then call /verify. When the check passes, the new domain becomes the project's domain and the old one is kept in previous_domains, so receipts recorded under it still belong to the project. A failed check changes nothing.

Opening a move needs a fresh identity check, as revealing the signing secret does: without one the call answers 401 identity_reproof_required. A frozen project answers 409 project_frozen.

Response shapes

All authenticated 401s are { ok: false } with Cache-Control: no-store, private and Vary: Cookie. All 422 validation failures return { error: string, details?: [{ subtype?: string, message: string }] }. All 429 rate-limit responses include a Retry-After header in seconds.

Rate limits per bucket

Limits are per IP, per bucket (except verify-domain which is per-account so DNS retries don't get throttled by a noisy neighbor). Headers X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Window are emitted on every rate-limited response. v1 buckets reset on cold start (per-instance in-memory); production fronts every endpoint with an edge-level limiter.