API Keys

API keys authenticate every request to the Vantax API. Each key is bound to a single tenant and scope, and the account it acts on is derived from the key itself — never from the request body.

Creating a key

Keys are created from the dashboard. Where you create the key determines its scope:

Sub-account keys — open the sub-account and go to Settings → API Keys. Give the key a descriptive name and create it.
Agency keys — go to your Agency settings → API Keys. Only agency owners and admins can mint agency keys.

The plaintext key is displayed once, at creation time. Copy it immediately and store it in a secret manager — you will not be able to view it again.

The key is shown only once

Vantax stores only a hash of your key, so the plaintext value cannot be recovered after the creation dialog closes. If you lose it, revoke the key and create a new one.

Key format

Live keys are prefixed with vx_live_ followed by a random secret:

vx_live_3fa9c2e1b7d84a06f5c2...

Treat the entire string as a secret. The server never persists the plaintext — it stores only a one-way hash and the key's metadata (scope, tenant, name, last-used time). At request time the presented key is hashed and compared, so a leaked key can be invalidated by revoking it without affecting any other credential.

Scopes

Every key has exactly one scope, and the scope is fixed at creation. The scope controls both which endpoints the key can reach and which tenant it acts on:

Agency keys reach agency-level endpoints such as /v1/agency and /v1/agency/sub-accounts, and act on the owning agency.
Sub-account keys reach resource endpoints such as /v1/agents, /v1/contacts, and /v1/calls, and act on the owning sub-account.

Tenant binding. The account a key operates on is derived from the key itself — you never pass an agency_id or sub_account_id in your requests. Using an agency key on a sub-account endpoint, or a sub-account key on an agency endpoint, returns 403:

{
  "success": false,
  "message": "This key cannot access this resource"
}

See Authentication for the full scope-to-endpoint mapping.

Using a key

Send your key on every request using either the Authorization bearer header or the x-api-key header — pick one:

# Authorization: Bearer
curl https://api.vantaxai.com/v1/agents \
  -H "Authorization: Bearer vx_live_3fa9c2..."

# x-api-key
curl https://api.vantaxai.com/v1/agents \
  -H "x-api-key: vx_live_3fa9c2..."

Both headers are equivalent. In code:

const res = await fetch("https://api.vantaxai.com/v1/agents", {
  headers: {
    Authorization: `Bearer ${process.env.VANTAX_API_KEY}`,
  },
});

const body = await res.json();
// { success: true, data: [ ... ], pagination: { ... } }

Load the key from an environment variable or secret manager — never commit it to source control or expose it in client-side code.

Rotating & revoking

To rotate a key, create a new one, deploy it to your integrations, then revoke the old key once traffic has moved over. Creating a key never invalidates existing keys, so rotations have zero downtime when staged this way.

Revoke disables the key immediately while keeping its record (name, scope, last-used time) for audit purposes. A revoked key can no longer authenticate.
Delete removes the key and its record entirely.

Both actions take effect immediately: any integration still presenting a revoked or deleted key starts receiving 401 on its next request, so swap in the new key first.

{
  "success": false,
  "message": "Invalid or revoked API key"
}

Limits

Each scope supports up to 25 active keys — that is, up to 25 per agency and up to 25 per sub-account. Revoked and deleted keys do not count toward the limit, so you can rotate freely.

If you reach the cap, revoke an unused key before creating another; attempting to exceed it returns a validation error:

{
  "success": false,
  "message": "Active API key limit reached for this scope"
}