OAuth Token Endpoint
Request access tokens for API authentication.
Endpoint
POST /ext/latest/oauth/requestToken
Content-Type: application/jsonAuthentication
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
{
"id": "{api_key_id}",
"clientId": "{partner_id}",
"clientSecret": "{client_secret}",
"grantType": "client_credentials"
}Fields:
id(required) — Your API key IDclientId(required) — Your partner IDclientSecret(required) — Your API key secretgrantType(required) — Must beclient_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.
{
"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 IDclientId(required) — Your client IDclientSecret(required) — Your API key secretgrantType(required) — Must beclient_credentialsnpi(required) — National Provider Identifier (10 digits)purposeOfUse(required) — Must be["TREAT"]— the only accepted value
Response
Success (200 OK)
{
"token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
}Response Fields:
token— JWT access token (60-minute TTL)
Error (400 Bad Request)
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Missing required field: clientSecret",
"requestId": "a1b2c3d4-5678-90ab-cdef-1234567890ab"
}
}Token Details
The returned JWT contains claims:
{
"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
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
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
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
| Status | Code | Message |
|---|---|---|
| 400 | VALIDATION_ERROR | Missing or invalid required fields |
| 401 | FORBIDDEN | Invalid credentials |
| 429 | RATE_LIMITED | Too many token requests |
| 500 | INTERNAL_ERROR | Server error |
Token Caching
Cache your tokens for the full 60-minute TTL to reduce authentication requests. Request a new token only when needed.
