Skip to content

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 ​

http
POST /ext/latest/oauth/requestToken
Content-Type: application/json

Request Body ​

The request body varies depending on your API key type (Partner or Client):

Partner Authentication ​

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

json
{
    "id": "{api_key_id}",
    "clientId": "{client_id}",
    "clientSecret": "{client_secret}",
    "grantType": "client_credentials",
    "npi": "{10-digit-npi}",
    "purposeOfUse": ["TREAT"]
}

Response ​

json
{
  "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 scopes
  • tokenType — Partner or Client
  • extensions — HL7 B2B authorization details

Using Your Token ​

Include the access token in the Authorization header of all API requests:

http
Authorization: Bearer {token}

Example Request ​

bash
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:

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

javascript
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:

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

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

  1. Your credentials are correct
  2. You're using the right token type (Partner vs. Client)
  3. Your API key has the required scopes
  4. Your token hasn't expired

Vivlio Health API Documentation