Skip to main content
Every request authenticates with a bearer API key.
x-api-key: pyai_live_... is an accepted alias for environments where setting an Authorization header is awkward.
Keys are opaque strings (up to 512 characters). Never parse, split, or decode them. They are self-validating and work on every PyAI surface the instant they are created, there is no activation or propagation delay.

​
Environments

Create either in the console. The key is shown once, store it as a secret (environment variable), never in source control.

​
Scopes

Keys carry scopes that gate which products they can call: GET /v1/models and GET /v1/voices are catalog reads, any active key may call them. A request whose key lacks the required scope returns 403 forbidden.

​
WebSocket authentication

Browsers can’t set headers on a WebSocket upgrade, so pass the key as a subprotocol:
Server-side clients may instead append ?api_key=... to the URL. Never put the key in any other query parameter.

​
Rotation & revocation

Each key in the console has rotate and revoke controls.
  • Rotate issues a new secret and invalidates the old one.
  • Revoke disables the key everywhere within 60 seconds.
After revocation, calls with the old key return 401 unauthorized.
If a key is ever exposed, revoke it immediately and mint a new one, there is no penalty for rotating often.