Authentication

Vitable uses two types of credentials depending on your integration:

• API keys — for server-to-server requests (creating employers, managing employees, etc.)
• Bound access tokens — short-lived, employee-scoped tokens for the Employee Dashboard Widget

Getting an API Key

To get an API key, please reach out to our team. We’ll provide you with the credentials to access the Vitable API.

Your API key grants full access to your organization’s data. Keep it server-side only.

Never expose your API key in frontend code, public repositories, or client-side requests. Treat it like a password.

Server-Side Authentication

Include your API key as a Bearer token in the Authorization header:

curl -X GET https://api.vitablehealth.com/v1/employers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

import requests

response = requests.get(
    "https://api.vitablehealth.com/v1/employers",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
    },
)

data = response.json()

const response = await fetch("https://api.vitablehealth.com/v1/employers", {
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
})

const data = await response.json()

A successful request returns 200 with a JSON body. If authentication fails, you’ll receive:

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key"
  }
}

All timestamps in API requests and responses are in UTC, formatted as ISO 8601 (e.g., 2026-01-23T14:30:00+00:00).

Bound Access Tokens

The Employee Dashboard Widget requires a bound access token instead of your API key. A bound token is a short-lived session token scoped to a single employee — it can only access that employee’s data, providing row-level security in the browser.

Your server creates bound tokens by calling the Issue Access Token endpoint with your API key:

curl -X POST https://api.vitablehealth.com/v1/auth/access-tokens \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "bound_entity": {
      "type": "employee",
      "id": "empl_abc123"
    }
  }'

The response includes the token and its lifetime:

{
  "access_token": "vit_at_...",
  "expires_in": 3600
}

Your frontend uses this token to initialize the widget. The @vitable/connect SDK handles token refresh automatically — see the Employee Dashboard Widget guide for the full integration flow.

Field	Description
grant_type	Always "client_credentials"
bound_entity.type	Always "employee"
bound_entity.id	The Vitable employee ID the token is scoped to
access_token	The bound token to pass to the widget
expires_in	Token lifetime in seconds