Security

Minimize PHI, preserve audit context, and let OpenDoc authorize healthcare actions.

OpenDoc treats identity, authorization, consent, payment, audit, and clinical safety as protocol responsibilities. Integrators should avoid unnecessary patient data, keep tokens server-side, and include correlation IDs in every support path.

Auditappend-only
Support IDx-correlation-id
Dev datasynthetic only

PHI boundary

Send only the data the route needs.

Discovery routes are designed to operate without patient context. Protected patient, receipt, EHR, booking, and transaction routes may touch PHI and are subject to actor resolution, consent, audit, route policy, and response controls.

Allowed publicProvider NPI/public professional profile, HSO catalog, offer price rows, availability slots, protocol discovery, and health checks.
ProtectedPatient profile, Health Key, bookings, receipts, EHR-linked data, consent grants, and state-changing transactions.
Never in devProduction patient exports, anonymized production patient datasets, real PHI in local files, logs, AI prompts, or non-production databases.

Logging

Do not log patient data or token values.

Operational logs should record route, status, duration, and correlation context. Compliance evidence lives in append-only audit tables and transaction ledgers. Application logs must not contain raw patient identifiers, medical details, bearer tokens, webhook secrets, or Stripe secrets.

// Good support log shape
{
  "route": "/transactions/:id/commit",
  "status": 402,
  "errorCode": "payment_required",
  "correlationId": "2f3f0a4e-..."
}

Correlation

Carry the correlation ID through your system.

OpenDoc returns x-correlation-id on responses and includes the same value in error bodies. Partners may pass an inbound x-correlation-id for request-chain tracing.

try {
  await client.commit(transactionId, "partner-order-123-commit");
} catch (error) {
  if (error instanceof OpenDocError) {
    console.error({
      code: error.code,
      status: error.status,
      correlationId: error.correlationId,
    });
  }
}

Checklist

Minimum partner security posture.

1
Keep tokens server-side.Do not expose agent/provider tokens in browser local storage or client logs.
2
Store secrets in approved vaults.Use 1Password and runtime env storage. Do not commit secrets.
3
Preserve audit context.Store correlation IDs with support tickets and partner request traces.
4
Use synthetic data in tests.Never copy production patient data into local or staging environments.
5
Verify webhook signatures.Read the raw body and verify OpenDoc webhook HMAC signatures before processing events.