Authorization
The Vivlio Health API implements scope-based access control. Each API key is assigned scopes that determine which endpoints it can access.
Scopes Overview
Scopes are validated per endpoint by a custom API Gateway authorizer. They follow a resource:action naming convention.
Current Scopes
| Scope | Resource | Action | Description |
|---|---|---|---|
client:read | Partner clients | Read | Read access to partner client endpoints |
client:write | Partner clients | Write | Write access to partner client endpoints |
user:read | Users | Read | Read access to user endpoints |
user:write | Users | Write | Write access to user endpoints |
patient:read | Patients | Read | Read access to patient endpoints |
patient:write | Patients | Write | Write access to patient endpoints |
provider:read | Providers | Read | Read access to provider endpoints |
provider:write | Providers | Write | Write access to provider endpoints |
appointment:read | Appointments | Read | Read access to appointment endpoints |
appointment:write | Appointments | Write | Write access to appointment endpoints |
record:read | Medical records | Read | Read access to medical record endpoints (read-only) |
file:read | Patient files | Read | Read access to patient file endpoints (read-only) |
Token Types and Access
Partner Tokens
Partner tokens grant access to partner-level endpoints for managing clients and API keys.
Available endpoints:
GET/POST/PUT/DELETE /partners/clients/*— Client management (requiresclient:read/client:write)GET/POST/PUT/DELETE /partners/apiKeys/*— API key management (requiresclient:read/client:write)
Note: Partners cannot directly access patient, provider, appointment, or medical record endpoints. They manage their clients' access through API keys.
Client Tokens
Client tokens grant access to client-level endpoints based on assigned scopes.
Available endpoints (no extra scope required):
GET/PUT /client— Client self-service
Available endpoints with user:read / user:write:
GET/POST/PUT/DELETE /users/*
Available endpoints with patient:read / patient:write:
GET/POST/PUT/DELETE /patients/*POST /patients/batch— Batch upsert
Available endpoints with provider:read / provider:write:
GET/POST/PUT/DELETE /providers/*
Available endpoints with appointment:read / appointment:write:
GET/POST/PUT/DELETE /appointments/*
Available endpoints with record:read:
GET /patients/{id}/records/*— All medical record endpoints (read-only)
Available endpoints with file:read:
GET /patients/{id}/files*— Patient files (read-only)
Scope Assignment
Scopes are assigned when you create an API key. You can specify multiple scopes separated by commas:
{
"name": "Patient Management Key",
"expiresAt": "2027-04-20T00:00:00.000Z",
"scope": "patient:read,patient:write,appointment:read"
}Least Privilege Principle
Follow the principle of least privilege when assigning scopes:
- Grant only necessary scopes — Don't assign
client:writeif you only need to read clients - Use separate keys for different functions — Consider having one key for read-only analytics and another for write operations
- Rotate keys regularly — Especially after key compromise or personnel changes
- Audit scope usage — Review which scopes your keys actually use
Best Practice
Create multiple API keys with different scope combinations for different services or integrations. This limits the impact if a key is compromised.
Permission Errors
If your API key lacks the required scopes for an endpoint, the API returns a 403 Forbidden error:
{
"error": {
"code": "FORBIDDEN",
"message": "The API key does not have the required scopes for the requested endpoint",
"requestId": "a1b2c3d4-5678-90ab-cdef-1234567890ab"
}
}To fix this:
- Verify you're using the correct API key
- Check that the API key has the required scopes
- If needed, create a new API key with the required scopes
- Contact your partner administrator if you need additional scopes
Data Isolation
API keys are scoped to specific clients and cannot access data from other clients:
- Client keys — Can only access data for their own client
- Partner keys — Can only manage clients and API keys belonging to their partner
- Cross-client access — Not permitted; each key can only access data within its authorization boundary
No Cross-Client Access
Even with broad scopes, an API key cannot access data from clients other than those it's authorized for. Data isolation is enforced at the API Gateway and database query levels.
Viewing Your Scopes
When you request a token, the JWT contains a scope claim listing all scopes granted to that key:
{
"sub": "api_key_id",
"clientId": "client_id",
"scope": ["user:read", "user:write", "patient:read"],
"tokenType": "Client",
"iat": 1234567890,
"exp": 1234571490
}You can decode your JWT (using jwt.decode() or an online JWT decoder) to verify your scopes.
Never Log Tokens
Do not log or store complete tokens in debug output. Only the requestId should be used for support tickets.
