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 it calls.

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 except evaluation definitions.	GET /external/v1/actorsGET /external/v1/encounters
patients:read	Read patient fields returned by encounter, document and evaluation responses.	Actor list, encounter list/detail, document list/detail, evaluation list/detail.	GET /external/v1/encountersGET /external/v1/documents
documents:read	Read document summaries and details for clinical documents, ambient transcripts, billing documents, and encounter checklists. This includes transcript content, phone-call numbers and call logs, selected billing codes, materialized checklist content, and document-linked audio metadata.	Actor, encounter and document routes.	GET /external/v1/documentsGET /external/v1/encounters/{encounter_id}/documents/{document_id}
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
evaluations:read	Read AI evaluations of your organization's staff conversations, including call summaries, scores, findings, rationales and transcript excerpts, and the evaluation definitions that describe them.	Evaluation routes.	GET /external/v1/evaluationsGET /external/v1/evaluations/{evaluation_id}GET /external/v1/evaluation-definitions

Route requirements

Route	Required scopes
GET /external/v1/actors	encounters:read, patients:read, documents:read
GET /external/v1/encounters	encounters:read, patients:read, documents:read
GET /external/v1/documents	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, patients:read, documents:read
GET /external/v1/encounters/{encounter_id}/documents/{document_id}/audio	encounters:read, documents:read, recordings:read
GET /external/v1/evaluations	encounters:read, patients:read, evaluations:read
GET /external/v1/evaluations/{evaluation_id}	encounters:read, patients:read, evaluations:read
GET /external/v1/evaluation-definitions	evaluations:read

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

Evaluation access

evaluations:read covers AI judgments about your staff as well as PHI, so no existing key has it. API keys can't be edited: create a new key with encounters:read, patients:read, and evaluations:read for an evaluation integration. Evaluation routes don't require documents:read; add it only if the integration also fetches the evaluated transcript from document detail or reads encounters and actors directly. The evaluation definitions route requires only evaluations:read.

A key receiving evaluation.completed webhooks needs the scopes of its follow-up route, GET /external/v1/evaluations/{evaluation_id}.

Order of checks

Authentication, route availability, organization-scope, 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.