Skip to content

OAuth Token Endpoint ​

Request access tokens for API authentication.

Endpoint ​

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

Authentication ​

No authentication required. Use your API credentials in the request body.

Request Body ​

The request body differs between Partner and Client token requests. Partners manage clients and users — they do not access clinical data directly and do not require NPI or purpose-of-use. Clients access patient records and must supply both.

Partner Request ​

json
{
    "id": "{api_key_id}",
    "clientId": "{partner_id}",
    "clientSecret": "{client_secret}",
    "grantType": "client_credentials"
}

Fields:

  • id (required) — Your API key ID
  • clientId (required) — Your partner ID
  • clientSecret (required) — Your API key secret
  • grantType (required) — Must be client_credentials

Client Request ​

Client tokens access patient, medical record, user, and appointment endpoints. npi and purposeOfUse are required — the token endpoint returns HTTP 400 if either is missing.

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

Fields:

  • id (required) — Your API key ID
  • clientId (required) — Your client ID
  • clientSecret (required) — Your API key secret
  • grantType (required) — Must be client_credentials
  • npi (required) — National Provider Identifier (10 digits)
  • purposeOfUse (required) — Must be ["TREAT"] — the only accepted value

Response ​

Success (200 OK) ​

json
{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Response Fields:

  • token — JWT access token (60-minute TTL)

Error (400 Bad Request) ​

json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Missing required field: clientSecret",
    "requestId": "a1b2c3d4-5678-90ab-cdef-1234567890ab"
  }
}

Token Details ​

The returned JWT contains claims:

json
{
  "sub": "api_key_id",
  "clientId": "client_id_or_partner_id",
  "scope": ["user:read", "patient:read"],
  "tokenType": "Partner" | "Client",
  "iat": 1234567890,
  "exp": 1234571490,
  "extensions": {
    "hl7_b2b_authorization": { ... }
  }
}

Token expires after 60 minutes — Request a new token before expiration.

Examples ​

Node.js ​

javascript
async function getAccessToken() {
  const response = await fetch('https://api.vivliohealth.io/ext/latest/oauth/requestToken', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      id: process.env.API_KEY_ID,
      clientId: process.env.CLIENT_ID,
      clientSecret: process.env.CLIENT_SECRET,
      grantType: 'client_credentials'
    })
  });

  if (!response.ok) {
    throw new Error(`Token request failed: ${response.statusText}`);
  }

  const { token } = await response.json();
  return token;
}

Python ​

python
import requests

def get_access_token():
    response = requests.post(
        'https://api.vivliohealth.io/ext/latest/oauth/requestToken',
        json={
            'id': os.environ['API_KEY_ID'],
            'clientId': os.environ['CLIENT_ID'],
            'clientSecret': os.environ['CLIENT_SECRET'],
            'grantType': 'client_credentials'
        }
    )
    response.raise_for_status()
    return response.json()['token']

cURL ​

bash
curl -X POST https://api.vivliohealth.io/ext/latest/oauth/requestToken \
  -H "Content-Type: application/json" \
  -d '{
    "id": "YOUR_API_KEY_ID",
    "clientId": "YOUR_CLIENT_ID",
    "clientSecret": "YOUR_CLIENT_SECRET",
    "grantType": "client_credentials"
  }'

Error Responses ​

StatusCodeMessage
400VALIDATION_ERRORMissing or invalid required fields
401FORBIDDENInvalid credentials
429RATE_LIMITEDToo many token requests
500INTERNAL_ERRORServer error

Token Caching

Cache your tokens for the full 60-minute TTL to reduce authentication requests. Request a new token only when needed.

Vivlio Health API Documentation