BreezeDocs
Get API key

Authentication

Most endpoints take an API key in the xi-api-key header. Account-management endpoints (e.g. /v1/api-keys) require a browser session. Create keys on the API keys page, or use breeze login to create a device-specific CLI key.

Sending your API key

Breeze accepts the key two ways. Both are equivalent.

  • xi-api-key header
  • Authorization: Bearer <key> header (standard HTTP)

When both are present, xi-api-key takes precedence.

curl # xi-api-key curl https://api.breeze.blue/v1/voices \ -H "xi-api-key: $BREEZE_API_KEY" # or Bearer curl https://api.breeze.blue/v1/voices \ -H "Authorization: Bearer $BREEZE_API_KEY" xi-api-key http GET /v1/voices HTTP/1.1 Host: api.breeze.blue xi-api-key: brz_xxxxxxxxxxxxxxxx Bearer http GET /v1/voices HTTP/1.1 Host: api.breeze.blue Authorization: Bearer brz_xxxxxxxxxxxxxxxx
# xi-api-key
curl https://api.breeze.blue/v1/voices \
  -H "xi-api-key: $BREEZE_API_KEY"

# or Bearer
curl https://api.breeze.blue/v1/voices \
  -H "Authorization: Bearer $BREEZE_API_KEY"

Key lifecycle

  • Keys have a stable key_id, prefix, and status. Breeze returns the plaintext api_key only when you create or rotate a key. Store it immediately; it cannot be viewed again.
  • CLI login keeps the same hash-only key model. The browser authorizes a short login flow, then the CLI exchanges a local verifier for one plaintext key response and saves it in ~/.breeze.
  • Use key_id for key management, request-log attribution, and support investigations. API-key authenticated responses include x-breeze-api-key-id so you can confirm which key handled a request.
  • Status is active, expiring, or disabled. Disabled keys return 401 AUTH_REQUIRED immediately and can be re-enabled.
  • Delete a key to remove it entirely. Use one key per environment; the last-used timestamp surfaces stale keys.

Common errors

  • 401 AUTH_REQUIRED — missing, malformed, deleted, or disabled key.
  • 403 FORBIDDEN — valid key but no access to the resource.

See the full list on the errors page.