Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.vobiz.ai/llms.txt

Use this file to discover all available pages before exploring further.

Vobiz uses two separate token systems. They are easy to confuse, so it helps to keep them straight from the start.
  • Access token (JWT) — a short-lived bearer token you use for console / dashboard API calls. Refreshed via POST /auth/refresh.
  • Auth token (X-Auth-Token) — a long-lived API key, paired with your auth_id, used for the REST and telephony API (placing calls, etc.). Rotated via POST /auth-token/rotate.
They are unrelated. Refreshing one has no effect on the other.

​
The three tokens at a glance

TokenWhat it isLifetimeUsed forRenewed by
Access token (JWT)Short-lived bearer token issued at login30 minutesConsole / dashboard API callsPOST /auth/refresh
Refresh token (JWT)Long-lived token that mints new access tokens7 daysOnly to call /auth/refreshRe-issued automatically by /auth/refresh
Auth token (X-Auth-Token)Long-lived API key (paired with auth_id)Until rotatedREST / telephony API authPOST /auth-token/rotate
A single call to POST /auth/refresh returns both a new access token and a new refresh token — there is no separate refresh-token endpoint. The X-Auth-Token API key is a different mechanism with its own rotation flow (see Auth-token rotation).

​
Access tokens (JWT)

Access tokens authenticate console and dashboard requests. This flow applies to main accounts, sub-accounts, and team members — all use the same endpoints, and the identity is taken from the token itself. Base URL: https://api.vobiz.ai/api/v1

​
You start with a token pair

When you log in to the console, you receive an access token and a refresh token: 
{
  "access_token": "eyJhbGciOiJI...",
  "refresh_token": "eyJhbGciOiJI...",
  "token_type": "bearer",
  "expires_in": 1800
}
expires_in is in seconds — 1800 is 30 minutes. From here, use the refresh token to keep your access token alive.

​
Refresh the access token

When the access token has expired (or is about to), send the refresh token as the bearer credential — not in the body:
cURL
curl -X POST https://api.vobiz.ai/api/v1/auth/refresh \
  -H "Authorization: Bearer <REFRESH_TOKEN>"
Response (200 OK)
{
  "access_token": "eyJhbGciOiJI...",
  "refresh_token": "eyJhbGciOiJI...",
  "token_type": "bearer",
  "expires_in": 1800
}
One call refreshes both tokens. Always store the new refresh_token from the response and use it for the next refresh — this is a sliding window. A 401 Unauthorized means the refresh token is missing, invalid, expired, or was invalidated early by a logout or password change.
Notes
  • Same flow for main accounts and sub-accounts — a sub-account simply presents its own refresh token. There is no separate sub-account refresh endpoint.
  • The refresh token is valid for 7 days; refreshing does not shorten it. It is invalidated early by logout or password change.

​
Auth-token rotation

The auth token is the long-lived API key (X-Auth-Token, paired with auth_id) used to authenticate REST and telephony API requests. Rotation supports an optional grace window so the old key keeps working while you roll out the new one — zero downtime.
Authentication for these endpoints: the bearer access token (JWT) of the account owner. Log in first, then call these with Authorization: Bearer <ACCESS_TOKEN>.

​
Request body

All rotate endpoints accept the same body:
FieldTypeDefaultDescription
grace_period_hoursinteger (0–24)24How long the previous key keeps working. 0 = immediate cutover (old key dies at once).
forcebooleanfalseRequired (true) if a previous key is still inside its grace window.
cURL
curl -X POST https://api.vobiz.ai/api/v1/accounts/{auth_id}/auth-token/rotate \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{ "grace_period_hours": 24, "force": false }'
Rotate response
{
  "new_auth_token": "…64-hex…",
  "previous_token_expires_at": "2026-05-28T08:00:00Z",
  "rotated_at": "2026-05-27T08:00:00Z"
}
new_auth_token is returned once and cannot be retrieved later — store it immediately. previous_token_expires_at is null when grace_period_hours is 0.

​
Endpoints

The same rotate / revoke / status actions exist for main accounts, sub-accounts, and partner-managed customers. Main account
ActionMethod & Path
RotatePOST /accounts/{auth_id}/auth-token/rotate
Revoke previous key nowDELETE /accounts/{auth_id}/auth-token/previous
StatusGET /accounts/{auth_id}/auth-token/status
Sub-account (rotated by the parent main account)
ActionMethod & Path
RotatePOST /accounts/{ma_auth_id}/sub-accounts/{sa_auth_id}/auth-token/rotate
Revoke previousDELETE /accounts/{ma_auth_id}/sub-accounts/{sa_auth_id}/auth-token/previous
StatusGET /accounts/{ma_auth_id}/sub-accounts/{sa_auth_id}/auth-token/status
The parent authenticates with its own access token and may only rotate sub-accounts it owns — otherwise the request returns 403.
Partner (rotating a managed customer’s key)
ActionMethod & Path
RotatePOST /partner/accounts/{customer_auth_id}/auth-token/rotate
Revoke previousDELETE /partner/accounts/{customer_auth_id}/auth-token/previous
StatusGET /partner/accounts/{customer_auth_id}/auth-token/status

​
Status response

{
  "rotated_at": "2026-05-27T08:00:00Z",
  "previous_token_active": true,
  "previous_token_expires_at": "2026-05-28T08:00:00Z"
}

​
Behavior & errors

  • Grace window — when grace_period_hours > 0, both the new and previous keys authenticate until previous_token_expires_at. Roll the new key out to all callers, then let it lapse or revoke it early via the …/auth-token/previous DELETE.
  • Immediate cutover — grace_period_hours = 0 invalidates the old key instantly (the legacy “regenerate credentials” behavior).
  • 409 Conflict — a previous key is still inside its grace window. Pass force: true to discard it and rotate again, or DELETE …/auth-token/previous first.
  • 403 Forbidden — attempting to rotate an account or sub-account you don’t own.

​
FAQ

Call POST /auth/refresh with your refresh token as the bearer credential. You get a new access and refresh token back. The same endpoint works for main accounts and sub-accounts.
No. The refresh token is re-issued automatically inside the /auth/refresh response. Just store the new one each time.
No. Access and refresh tokens are JWTs for the console API. The X-Auth-Token API key is a separate, long-lived credential rotated with a grace window.