Scopes

Least-privilege access

Public API keys use additive read scopes. A request must include every scope required by the route.

Use the smallest scope set needed for the integration workflow. For example, a webhook receiver should grant only the union of scopes required for the follow-up routes that ChartHero has enabled for that receiver.

Scopes table

Scope	What it allows	Required for	Example routes
encounters:read	Read encounter records and use encounter context for related resources.	All public REST routes.	GET /external/v1/encountersGET /external/v1/encounters/{encounter_id}/documents/{document_id}
patients:read	Read patient fields returned by encounter list and detail responses.	Encounter list and encounter detail.	GET /external/v1/encountersGET /external/v1/encounters/{encounter_id}
documents:read	Read document summaries, document details, transcript content, and document-linked audio metadata.	All public REST routes.	GET /external/v1/encounters/{encounter_id}/documents/{document_id}GET /external/v1/encounters/{encounter_id}/documents/{document_id}/transcript
recordings:read	Request short-lived URLs for recording-backed audio when audio access is enabled.	Audio URL route only.	GET /external/v1/encounters/{encounter_id}/documents/{document_id}/audio

Route requirements

Route	Required scopes
GET /external/v1/encounters	encounters:read, patients:read, documents:read
GET /external/v1/encounters/{encounter_id}	encounters:read, patients:read, documents:read
GET /external/v1/encounters/{encounter_id}/documents/{document_id}	encounters:read, documents:read
GET /external/v1/encounters/{encounter_id}/documents/{document_id}/transcript	encounters:read, documents:read
GET /external/v1/encounters/{encounter_id}/documents/{document_id}/audio	encounters:read, documents:read, recordings:read

recordings:read is required only for the audio URL route. It does not grant access to encounter, patient, document, or transcript data by itself.

Evaluation order

Authentication, partner route enablement, and scope checks run before unsupported-query handling. After those route-level checks pass, unsupported query parameters are rejected before resource lookup. For example, a request that fails a scope check receives an authorization error rather than an unsupported_filter error.