BYOK and managed credentials

The gateway supports BYOK and Speko-managed sessions through the same local socket. Credential source is request-scoped, so one process can serve both at the same time.

BYOK requests

Set at least one SPEKO_<PROVIDER>_BYOK_API_KEY (or its _FILE variant) and send credential_source: "byok".

• Session plans are minted in-process and HMAC-signed with an ephemeral per-process key. No control-plane call is made for planning or fallback.
• Your provider key is injected into the provider request only after the local plan verifies. It never leaves the process.
• Sessions must request credential_source: "byok", provider_route: "provider_direct" (or "auto"), and relay_policy: "forbidden". If more than one configured BYOK provider supports the session kind, request.provider must name one explicitly.
• Provider-direct sessions receive a fixed local hard deadline capped by SPEKO_LOCAL_MAX_SESSION_DURATION (default 24h). The deadline is not renewed during a call.
• Anonymous, content-free telemetry is sent by default; disable with SPEKO_TELEMETRY_DISABLED=true. It carries no API key, account ID, credential, or stable installation identifier.

Speko-managed requests

Set SPEKO_API_KEY (or SPEKO_API_KEY_FILE) and send credential_source: "managed".

• Before a session opens, the gateway fetches a signed session plan from gateway.speko.dev: the route (provider, model, endpoint, adapter), a short-lived delegated provider credential, metering ceilings, and a session-scoped telemetry token. The gateway verifies signature, issuer, audience, expiry, and structure against the public JWKS before accepting media.
• request.provider: "auto" becomes available — Speko picks the route.
• One bounded fallback is available: if the provider fails to open, the gateway exchanges the failed attempt for a plan on a backup provider, transparently.
• Usage is metered and consolidated onto your Speko invoice, post-paid. See Billing.

Warm plans (zero-overhead session setup)

For managed requests, the gateway prefetches a small pool of signed plans per route shape, so POST /v1/sessions normally costs zero control-plane round trips:

• SPEKO_WARM_PLAN_TARGET (default 4) plans per route; 0 disables prefetching.
• Pre-declare hot routes with SPEKO_WARM_ROUTES (comma-separated kind:provider[:model[:language]]), or let the pool learn from traffic.
• Each warmed plan carries a short-lived credential; unused plans are discarded at expiry and settle at zero cost.

The trade-off is that delegated credentials exist in memory from prefetch time rather than session-start time — bounded by the plan TTL (minutes) and the pool size. Set SPEKO_WARM_PLAN_TARGET=0 if that window matters more to you than setup latency.

Automatic selection in the LiveKit integration

The raw local API always requires an explicit execution.credential_source. The LiveKit STT and TTS helpers default to credential_source="auto":

• SPEKO_API_KEY or SPEKO_API_KEY_FILE configured → managed;
• otherwise → BYOK.

Set credential_source="byok" explicitly when you want voice requests to use local provider keys while keeping a Speko API key available for LLM Relay calls or other managed traffic. The validation rules cover the legal request combinations.