Authentication

API Key Format

VoiceAgent API keys are secret strings prefixed with vak_. Treat the full value like a password. Store it in a secret manager or environment variable, never in browser code, mobile apps, logs, or source control.

Where To Get Keys

Workspace admins can create API keys in the Dashboard at /api-keys. Copy the secret when it is created; after that, store only the secret in your integration environment.

Request Headers

The API accepts two equivalent header styles:

Authorization: Bearer vak_...
X-API-Key: vak_...

Use one header per request. If Authorization contains a vak_ token, VoiceAgent validates that token before checking X-API-Key.

Rotation

Key rotation is planned as part of the Phase 5 hardening work for #42. Until rotation tooling is available, create a replacement key, deploy it to your integration, verify traffic, and then revoke the old key from the Dashboard.

Scopes

Public routes enforce API key scopes. Choose the smallest concrete scopes that cover your integration, and review high-risk grants before using them in automated systems.

See Scope reference for the canonical scope list, wildcard policy, and OpenAPI metadata fields.

Authentication Failures

Missing, invalid, or expired API keys return 401 Unauthorized with the canonical error envelope:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired API key"
  }
}