BYOK (Bring Your Own Key)

BYOK (Bring Your Own Key) allows API consumers to override the model for a single request by passing their own provider credentials in HTTP headers. The engine uses the consumer’s key for that request only and never stores it.

What is BYOK?

Normally, each agent uses the model configured in its definition (e.g., model: gpt-4o). With BYOK enabled, an API consumer can override this by specifying a different provider, model, and API key in request headers. The override applies to that single request only — subsequent requests without BYOK headers use the default model.

This is useful for:

Multi-tenant platforms — each customer uses their own LLM API key and billing.
Testing — try different models without changing engine configuration.
Premium tiers — offer customers the option to use a more powerful model by providing their own key.

Headers

Header	Required	Description
`X-BYOK-Provider`	Yes	Provider type. One of `openai`, `anthropic`, `openrouter`, `openai_compatible`, `ollama`.
`X-BYOK-API-Key`	Yes	The consumer’s API key for the specified provider.
`X-BYOK-Model`	No	Model identifier as expected by the provider (e.g., `gpt-4o-mini`, `claude-sonnet-4-20250514`). Falls back to the provider default when omitted; `openrouter` has no default, so supply one.
`X-BYOK-Base-URL`	No	Override the provider base URL. Required for `openai_compatible`; optional for the others (each has a sensible default).

X-BYOK-Provider and X-BYOK-API-Key are mandatory — if either is missing the request is rejected with HTTP 400. The remaining headers are optional.

Supported providers

Provider	Default base URL	Notes
`openai`	`https://api.openai.com/v1`	Default model `gpt-4o-mini` when `X-BYOK-Model` omitted.
`anthropic`	`https://api.anthropic.com/v1`	OpenAI-compatible adapter; `anthropic-version` header injected automatically.
`openrouter`	`https://openrouter.ai/api/v1`	`X-BYOK-Model` required (no default).
`openai_compatible`	—	`X-BYOK-Base-URL` required; works with any OpenAI-compatible endpoint.
`ollama`	`http://localhost:11434/v1`	For self-hosted Ollama.

curl example

curl -N http://localhost:8443/api/v1/schemas/{schema_name}/chat \
  -H "Authorization: Bearer bb_your_token" \
  -H "Content-Type: application/json" \
  -H "X-BYOK-Provider: anthropic" \
  -H "X-BYOK-API-Key: sk-ant-customer-provided-key" \
  -H "X-BYOK-Model: claude-sonnet-4-20250514" \
  -d '{"message": "Hello, tell me about your capabilities"}'

The agent’s system prompt, tools, and all other configuration remain unchanged. Only the LLM backend is overridden.

For an OpenAI-compatible endpoint, supply the base URL too:

curl -N http://localhost:8443/api/v1/schemas/{schema_name}/chat \
  -H "Authorization: Bearer bb_your_token" \
  -H "Content-Type: application/json" \
  -H "X-BYOK-Provider: openai_compatible" \
  -H "X-BYOK-API-Key: sk-your-key" \
  -H "X-BYOK-Base-URL: https://your-endpoint.example/v1" \
  -H "X-BYOK-Model: your-model" \
  -d '{"message": "Hello"}'

JavaScript example

const response = await fetch('http://localhost:8443/api/v1/schemas/{schema_name}/chat', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer bb_your_token',
    'Content-Type': 'application/json',
    'X-BYOK-Provider': 'openai',
    'X-BYOK-API-Key': customerApiKey,
    'X-BYOK-Model': 'gpt-4o-mini',
  },
  body: JSON.stringify({ message: userMessage }),
});

const reader = response.body.getReader();
// Process SSE stream...

Enabling BYOK

BYOK is disabled by default. Enable it one of two ways.

Admin Dashboard (imperative)

Navigate to Admin Dashboard -> Settings.
Under BYOK (Bring Your Own Key), turn on BYOK Enabled and select the providers to allow.
Changes take effect immediately (no restart needed).

If no providers are selected, all supported providers are allowed while BYOK is enabled.

Declaratively via Helm values (GitOps)

Engine 1.10.0+ / chart 0.11.0+ let you manage BYOK from your chart values, so it lives in your GitOps flow instead of per-engine Admin clicks:

config:
  byok:
    enabled: true
    allowedProviders: [openai, anthropic, openrouter, openai_compatible, ollama]

When this block is set, the engine reconciles these settings on every boot — the values above are the source of truth and supersede Admin-UI edits (remove the block to hand control back to the Admin Dashboard). Omit allowedProviders (or leave it empty) to allow all supported providers. The corresponding env vars are SYNTHETICBREW_BYOK_ENABLED and SYNTHETICBREW_BYOK_ALLOWED_PROVIDERS (comma-separated).

When to use BYOK

Scenario	BYOK useful?	Why
Multi-tenant SaaS	Yes	Each customer provides their own LLM key and pays their own API costs.
Internal team tools	Usually no	Use a shared organizational API key configured in the engine.
A/B testing models	Yes	Compare gpt-4o vs claude on the same agent without changing config.
Premium features	Yes	Let paying customers use a better model by providing their own key.
Development/staging	Yes	Developers test with their personal keys without affecting shared config.

Security

Keys are never stored. The engine uses the key for the duration of that single HTTP request and discards it immediately after.
Keys are never logged. Even at debug log level, API keys from BYOK headers are redacted.
BYOK is off by default. An operator must explicitly enable it (Admin Settings or chart values).
Stateless. The engine does not cache, persist, or transmit the key anywhere except to the specified provider’s API.
Provider validation. If the consumer specifies a provider that is not in the allowlist, the request is rejected with HTTP 403. A missing required header (X-BYOK-Provider / X-BYOK-API-Key) is rejected with HTTP 400.