Authentication and patient access

Availability: draft. Partner principal mapping and delegation policies must be established before these routes are enabled.

Choose the right credential

Credential Holder Draft lifetime Use
OAuth access token Partner backend 60 minutes Server-to-server API operations.
SDK token Patient application 15 minutes One user and approved interviewer/connection capabilities.
Embed bootstrap URL Practitioner browser 5 minutes One-time exchange into a bounded embed session.
Webhook signing secret Partner backend Until rotated Verify ENO event deliveries.

Use client credentials from the backend. Store secrets in managed secret storage and redact them from logs. Obtain the confirmed token URL during onboarding. Never submit client secrets through the documentation playground.

Scopes and grants answer different questions

A scope such as documents:read permits an operation. A Patient Access Grant permits access to a particular patient's whole record, category or record. Both must be satisfied. The verified integration Organisation comes from trusted identity binding, not a request-body organisation ID.

GET /users/{userId}/access-grants
Authorization: Bearer <backend-access-token>

The proposed grants:read endpoint returns only grants addressed to this integration's Organisation. Active, paused, revoked and expired states explain access. Nonclinical grant-state visibility requires its own Access-owned policy and never substitutes for an active clinical grant.

Consent to process health data, collect wearable data or conduct an interview is distinct from permission to disclose patient records to a clinic. A partner's ability to record consent must be verified; a supplied timestamp is not sufficient proof.

Summary counts, timeline events, historical snapshots, exports, review summaries and derived results must honor the same patient boundaries as individual observations. Restricted sources must not be disclosed indirectly through an evaluation result.

Patient identity and delegation

externalId is scoped to a partner relationship. Verified identity linking for an existing ENO patient is an onboarding decision. Matching an email alone must not link or reveal another clinic's patient.

SDK issuance and symptom submission need explicit authority for the intended patient. Requested permissions cannot expand the integration's approved authority. Practitioner identity in an embed must be verified or identified as a trusted partner assertion in audit.

Revocation and erasure

Recheck authorization when reading a resource, even if the integration previously read it. Expired grants, erasure fences and revoked integration credentials can invalidate access. Do not treat cached token validity as proof of continuing patient permission.

See the endpoint scope definitions and data semantics.

Stored-document processing requires documents:process and a current processing Access Decision plus applicable processing consent. documents:write alone does not authorise reprocessing. Operation receipts additionally require operations:read and operation-specific authority.

Partner API 0.1.0-draft.3 · Draft contract · Sandbox and SDK availability require confirmation.