Authentication and scopes
Send a key or an OAuth token as a bearer token. Scopes decide which endpoints answer; data classes decide which fields come back.
Send a bearer token#
Authorization: Bearer claro_sk_live_au_...Send it to the base URL for the key's region: _au_ keys to https://api-au.claro.clinic/api/public/v1, _us_ keys to https://api-us.claro.clinic/api/public/v1.
Two kinds of credential work:
- An API key. Made by a clinic admin in Manage → Integrations → Developer tools → API Keys. It reaches that one clinic, and acts as the admin who made it.
- An OAuth access token. From an OAuth app (authorization code with PKCE), made under Developer tools → OAuth Apps. It acts as the person who approved it, at the clinics they can reach. A full OAuth guide is coming.
A signed-in Claro session is refused: 401 machine_credential_required. The public API is for software, not for the Claro apps.
When a credential stops working#
- Revoked or rotated in Developer tools, or its OAuth app revoked:
401 invalid_credentialon the next request. - The person it acts as leaves the clinic: it reaches no clinic, so clinic reads are
403 no_clinic_access.
Scopes#
A scope decides whether an endpoint answers at all. Missing one is 403 insufficient_scope.
| Scope | Label in Claro | Unlocks in v1 |
|---|---|---|
| none needed | GET /clinics, GET /clinics/{id} | |
patients:read | Read patients | GET /patients, GET /patients/{id}, and an appointment's patient |
appointments:read | Read appointments | GET /appointments, GET /appointments/{id} |
practitioners:read | Read practitioners | GET /practitioners, GET /practitioners/{id} |
events:read | Read webhook events (catch-up) | GET /events. See catching up. |
clinical_content:read | Read clinical content | An appointment's notes, with the clinic's opt-in (below) |
Some scopes include others: patients:write and clinical:read include patients:read, and appointments:write includes appointments:read.
Other scopes, such as patients:write, appointments:write and notes:read, exist for writes and resources the public API does not serve yet.
Data classes#
A scope opens an endpoint. The data class decides which fields come back. There are three.
| Class | What it covers | You need |
|---|---|---|
| Operational | Clinics, practitioners, appointment times, status and type | The endpoint's own scope |
| Clinical metadata | Who a patient is: names, date of birth, contact details, address. An appointment's patient. | patients:read |
| Clinical content | What was written about care. In v1, an appointment's notes. | clinical_content:read and the clinic's opt-in for your app |
- A field you may not see is absent, not
null.nullalways means "nothing recorded". - The opt-in is per clinic, per app. The clinic's owner or admin grants it in Manage → Integrations, under Apps that can read clinical content, and can withdraw it at any time. An app can't opt itself in. The Allow button appears only for an app that holds
clinical_content:read. - Patients need wide access. The person a credential acts as must see all of the clinic's patients in Claro. If not, patient reads are
403 patients_not_visible.
Never returned#
Government identifiers are never returned, whatever the scope: IHI, Medicare and DVA numbers in Australia, and practitioner provider and prescriber numbers. Nor are free-text fields written by or about a patient that are not yet classified.
Every field the API returns is on an explicit allowlist. See Privacy and security.