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.

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.