API Keys
Manage API keys for your clients. API keys are used for secure, programmatic access to the Vivlio Health API with specific scopes and optional expiration dates.
Authentication
All API key endpoints require a Partner token with appropriate scopes.
Required scopes:
client:read— For GET endpointsclient:write— For POST/PUT/DELETE endpoints
Overview
API keys allow clients to authenticate with the API using client credentials flow. Each key can be scoped to specific permissions and set to expire at a specific date. Keys are associated with a client within your organization.
Quick Links
List API Keys
Retrieve all API keys for the partner and its clients.
GET /ext/latest/partners/apiKeys
Authorization: Bearer {token}Query Parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
limit | integer | 10 | Page size (max: 100) |
offset | integer | 0 | Page offset |
Sample Response
{
"data": [
{
"apiKeyId": "019d0716-6a88-70af-9ef4-50c1cc2bda86",
"clientId": "a587f055-12ff-4009-a4b2-6300f665f35e",
"name": "Production Key",
"active": true,
"expiresAt": "2027-04-01T00:00:00.000Z",
"scope": ["user:read", "patient:read"]
}
],
"limit": 10,
"offset": 0,
"total": 1,
"hasMore": false
}Get API Key
Retrieve a specific API key by ID.
GET /ext/latest/partners/apiKeys/{apiKeyId}
Authorization: Bearer {token}Path Parameters:
| Parameter | Type | Description |
|---|---|---|
apiKeyId | string | The API key UUID |
Sample Response
{
"data": {
"apiKeyId": "019d0716-6a88-70af-9ef4-50c1cc2bda86",
"clientId": "a587f055-12ff-4009-a4b2-6300f665f35e",
"name": "Production Key",
"active": true,
"expiresAt": "2027-04-01T00:00:00.000Z",
"scope": ["user:read", "patient:read"]
}
}Create API Key
Create a new API key for a client.
POST /ext/latest/partners/apiKeys
Content-Type: application/json
Authorization: Bearer {token}Request Body:
{
"clientId": "a587f055-12ff-4009-a4b2-6300f665f35e",
"name": "Example Key",
"expiresAt": "2027-04-20T00:00:00.000Z",
"scope": ["user:read", "user:write", "patient:read"]
}Request Fields:
| Field | Type | Required | Description |
|---|---|---|---|
clientId | string | yes | UUID of the client this key belongs to |
name | string | yes | Descriptive name for the key (e.g., "Production", "Testing") |
expiresAt | string | yes | ISO 8601 expiration date (future date required) |
scope | string[] | yes | Array of scopes (e.g., ["user:read", "patient:write"]) |
Response (201 Created)
{
"data": {
"id": "019d0716-6a88-70af-9ef4-50c1cc2bda86",
"clientId": "a587f055-12ff-4009-a4b2-6300f665f35e",
"scope": ["user:read", "user:write", "patient:read"],
"clientSecret": "sk_live_abc123def456..."
}
}Response Fields:
| Field | Description |
|---|---|
id | The newly created API key's UUID |
clientSecret | The plaintext secret — only returned once, store immediately |
clientId | The resolved clientId that was persisted. For client-level keys this is the target client. For partner-level keys (no clientId in the request), this is the partner's own id. |
scope | The scope array actually written — confirms what was granted |
Secret Only at Creation
The clientSecret is only returned once at key creation. Store it securely immediately. You will not be able to retrieve it later — if lost, you must delete and create a new key.
Confirm What Was Written
clientId and scope in the creation response reflect what was actually persisted, not just echoed from the request. This is particularly useful for partner-level keys where the effective clientId (the partner's own id) differs from the absence of a clientId in the request body.
Update API Key
Update an existing API key's status or expiration date.
PUT /ext/latest/partners/apiKeys/{apiKeyId}
Content-Type: application/json
Authorization: Bearer {token}Path Parameters:
| Parameter | Type | Description |
|---|---|---|
apiKeyId | string | The API key UUID |
Request Body (all fields optional):
{
"active": false,
"expiresAt": "2027-06-20T00:00:00.000Z"
}Request Fields:
| Field | Type | Description |
|---|---|---|
active | boolean | Enable or disable the key |
expiresAt | string | ISO 8601 expiration date (future date required) |
Sample Response
{
"data": {
"apiKeyId": "019d0716-6a88-70af-9ef4-50c1cc2bda86",
"clientId": "a587f055-12ff-4009-a4b2-6300f665f35e",
"name": "Example Key",
"active": false,
"expiresAt": "2027-06-20T00:00:00.000Z",
"scope": ["user:read", "user:write", "patient:read"]
}
}Delete API Key
Delete an API key permanently. This action cannot be undone.
DELETE /ext/latest/partners/apiKeys/{apiKeyId}
Authorization: Bearer {token}Path Parameters:
| Parameter | Type | Description |
|---|---|---|
apiKeyId | string | The API key UUID |
Response (204 No Content)
No response body is returned on successful deletion.
Field Reference
API Key Fields
| Field | Type | Read-Only | Description |
|---|---|---|---|
apiKeyId | string | yes | Unique identifier for the API key |
clientId | string | yes | UUID of the associated client |
name | string | no | Descriptive name for the key |
active | boolean | no | Whether the key is currently active/usable |
expiresAt | string | no | ISO 8601 expiration timestamp |
scope | string[] | yes | Array of scopes granted to this key |
clientSecret | string | yes | Secret key (only returned at creation) |
Usage Examples
Node.js Example
// Create a new API key
async function createApiKey(partnerToken, clientId) {
const response = await fetch(
'https://api.vivliohealth.io/ext/latest/partners/apiKeys',
{
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': `Bearer ${partnerToken}`
},
body: JSON.stringify({
clientId: clientId,
name: 'Production API Key',
expiresAt: '2027-12-31T23:59:59.000Z',
scope: ['user:read', 'patient:read', 'record:read']
})
}
);
return response.json();
}
// List all API keys
async function listApiKeys(partnerToken, limit = 10, offset = 0) {
const response = await fetch(
`https://api.vivliohealth.io/ext/latest/partners/apiKeys?limit=${limit}&offset=${offset}`,
{
headers: { 'Authorization': `Bearer ${partnerToken}` }
}
);
return response.json();
}
// Disable an API key
async function disableApiKey(partnerToken, apiKeyId) {
const response = await fetch(
`https://api.vivliohealth.io/ext/latest/partners/apiKeys/${apiKeyId}`,
{
method: 'PUT',
headers: {
'Content-Type': 'application/json',
'Authorization': `Bearer ${partnerToken}`
},
body: JSON.stringify({ active: false })
}
);
return response.json();
}Python Example
import requests
from datetime import datetime, timedelta
def create_api_key(partner_token, client_id, key_name):
"""Create a new API key for a client."""
expires_at = (datetime.now() + timedelta(days=365)).isoformat() + 'Z'
response = requests.post(
'https://api.vivliohealth.io/ext/latest/partners/apiKeys',
headers={'Authorization': f'Bearer {partner_token}'},
json={
'clientId': client_id,
'name': key_name,
'expiresAt': expires_at,
'scope': ['user:read', 'patient:read', 'record:read']
}
)
return response.json()
def list_api_keys(partner_token, limit=10):
"""Retrieve all API keys."""
response = requests.get(
f'https://api.vivliohealth.io/ext/latest/partners/apiKeys?limit={limit}',
headers={'Authorization': f'Bearer {partner_token}'}
)
return response.json()
def update_api_key(partner_token, api_key_id, active=None, expires_at=None):
"""Update an API key status or expiration."""
body = {}
if active is not None:
body['active'] = active
if expires_at:
body['expiresAt'] = expires_at
response = requests.put(
f'https://api.vivliohealth.io/ext/latest/partners/apiKeys/{api_key_id}',
headers={'Authorization': f'Bearer {partner_token}'},
json=body
)
return response.json()Error Responses
| Status | Code | Description |
|---|---|---|
| 400 | VALIDATION_ERROR | Invalid request parameters or body |
| 401 | UNAUTHORIZED | Missing or invalid authentication |
| 403 | FORBIDDEN | Insufficient scopes (client:write) |
| 404 | RESOURCE_NOT_FOUND | API key or client not found |
| 409 | RESOURCE_EXISTS | API key with duplicate name |
| 500 | INTERNAL_ERROR | Server error processing request |
Best Practices
Security
- Store Secrets Safely — Save the
clientSecretin a secure environment (e.g., environment variables, secrets manager, not in version control) - Rotate Keys Regularly — Create new keys and disable old ones on a schedule
- Use Minimal Scopes — Grant only the scopes required for your integration
- Monitor Key Activity — Track which keys are in use and disable unused keys
Lifecycle Management
- Set Expiration Dates — Always set an expiration date to enforce key rotation
- Track Key Purpose — Use descriptive names (e.g., "Production", "Staging", "Testing") to identify key purpose
- Audit Access — Regularly review your API keys and their associated scopes
- Disable Before Deleting — Consider disabling a key first if you want to monitor for continued usage before permanent deletion
