Authentication

Identity authenticates the actor. OpenDoc authorizes the action.

OpenDoc accepts approved identity sessions and OpenDoc-issued agent tokens, then resolves each request to an OpenDoc actor before route policy, consent, spending limits, and audit checks run.

Public discoveryGET /protocol
Identity sessionBearer OIDC JWT
DelegationBearer agent token

Auth surfaces

Use the narrowest authority that matches the caller.

No authPublic discovery and browsing: protocol map, provider search, HSOs, offers, Sure Price, and specialty lists.
OIDC JWTFirst-party patient, provider, SCP admin, or workforce sessions authenticated by an approved identity provider.
Agent tokenOpenDoc-issued delegated authority for a patient or provider. Tokens carry permissions, data tier, expiry, spending limits, and ecosystem identity.
odk_sandbox_Self-serve developer key from signup, live today for everyone. Acts as a dedicated synthetic patient; confined to the sandbox provider with simulated payments.
odk_live_Live-mode developer key. Granted per-partner by workforce approval; opens with the first design partners.

Developer keys

Sandbox keys are pre-authorized synthetic patients.

A developer key is a Bearer token like any other. POST /developers/signup returns an odk_sandbox_ key instantly, and the server provisions everything the ceremony below would otherwise require: the sandbox subject is created with an active Health Key at IA2 and Layer-2 BOOK and CANCEL consent already granted. The same authorization gates run on every call — a sandbox key simply passes them from the start, so you can drive the full transaction flow immediately (see the quickstart).

curl https://api.opendoc.com/transactions/declare-intent \
  -X POST \
  -H "Authorization: Bearer $OPENDOC_SANDBOX_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "providerHsoId": "<sandboxProviderHsoId from signup>" }'
Sandbox keys are structurally confined. They resolve to a synthetic patient, can only book the seeded sandbox offering, and payments are forced non-live — real money and real PHI are unreachable by construction. Live keys (odk_live_) are minted only by workforce approval.

Discovery

Ask the API what it supports.

The protocol endpoint is public and should be the first call for a new integration. It returns available routes, permissions, consent vocabulary, event types, auth requirements, and the current protocol version.

curl https://api.opendoc.com/protocol

Identity session

Call patient or provider routes with an approved identity session.

The exact sign-in ceremony depends on the deployed identity provider. Once the caller has an approved OpenDoc identity JWT, pass it as a Bearer token. OpenDoc still owns healthcare authorization after authentication.

curl https://api.opendoc.com/me/profile \
  -H "Authorization: Bearer $OPENDOC_IDENTITY_JWT"

Delegated authority

Grant an agent token from a patient-controlled Health Key.

Agent tokens are shown once when granted. Store the raw token securely; OpenDoc stores only a hash and token preview.

1
Create or read the Health Key.The patient must have an active Health Key before granting delegated authority.
2
Promote to IA2.IA2 is required before the patient can authorize transactions or grant agent tokens.
3
Grant Layer 2 consent.POST /agent-tokens requires GRANT_AGENT_TOKEN consent.
4
Mint the token.Set permissions, data tier, expiry, and spending limits during the grant.
curl https://api.opendoc.com/me/consent \
  -X POST \
  -H "Authorization: Bearer $OPENDOC_IDENTITY_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "layer": 2,
    "consentType": "GRANT_AGENT_TOKEN"
  }'

curl https://api.opendoc.com/agent-tokens \
  -X POST \
  -H "Authorization: Bearer $OPENDOC_IDENTITY_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "ecosystemId": "partner-app",
    "label": "Partner booking agent",
    "permissions": ["search", "BOOK", "READ_BOOKINGS"],
    "dataTier": 1,
    "spendingLimitCents": 100000,
    "spendingPeriod": "monthly",
    "singleTransactionMaxCents": 35000,
    "expiresAt": "2026-12-31T23:59:59.000Z"
  }'

Agent call

Use the granted token as a Bearer token.

Route policy checks the actor type and permissions on every call. For transactions, a patient agent generally needs BOOK for state transitions and READ_TRANSACTIONS or READ_BOOKINGS for reads.

curl https://api.opendoc.com/events \
  -H "Authorization: Bearer $OPENDOC_AGENT_TOKEN"
Do not treat agent tokens as generic API keys. They are patient- or provider-originated authority with explicit scope, expiry, revocation, spending limits, and audit trails.