Authentication

API keys

Every request must include a valid API key. Keys look like vx_live_3fa9c2... and carry both your identity and your scope. Pass the key as a bearer token in the Authorization header:

Authorization: Bearer vx_live_3fa9c2...

Alternatively, you can send the key in the x-api-key header. Use whichever fits your HTTP client — never both at once.

x-api-key: vx_live_3fa9c2...

All requests must be made over HTTPS. Plain HTTP requests are rejected before they reach the API, so your key is never transmitted in the clear.

Key scopes

Keys come in two scopes. The scope fixes which endpoints a key can reach and which account it acts on. The account is derived from the key itself — you never pass an agency_id or sub_account_id in the request. Using a key on an endpoint outside its scope returns 403 Forbidden.

• AGENCY — reaches agency-level endpoints such as /v1/agency and /v1/agency/sub-accounts. Acts on the owning agency. Cannot reach sub-account resource endpoints.
• SUB-ACCOUNT — reaches resource endpoints such as /v1/agents, /v1/contacts, and /v1/calls. Acts on the owning sub-account. Cannot reach agency endpoints.

Because the tenant is encoded in the key, an AGENCY key on a sub-account endpoint — or a SUB-ACCOUNT key on an agency endpoint — is a scope mismatch and is rejected with 403.

Making authenticated requests

Attach your key to each request. The example below lists agents for the sub-account that owns the key:

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

The same request using the x-api-key header:

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

Unauthorized responses

A missing, malformed, or invalid key returns 401 Unauthorized:

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

A valid key used outside its scope returns 403 Forbidden:

{
  "success": false,
  "message": "This API key does not have access to this resource"
}

Security best practices

• Never expose keys client-side. Secret keys belong on your server — never in browser code, mobile apps, or any artifact shipped to end users.
• Rotate regularly. Roll keys on a schedule and immediately if one may have leaked.
• Scope minimally. Use a SUB-ACCOUNT key for resource work and reserve AGENCY keys for agency operations.
• Store in environment variables. Load keys from env vars or a secrets manager — never commit them to source control.