Skip to main content
Every public request carries an API key in the X-API-Key header. The gateway resolves the key to a user and injects identity downstream — you never pass a user id or subject yourself; the server derives it from the key. 
-H "X-API-Key: <API_KEY>"

​
Base URL

DeploymentAPI base
Self-hosted (make all / compose)http://localhost:18056 (API_GATEWAY_HOST_PORT)
Hostedhttps://api.cloud.vexa.ai

​
Getting a key

make all mints a key as part of bring-up and prints it (along with the service URLs) when the stack is ready — copy it from the make all output and use it as your X-API-Key.

​
Minting more keys

To mint additional keys, use the provision-token make target with your ADMIN_TOKEN (it’s set in .env, default dev-admin-token — change it before exposing anything): 
make -s provision-token ADMIN_TOKEN=dev-admin-token
# → prints a freshly minted vxa_... API key
Under the hood the admin API mints keys. It listens on http://localhost:18057 by default (ADMIN_API_PORT) and is protected by ADMIN_TOKEN via the X-Admin-API-Key header — you can call it directly for finer control over users and scopes: 
export ADMIN=http://localhost:18057
export ADMIN_TOKEN=dev-admin-token        # your ADMIN_TOKEN from .env

# 1. create (or find) a user
curl -X POST "$ADMIN/admin/users" \
  -H "X-Admin-API-Key: $ADMIN_TOKEN" -H "Content-Type: application/json" \
  -d '{"email":"jane@acme.com","name":"Jane","max_concurrent_bots":2}'
# → {"id":1,"email":"jane@acme.com","name":"Jane","max_concurrent_bots":2}

# 2. mint a key for that user id
curl -X POST "$ADMIN/admin/users/1/tokens?scopes=bot,tx" \
  -H "X-Admin-API-Key: $ADMIN_TOKEN"
# → {"id":7,"token":"vxa_bot_...","user_id":1,"scopes":["bot","tx"]}
The returned token is your X-API-Key. It is shown once — store it.

​
Scopes

A key carries one or more scopes. Pass scope=<one> or scopes=<a>,<b> when minting.
ScopeGrants
botsend and manage meeting bots, read transcripts
txtranscription / transcript access
browserbrowser-tool capabilities
Keys are prefixed by their primary scope — vxa_bot_…, vxa_tx_…, vxa_browser_…. A key without a recognized scope is rejected.

​
Rotating and revoking

Mint a new key, switch your clients over, then delete the old one by its token id: 
curl -X DELETE "$ADMIN/admin/tokens/7" -H "X-Admin-API-Key: $ADMIN_TOKEN"   # → 204
Set an expiry at mint time with expires_in=<seconds>; expired keys are rejected automatically.

​
What can go wrong

StatusdetailMeaning
401Missing API keyno X-API-Key header
401Invalid API keyunknown or revoked key
403Token scope not authorizedkey lacks the scope this route needs
See the full error reference.