Scopes
The API uses a least-privilege scope taxonomy: exactly one read scope per data domain, and no scope maps to more than one domain. v1 is read-only — there are no write scopes.
Each scope authorizes a single domain and limits responses to a fixed field
projection. The same field set is returned across single-record, list, and
aggregation responses. Fields outside the projection — and all internal fields
such as userId and credential hashes — are never returned.
The 13 scopes
| Scope | Data domain | Projected fields |
|---|---|---|
read:health-data | health-data (vitals/readings) | id, type, value, unit, timestamp, source |
read:aggregations | aggregations / summaries | summary shape only (derived) |
read:trends | trends | bucketized trend points only (derived) |
read:symptoms | symptoms | id, description, severity, timestamp |
read:medications | medications & adherence | id, name, dosage, frequency, condition, pattern |
read:conditions | conditions | id, name, severity, sinceDate |
read:allergies | allergies | id, name, severity, sinceDate |
read:appointments | appointments | id, title, dateTime, specialty, location |
read:weight | weight | id, weightKg, date |
read:mood | mood | id, mood, note, timestamp |
read:reports | reports | id, generatedAt, dateRange, summary |
read:profile | profile (demographics) | name, gender, dateOfBirth, bloodType |
read:ehr | EHR-derived data | id, resourceType, summary, timestamp |
How scopes are enforced
On every authenticated /api/v1 request, the platform:
- Resolves the single scope the endpoint requires.
- Rejects with
INSUFFICIENT_SCOPE(HTTP 403) if the token lacks that scope, or presents a scope not in this taxonomy. The error names the missing scope. - Rejects with
CONSENT_REQUIRED(HTTP 403) if no active consent grant covers that scope for the requesting client and target user.
A scope can never reach data outside its own domain.
Requesting scopes
Request only the scopes your app needs. Users can approve a subset, so design your app to degrade gracefully when some requested scopes are not granted.