Authentication
The Vivlio Health API uses token-based authentication via OAuth 2.0 client credentials flow.
Overview
To access the API, you need to obtain an access token by authenticating with your API key credentials. Once you have the access token, include it in the Authorization header of your API requests.
HTTPS Required
All API requests must be made over HTTPS. Calls made over plain HTTP will fail.
OAuth 2.0 Client Credentials Flow
The API uses the OAuth 2.0 client credentials grant type for server-to-server authentication.
Token Endpoint
POST /ext/latest/oauth/requestToken
Content-Type: application/jsonRequest Body
The request body varies depending on your API key type (Partner or Client):
Partner Authentication
{
"id": "{api_key_id}",
"clientId": "{partner_id}",
"clientSecret": "{client_secret}",
"grantType": "client_credentials"
}Client Authentication
Client tokens access patient records and clinical data. npi and purposeOfUse are required — omitting either returns HTTP 400. purposeOfUse must be ["TREAT"]; no other value is accepted.
{
"id": "{api_key_id}",
"clientId": "{client_id}",
"clientSecret": "{client_secret}",
"grantType": "client_credentials",
"npi": "{10-digit-npi}",
"purposeOfUse": ["TREAT"]
}Response
{
"token": "eyJhbGciOiJSUzI1NiIs..."
}The token is a signed JWT with a 60-minute TTL containing claims such as:
sub— Subject (user/API key ID)scope— Granted scopestokenType—PartnerorClientextensions— HL7 B2B authorization details
Using Your Token
Include the access token in the Authorization header of all API requests:
Authorization: Bearer {token}Example Request
curl -X GET \
https://api.vivliohealth.io/ext/latest/patients \
-H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."Token Expiration
Tokens expire after 60 minutes. When a token expires, you must request a new one:
async function refreshToken(apiKeyId, partnerId, clientSecret) {
const response = await fetch('https://api.vivliohealth.io/ext/latest/oauth/requestToken', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
id: apiKeyId,
clientId: partnerId,
clientSecret: clientSecret,
grantType: 'client_credentials'
})
});
const { token } = await response.json();
return token;
}Token Types
Partner Tokens
Issued to partner-type API keys. Partners manage clients and users — they do not access clinical data directly. npi and purposeOfUse are not required and are ignored if provided.
Permissions:
- View, create, update, and delete clients
- Manage API keys for themselves and their clients
Client Tokens
Issued to client-type API keys. Grants access to clinical endpoints: /patients, /providers, /appointments, and /records. npi and purposeOfUse: ["TREAT"] are required to obtain a client token.
Permissions:
- Based on assigned scopes
- Can only access data within their own organization
- Cannot access partner management endpoints
Security Best Practices
Keep Credentials Secure
- Never commit API keys to version control
- Use environment variables to store credentials
- Rotate keys regularly — especially if compromised
- Use HTTPS only — never send credentials over HTTP
- Limit scope — grant keys only the scopes they need
Example: Secure Token Management
const apiKeyId = process.env.VIVLIO_API_KEY_ID;
const clientId = process.env.VIVLIO_CLIENT_ID;
const clientSecret = process.env.VIVLIO_CLIENT_SECRET;
let cachedToken = null;
let tokenExpiry = null;
async function getValidToken() {
const now = Date.now();
// Use cached token if still valid (refresh 5 minutes before expiry)
if (cachedToken && tokenExpiry && now < tokenExpiry - 5 * 60 * 1000) {
return cachedToken;
}
// Request new token
const response = await fetch('https://api.vivliohealth.io/ext/latest/oauth/requestToken', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
id: apiKeyId,
clientId: clientId,
clientSecret: clientSecret,
grantType: 'client_credentials'
})
});
const { token } = await response.json();
cachedToken = token;
tokenExpiry = now + 60 * 60 * 1000; // 60 minutes from now
return token;
}Common Authentication Errors
401 Unauthorized
Possible causes:
- Missing or invalid access token
- Expired token (request a new one)
- Incorrect credentials
- Malformed Authorization header
Example error:
{
"error": {
"code": "FORBIDDEN",
"message": "Authentication failed",
"requestId": "..."
}
}403 Forbidden
Possible causes:
- API key lacks required scopes
- Token type doesn't have permission for this endpoint
Example error:
{
"error": {
"code": "FORBIDDEN",
"message": "The API key does not have the required scopes for the requested endpoint",
"requestId": "..."
}
}Need Help?
If you encounter authentication issues, verify:
- Your credentials are correct
- You're using the right token type (Partner vs. Client)
- Your API key has the required scopes
- Your token hasn't expired
