Docs — ProseID

01 — Authentication

Authentication

Every API call carries a Bearer token. Tokens are minted in your console and scoped to a single environment. Tokens are shown once at creation — store them in your backend secret manager, never in client code.

curl

curl https://api.proseid.com/v1/sessions \
  -H "Authorization: Bearer prsid_live_..." \
  -H "Content-Type: application/json"

Missing or invalid tokens return 401 Unauthorized. Revoked tokens return 403 Forbidden.

02 — Idempotency

Idempotency

Pass an Idempotency-Key header on session creation to make retries safe. The same key + same request body within 24 hours returns the same sessionId — never duplicates, never double-billed.

curl https://api.proseid.com/v1/sessions \
  -H "Authorization: Bearer prsid_live_..." \
  -H "Idempotency-Key: order_8f3a9b2c" \
  -H "Content-Type: application/json" \
  -d '{"schema": "acme/onboarding", "signed": true}'

→ Use a unique key per logical operation (order ID, claim ID, etc.) — not per HTTP retry.
→ Same key + different body returns 409 Conflict.
→ Keys are scoped to your API key. Two separate keys can use the same Idempotency-Key independently.

03 — Create a session

Create a session

Call POST /v1/sessions with the schema you want to render and (optionally) a webhook URL. We return a sessionId. Append it to proseid.com/sessions/{sessionId} and redirect your user.

Request

POST /v1/sessions
{
  "schema": "acme/employee-onboarding",
  "signed": true,
  "webhook": "https://yours.app/proseid",
  "metadata": { "orderId": "order_8f3a9b2c" }
}

Response

{
  "sessionId": "sess_7f3a9b2c8d4e",
  "url": "https://proseid.com/sessions/sess_7f3a9b2c8d4e",
  "expiresAt": "2026-04-27T12:00:00Z"
}

Fields

schema: Required. Publisher-qualified slug, e.g. acme/employee-onboarding.
signed: Optional, defaults to false. When true, the completion webhook payload includes an AdES signature. Costs 3 credits instead of 1.
webhook: Optional. URL to POST when the session completes. If omitted, you can poll the session via API instead.
metadata: Optional. Arbitrary JSON object echoed back on the webhook payload. Max 4KB.

04 — Webhook delivery

Webhook delivery

When the user completes the hosted flow, we POST to your webhook URL. Webhook delivery is the only billable event — abandoned sessions cost zero.

Payload — signed: true

{
  "sessionId": "sess_7f3a9b2c8d4e",
  "status": "completed",
  "schema": "acme/employee-onboarding@v3",
  "completedAt": "2026-04-26T18:42:11Z",
  "payload": { ...form fields... },
  "signature": {
    "alg": "AdES-B-LT",
    "value": "MIIH...",
    "certificate": "MIIE..."
  },
  "metadata": { "orderId": "order_8f3a9b2c" }
}

Verify the request came from us using the X-Proseid-Signature header — an HMAC-SHA256 of the raw body keyed with your webhook secret.

→ Unsigned sessions omit the signature object entirely. Cost: 1 credit.
→ Signed sessions deliver an AdES-B-LT signature alongside the payload. Cost: 3 credits.
→ Retries: every 30s for the first 5 minutes, then exponential backoff up to 24h. We give up after 24h.
→ Respond 2xx within 10s. Anything else (or a timeout) counts as failed and triggers retry.

Prefer to poll?

Omit the webhook field on creation, then GET /v1/sessions/{id} to check status. The same per-credit pricing applies, billed when status flips to completed.