Environments

Keep base URLs, secrets, and actor tokens separated by environment.

Public discovery can run against production, and sandbox keys are self-serve for everyone. Live-mode workflows need an approved identity session or OpenDoc-issued agent/provider token, and secrets must stay in 1Password, Coolify, or approved platform env storage.

Production APIhttps://api.opendoc.com

Local defaulthttp://localhost:3010

DiscoveryGET /protocol

Base URLs

Route by environment, not by guesswork.

api.opendoc.comProduction protocol API. Public reads and sandbox-key traffic run here today; live-mode integrations open with the first design partners.

localhost:3010Local protocol API when running @opendoc/protocol locally.

docs.opendoc.comTechnical docs and API reference. Not an API origin.

dev.opendoc.comDeveloper and partner landing surface. Not the protocol origin.

Tokens

There is no generic API key that bypasses OpenDoc authorization.

Current protected flows use OIDC identity sessions or OpenDoc-issued delegated tokens. The identity provider authenticates; OpenDoc resolves the caller to an actor and applies provider/SCP ownership, patient ownership, consent, spending, route policy, and audit rules. Self-serve developer keys exist, but they are sandbox-scoped by construction: they cannot reach real money or real PHI.

OIDC bearerApproved on-prem identity input. Required for browser/provider/workforce identity flows once mapped to protocol-owned rows.

patient_agentDelegated patient authority minted through the agent-token flow. Carries permissions, data tier, expiry, and spending limits.

provider_agentDelegated provider/SCP authority for headless operational integrations where route policy allows it.

publicDiscovery routes such as /search, /providers, /offers, /health, and /protocol.

odk_sandbox_Live today for everyone: instant self-serve key from signup. Runs the full state machine against a synthetic provider with simulated payments.

odk_live_Live-mode developer key. Granted per-partner; opens with the first design partners.

Runtime env

Production values live in Coolify/server env storage.

Local development reads an untracked .env. Production values are set in Coolify/server env storage and credential custody lives in 1Password vaults. Do not commit secrets or paste them into docs, screenshots, logs, or chat.

OPENDOC_PROTOCOL_URL=https://api.opendoc.com
OIDC_ISSUER_URL=https://idp.example/realms/opendoc
OIDC_AUDIENCE=opendoc-protocol
OIDC_ALLOWED_ALGORITHMS=RS256
TRUSTED_ORIGINS_EXTRA=https://partner.example
STRIPE_SECRET_KEY=sk_live_...
STRIPE_WEBHOOK_SECRET=whsec_...

Use names in docs, never values. Secret values belong in 1Password, Coolify encrypted env storage, or the approved environment secret store for the runtime that consumes them.

CORS

Browser clients must be explicitly trusted.

The protocol exposes x-correlation-id and accepts authorization, JSON bodies, and the narrow internal-test headers used for controlled non-production smoke. Add partner origins with TRUSTED_ORIGINS_EXTRA only after they are approved.

# Comma-separated extra browser origins for the protocol API.
TRUSTED_ORIGINS_EXTRA=https://partner.example,https://app.partner.example