Authentication

How Speechbase API keys work — issuing, scoping, revoking, and the difference between Speechbase keys and provider keys.

Every Speechbase API request — except the public /health probe — requires an Authorization: Bearer <key> header.

Authorization: Bearer sk_a1b2c3d4...

Two kinds of keys, in one platform

This trips people up, so it's worth pinning down up front:

Key	Issued by	Used for
Speechbase API key	Speechbase	Authenticating your requests to `api.speechbase.ai`.
Provider key	Upstream provider (OpenAI, ElevenLabs, …)	Authenticating Speechbase's outbound call to that provider on your behalf.

The Speechbase API key proves you are you. Provider keys are how you get billed by the upstream — Speechbase never proxies billing. Both are managed in the dashboard but they live in different places: see Provider Keys (BYOK) for the second kind.

Issuing a Speechbase API key

In the dashboard, Settings → API Keys → Create key. Give it a descriptive name, copy the secret immediately (it's only shown once), and store it somewhere your app can read at runtime.

Keys are scoped to a single organisation. If you belong to multiple orgs, each one issues its own keys and they don't cross over.

Scope and permissions

A Speechbase API key has full access to its organisation's resources — voices, provider keys, synthesis. There are no per-key permissions today. Treat each key like a service-account credential.

You can issue multiple keys per organisation (one per environment, one per service, etc.) and revoke individual keys without disrupting the others. A revoked key returns 401 Unauthorized from then on.

Storing keys safely

Don't commit them. Use .env files and a secret manager.
Don't log them. Speechbase never logs your inbound key beyond a stable key ID for traceability — you should do the same downstream.
Don't ship them to the browser. Speechbase keys grant full org access; route synthesis requests through your own backend.

Error responses

Status	Meaning
`401`	The key is missing, malformed, or has been revoked.
`403`	The key is valid but the resource belongs to a different organisation.

Both responses use the RFC 7807 Problem Detail format.

{
  "type": "about:blank",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Invalid or missing API key"
}

Rotating keys

There's no built-in rotation primitive yet. The standard pattern:

Create a new key.
Roll your application config to use the new key.
Revoke the old key from the dashboard.

Because keys are independent, you can run both side-by-side for as long as the rollout takes.