Authentication

Authenticate Boson API requests with a Bearer token.

Get an API key

• Go to boson.ai/workspace and sign up for a free Boson account.
• Complete the account setup and verification steps.
• Log in and open the API Keys page.
• Click Create API Key and give the key a descriptive name.
• Copy the key. Boson API keys use the format bai-xxxx; store yours securely.

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:

  export BOSON_API_KEY=bai-xxxx
  

• 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.

cURL

curl https://api.boson.ai/v1/audio/speech \
  -H "Authorization: Bearer $BOSON_API_KEY"

Common errors

The API returns 401 Unauthorized when there is a problem with your API key. Common causes include:

Code	Cause
invalid_api_key	Key missing, malformed, or revoked.
insufficient_quota	Credits are exhausted or a hard limit has been reached.
permission_denied	Key is valid but lacks access to the requested resource.