Bring-your-own-key (BYOK)

BYOK (Bring Your Own Key) lets you plug your own OpenAI API key into Spelo. We handle the widget, session management, database adapters, and security — OpenAI bills you directly for inference.

When to choose BYOK

You already have an OpenAI account with committed spend discounts
You want to unify OpenAI billing across multiple apps
You expect high volume where managed per-minute pricing becomes more expensive than raw OpenAI API pricing
You operate in a region where OpenAI requires separate billing entities

When to choose managed

You want one bill (Spelo, not split)
You’re new to OpenAI and don’t want to deal with their account / rate limit quotas
You need under ~500 min / month (managed is cheaper at low volume due to OpenAI’s minimum commits)
You need a predictable per-minute cost without worrying about rate limits

You can switch between BYOK and managed at any time from the dashboard.

How to enable BYOK

Create an OpenAI API key. OpenAI Platform → API keys → Create new secret key → pick Realtime API permissions.
Paste it in Spelo. Dashboard → Billing → OpenAI key → paste.
Spelo encrypts it. AES-256-GCM at rest. You see only sk-proj-...XXXX (last 4 chars) from now on.
Test a session. Click Test voice — it should work. If it doesn’t, check your OpenAI account for rate-limit or billing issues.

What happens under the hood

Every call to POST /v1/:siteId/token decrypts your key server-side, calls OpenAI’s /realtime/sessions, and returns the ephemeral to the widget.
Your key never touches the browser.
Your OpenAI usage dashboard shows Spelo-originated sessions as normal API usage — they’re not separately tagged.
Rate limits on your OpenAI account apply. If you hit them, we surface the error to your widget and log it in our dashboard.

Key rotation

Rate limits

OpenAI assigns rate limits per account / per tier. For Realtime API (as of this writing):

Tier 1 — 1 concurrent session
Tier 2 — 10 concurrent
Tier 3 — 30 concurrent
Tier 4 — 100 concurrent
Tier 5 — 1,000 concurrent

If you’re on Tier 1, only one visitor can use your voice widget at a time (the second gets a “busy” message). Contact OpenAI to upgrade tiers.

Cost calculator

OpenAI Realtime (gpt-4o-realtime) pricing as of the cutoff in this doc:

Audio input: $100 / 1M tokens (~6 min of speech)
Audio output: $200 / 1M tokens
Text input: $5 / 1M tokens
Text output: $20 / 1M tokens

Typical voice session: ~2 min of audio in, ~3 min of audio out, ~2K tokens of system prompt. Rough cost: $0.10–$0.20 per session. A 2-minute session costs about the same as a Pro plan session would if you paid via Spelo managed pricing.

Managed pricing becomes more favorable at very low volume (OpenAI has minimum monthly spend thresholds you’d otherwise under-utilize).

Limits when BYOK is enabled

Thing	Managed plan	BYOK
Monthly minutes cap	Plan limit	None (OpenAI is your cap)
Rate limiting by Spelo	Generous	Same
Observability (sessions / cost)	We compute cost_cents exactly	We compute cost_cents using the numbers above (may lag actual OpenAI billing by 24h)
Support	Full	Full — but questions about OpenAI billing go to OpenAI

Multiple keys across sites

Each site can have its own OpenAI key. Useful if you want separate billing for different business units. Dashboard → site detail → OpenAI key (overrides the workspace default).

Security

Your OpenAI key:

Encrypted at rest with AES-256-GCM, per-record IVs, site_id as AAD
Master key stored in Cloudflare Secrets or AWS KMS — never in our DB
Decrypt operations audit-logged
Rotated on your request or on detection of anomalous usage

Full detail: Security.