Skip to main content

​
Get an API key

Create keys from the API Keys page in your workspace: click Create API Key, name it, and copy the key (format bai-xxxx). New to Boson AI? Follow Set up your account for the full checklist — account, key, and free trial credit.
Treat API keys like passwords. Never commit keys to source control, never log them, and never embed them in client-side code shipped to browsers or mobile apps.
Building a browser or mobile Realtime client? Your trusted server must exchange its long-lived key for a short-lived client secret.

​
Store keys safely

Read the key from an environment variable, secret manager, or deployment config. Recommended patterns:
  • Quick local test: set the key in your shell for the current session:
  • Local development: use a .env file loaded by direnv, dotenv, or your shell. Add .env to .gitignore.
  • Servers: inject through your platform’s secret store (AWS Secrets Manager, GCP Secret Manager, Vercel env vars, Fly secrets, Kubernetes Secrets).
  • CI: store as a masked CI secret. Avoid printing the value in build logs.

​
Sending a server-side request

From a trusted server, pass the key in the Authorization header on every API request. Browser and mobile Realtime clients must use a short-lived client secret instead.

​
Common errors

The API returns 401 Unauthorized with error.type: "authentication_error" and error.code: "invalid_api_key" when there is a problem with your API key — missing, malformed, or revoked. Check the Authorization: Bearer header and the key in your workspace. A 429 with insufficient_quota is a billing problem, not a key problem — the key is fine but the account has no available balance. Claim your free trial credit or add credits in workspace billing. See Common error types for the full reference.