Skip to content

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 endpoints
  • client: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.

List API Keys ​

Retrieve all API keys for the partner and its clients.

http
GET /ext/latest/partners/apiKeys
Authorization: Bearer {token}

Query Parameters:

ParameterTypeDefaultDescription
limitinteger10Page size (max: 100)
offsetinteger0Page offset

Sample Response ​

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

http
GET /ext/latest/partners/apiKeys/{apiKeyId}
Authorization: Bearer {token}

Path Parameters:

ParameterTypeDescription
apiKeyIdstringThe API key UUID

Sample Response ​

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

http
POST /ext/latest/partners/apiKeys
Content-Type: application/json
Authorization: Bearer {token}

Request Body:

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

FieldTypeRequiredDescription
clientIdstringyesUUID of the client this key belongs to
namestringyesDescriptive name for the key (e.g., "Production", "Testing")
expiresAtstringyesISO 8601 expiration date (future date required)
scopestring[]yesArray of scopes (e.g., ["user:read", "patient:write"])

Response (201 Created) ​

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

FieldDescription
idThe newly created API key's UUID
clientSecretThe plaintext secret — only returned once, store immediately
clientIdThe 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.
scopeThe 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.

http
PUT /ext/latest/partners/apiKeys/{apiKeyId}
Content-Type: application/json
Authorization: Bearer {token}

Path Parameters:

ParameterTypeDescription
apiKeyIdstringThe API key UUID

Request Body (all fields optional):

json
{
  "active": false,
  "expiresAt": "2027-06-20T00:00:00.000Z"
}

Request Fields:

FieldTypeDescription
activebooleanEnable or disable the key
expiresAtstringISO 8601 expiration date (future date required)

Sample Response ​

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

http
DELETE /ext/latest/partners/apiKeys/{apiKeyId}
Authorization: Bearer {token}

Path Parameters:

ParameterTypeDescription
apiKeyIdstringThe API key UUID

Response (204 No Content) ​

No response body is returned on successful deletion.


Field Reference ​

API Key Fields ​

FieldTypeRead-OnlyDescription
apiKeyIdstringyesUnique identifier for the API key
clientIdstringyesUUID of the associated client
namestringnoDescriptive name for the key
activebooleannoWhether the key is currently active/usable
expiresAtstringnoISO 8601 expiration timestamp
scopestring[]yesArray of scopes granted to this key
clientSecretstringyesSecret key (only returned at creation)

Usage Examples ​

Node.js Example ​

javascript
// 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 ​

python
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 ​

StatusCodeDescription
400VALIDATION_ERRORInvalid request parameters or body
401UNAUTHORIZEDMissing or invalid authentication
403FORBIDDENInsufficient scopes (client:write)
404RESOURCE_NOT_FOUNDAPI key or client not found
409RESOURCE_EXISTSAPI key with duplicate name
500INTERNAL_ERRORServer error processing request

Best Practices ​

Security ​

  • Store Secrets Safely — Save the clientSecret in 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

Vivlio Health API Documentation