Skip to main content
API tokens can be scoped to limit what they can access. A bot-only token cannot manage users, and a transcription-only token cannot start bots. This follows the principle of least privilege.

​
Token format

Scoped tokens use a prefix that identifies the scope: 
vxa_<scope>_<random>
Examples:
  • vxa_bot_VDXyV683YBvsCRrlUtnWWKLC0qTtGNaxGgVS8F5s — bot scope
  • vxa_tx_eFgh1234abcd5678... — transcription scope
  • vxa_browser_xyz789... — browser scope
Legacy tokens (without the vxa_ prefix) retain full access for backward compatibility.

​
Scopes

ScopePrefixAccess
botvxa_bot_Bot operations: start/stop bots, check bot status, webhooks, voice agent
txvxa_tx_Transcription and meeting data access: view meetings, read transcripts
browservxa_browser_Browser sessions: VNC, CDP, workspace

​
Enforcement

Scope enforcement happens at the service level, not the gateway. Each backend service declares which scopes it accepts:
ServiceEndpoint examplesAllowed scopes
meeting-apiPOST /bots, GET /bots/statusbot
meeting-apiGET /meetings, GET /transcriptstx
api-gatewayPOST /browser-sessionsbrowser
A request with an out-of-scope token receives 403 Forbidden: 
{
  "detail": "Token scope not authorized for bot management"
}

​
Creating scoped tokens

Create tokens via the admin API: Single scope: 
curl -X POST "https://your-vexa-host/admin/users/{user_id}/tokens?scope=bot" \
  -H "X-Admin-API-Key: YOUR_ADMIN_KEY"
Multiple scopes (comma-separated): 
curl -X POST "https://your-vexa-host/admin/users/{user_id}/tokens?scopes=bot,tx" \
  -H "X-Admin-API-Key: YOUR_ADMIN_KEY"
Response: 
{
  "user_id": 1,
  "id": 42,
  "token": "vxa_bot_VDXyV683YBvsCRrlUtnWWKLC0qTtGNaxGgVS8F5s",
  "created_at": "2026-03-23T10:00:00"
}
The scope parameter accepts: bot, tx, browser. Use scopes (plural) with comma-separated values to grant multiple scopes to a single token.

​
Using scoped tokens

Use scoped tokens the same way as regular tokens — via the X-API-Key header: 
# This works — bot scope can access bot endpoints
curl -H "X-API-Key: vxa_bot_VDXyV683Y..." \
  https://your-vexa-host/bots/status

# This fails with 403 — bot scope cannot access transcript endpoints
curl -H "X-API-Key: vxa_bot_VDXyV683Y..." \
  https://your-vexa-host/transcripts/google_meet/abc-defg-hij

​
Legacy tokens

Tokens created before scoping was introduced have no vxa_ prefix. These tokens retain full access to all endpoints for backward compatibility. To migrate a legacy token to a scoped token:
  1. Create a new scoped token with the desired scope
  2. Update your application to use the new token
  3. Revoke the legacy token via DELETE /admin/tokens/{id}

​
Revoking tokens

curl -X DELETE "https://your-vexa-host/admin/tokens/{token_id}" \
  -H "X-Admin-API-Key: YOUR_ADMIN_KEY"
Revoked tokens are immediately rejected on the next request.