Bring your own provider keys

BYOK is the self-serve provider access model in Speechbase. Provider charges go directly to your account at each upstream vendor, and Speechbase uses the credential you store to call the provider on your behalf.

If your workspace uses Managed Routing, Speechbase manages provider relationships, billing, and quotas instead of requiring you to store provider keys. The synthesis API shape is the same; the difference is who owns the upstream provider relationship and bill.

This guide walks through the lifecycle.

BYOK vs Managed Routing

Use BYOK when you already have provider accounts or need charges to remain on provider invoices. Use Managed Routing when you want one Speechbase bill and do not want to manage provider accounts directly.

What you need before you start

• A Speechbase organisation and an API key.
• An account with at least one TTS provider — OpenAI is fastest to start with.
• A provider API key with permission to call the provider's TTS endpoints.

Adding a key

In the dashboard:

1. Go to Speechbase → Provider Keys.
2. Find the row for your provider and click Connect.
3. Paste the provider key. Speechbase validates it by issuing a tiny synthesis call against a known voice — if the key is wrong you'll get an error here instead of at request time.
4. Save.

Or via the API:

curl -X PUT https://api.speechbase.ai/v1/api-keys/openai \
  -H "Authorization: Bearer $SPEECHBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "keyValue": "sk-..." }'

What happens to the key

When you store a provider key, Speechbase writes:

1. The key value to a secure encrypted key store, scoped to your organization and provider.
2. A row to Postgres recording the last four characters and a key_updated_at timestamp.

That's it. The plaintext key never lives on disk in our infrastructure outside the encrypted key store, and is only ever decrypted in memory at request time, just long enough to dispatch the upstream call. Speechbase can't view or recover the full key. Provider keys are not echoed back by any endpoint — GET /v1/api-keys returns the metadata row, last-four only.

Listing your keys

curl https://api.speechbase.ai/v1/api-keys \
  -H "Authorization: Bearer $SPEECHBASE_API_KEY"

You'll see one entry per provider you have a key for, with lastFour and updatedAt.

Rotating

Just PUT the new key over the old one. There's no separate rotate endpoint because there doesn't need to be:

curl -X PUT https://api.speechbase.ai/v1/api-keys/elevenlabs \
  -H "Authorization: Bearer $SPEECHBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "keyValue": "sk_new..." }'

The encrypted key is replaced atomically with the metadata row update. The very next synthesis request uses the new key.

Removing

curl -X DELETE https://api.speechbase.ai/v1/api-keys/elevenlabs \
  -H "Authorization: Bearer $SPEECHBASE_API_KEY"

Both the encrypted key and the metadata row are cleared. Synthesis calls targeting the now-disconnected provider will fail with 403 no_api_key.

Enabling and disabling without removing

If you want to temporarily turn a provider off without losing the stored key, use Speechbase → Provider Keys → Enabled in the dashboard. Disabled providers fail synthesis with 403 provider_disabled; the key stays encrypted and re-enabling is instant.

Best practices

• Use a least-privilege key per provider. If your provider supports scoped keys (OpenAI does, ElevenLabs does), generate one that can call TTS only.
• Rotate on a schedule. Once a quarter is reasonable for production keys.
• Don't share keys between orgs. Speechbase organisations correspond to customer environments; mixing them up risks cross-tenant billing.

Logging hygiene

Speechbase never logs your provider keys or your synthesis text. We strongly recommend you don't either.

Never log request text, response audio, signed audio URLs, anything derived from the input (transcripts, summaries, hashes), API keys (yours or ours), or provider error bodies — they sometimes echo input back.

Safe to log: request ID, org ID, provider, model, voice ID, character count, output duration, status code, latency. Stick to operational metadata on a strict allowlist; the default answer to "should we log this?" is no.