BYOK — Bring Your Own Key

BYOK lets you keep using Sonzai's chat / sessions / extraction stack while routing the underlying provider call through your API key. Token charges land on your provider invoice; everything else (memory, personality, post-processing models, billing for Sonzai's platform) behaves the same.

This is different from Custom LLM (BYOM). BYOK uses Sonzai's first-party provider integrations with your billing key; BYOM swaps the entire chat-completion call to an endpoint you host.

Setup paths

Two ways to add a key, both equivalent on the wire:

• Dashboard. Open your project at platform.sonz.ai → Settings → BYOK, pick a provider, paste the key. The dashboard runs the same probe and shows the redacted prefix + health status alongside any keys you already have.
• API / SDK. The endpoints below. Useful for IaC, CI bootstrap of new tenants, or rotation cron jobs.

What you can plug in

The same providers that the platform speaks natively:

• openai
• gemini
• xai
• openrouter (internal fallback path — a key here covers when the platform falls through to OpenRouter)

A custom BYOM endpoint isn't a BYOK provider; configure it via Custom LLM instead.

Storage and security

• Keys are encrypted at rest and decrypted only inside the platform's request path. They never round-trip back through any API — list / get responses return only an api_key_prefix (the first few characters) so you can identify which key is which.
• A synchronous probe runs at write time. Sonzai does a no-op call to the upstream provider with the key, so bad keys fail PUT with a 400. Misconfiguration surfaces at setup, not on the first user chat.
• Per-key health is tracked. Every read returns health_status, last_health_error, and last_health_check_at so you can detect a rotated-out or revoked key before users do — pipe these into a monitor and alert before chat traffic starts failing.

Endpoints

Per project, indexed by (project_id, provider). List all keys, set one, mark it inactive, delete, or re-test.

The full request/response shapes are in Reference → API → BYOK.

Setting a key

import { Sonzai } from "@sonzai-labs/agents";

const client = new Sonzai({ apiKey: process.env.SONZAI_API_KEY! });

const key = await client.byok.put("project_xyz", "openai", {
api_key: process.env.MY_OPENAI_KEY!,
});

console.log(key.api_key_prefix); // e.g. "sk-..." — never the full key
console.log(key.health_status);  // "healthy" after the synchronous probe

Listing and inspecting

const keys = await client.byok.list("project_xyz");
for (const k of keys) {
console.log(k.provider, k.api_key_prefix, k.health_status, k.last_used_at);
}

Activating, deactivating, deleting

PATCH toggles is_active without rotating the key — handy for disabling temporarily without losing the key material. DELETE removes the key and its history.

// Pause this BYOK key (subsequent calls fall back to platform-managed billing)
await client.byok.setActive("project_xyz", "openai", false);

// Re-test
const fresh = await client.byok.test("project_xyz", "openai");

// Permanently remove
await client.byok.delete("project_xyz", "openai");

Caching and invalidation

The platform caches the resolved BYOK key per (project_id, provider) in-process for performance. Every Put / Patch / Delete fires an invalidator so a rotated key takes effect on the next call without a restart.

When BYOK doesn't apply

If a project has no BYOK key for the provider that the chat call ends up using, Sonzai bills that provider call to its own platform key as normal — same UX, same SLA. BYOK is purely additive: set a key and it takes over for that provider; remove it and the platform key kicks back in.

Reference

• Custom LLM (BYOM) — entirely your own endpoint, not provider passthrough.
• Providers — the four IDs you can attach BYOK keys to.
• Reference → API → BYOK — REST shape for every endpoint above.