Skip to content

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 ​

ScopeResourceActionDescription
client:readPartner clientsReadRead access to partner client endpoints
client:writePartner clientsWriteWrite access to partner client endpoints
user:readUsersReadRead access to user endpoints
user:writeUsersWriteWrite access to user endpoints
patient:readPatientsReadRead access to patient endpoints
patient:writePatientsWriteWrite access to patient endpoints
provider:readProvidersReadRead access to provider endpoints
provider:writeProvidersWriteWrite access to provider endpoints
appointment:readAppointmentsReadRead access to appointment endpoints
appointment:writeAppointmentsWriteWrite access to appointment endpoints
record:readMedical recordsReadRead access to medical record endpoints (read-only)
file:readPatient filesReadRead 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 (requires client:read / client:write)
  • GET/POST/PUT/DELETE /partners/apiKeys/* — API key management (requires client: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:

json
{
  "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:write if 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:

json
{
  "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:

  1. Verify you're using the correct API key
  2. Check that the API key has the required scopes
  3. If needed, create a new API key with the required scopes
  4. 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:

json
{
  "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.

Vivlio Health API Documentation