Trust and signing

Plan verification

Every session — BYOK or managed — is authorized by a plan the gateway verifies before any credential attaches or media flows.

Managed plans are JWS artifacts signed by the control plane:

• Protected header: alg (EdDSA or RS256), a non-blank kid, typ: speko.session-plan+jws.
• Payload claims: issuer (must equal the configured control plane), audience (must contain speko-runtime), iat/exp with 30 s clock skew, and a jti consumed exactly once — replaying a plan fails.
• The enclosed plan must match the served plan byte for byte, and the envelope exp must equal the plan's own expires_at.

Keys are fetched from gateway.speko.dev/.well-known/jwks.json, with Cache-Control/ETag honored, an unknown kid forcing one synchronous refresh, and HTTPS-only redirects.

Local BYOK plans never touch the network: the gateway mints the plan itself and HMAC-signs it with an ephemeral per-process key (local.v1. signature prefix, 1-minute TTL). The same verification pipeline runs either way — BYOK keys are injected only after the plan verifies.

Plan invariants worth knowing

• BYOK plans must not carry a credential; managed plans must.
• A credential can never outlive its plan.
• Transport and endpoint scheme are cross-checked (websocket → wss, http → https, and so on), and provider endpoints must match exact official host allowlists.
• Managed plans carry a telemetry block with a session-scoped token; that token — not your API key — authenticates runtime telemetry. Provider-direct deadlines are fixed and are not renewed mid-call.

The relay plan family

The hosted relay uses a second, deliberately isolated plan family: typ: speko.relay-plan+jws, audience speko-relay, protocol revision 5, signed with a different key published at gateway.speko.dev/.well-known/relay-jwks.json. The local session protocol remains revision 3; Relay revision 5 is a parallel artifact for the relay fleet, not its successor. Separate keys and audiences mean neither plan family's signature can ever authorize the other's consumer.

Credential rules

• Local gateway BYOK keys stay in gateway memory. They are never sent to Speko — not even in the setup request. Hosted Relay BYOK uses separately encrypted organization credentials resolved inside regional connectors.
• Your SPEKO_API_KEY is used only against gateway.speko.dev. It is never sent to a provider.
• Delegated provider credentials in managed plans are short-lived and session-scoped.
• On managed Deepgram STT routes, the provider also receives Speko's opaque reservation ID for bill correlation — no other customer data.

What the setup request contains (managed mode)

Session kind and protocol revision; gateway version, instance ID, installed adapters; optional integration name/version; route and credential constraints; requested provider, model, voice, language, region, allow/deny lists, TTS character allowance, and the routing objective; media format.

Limits of the model

Process memory is not a hardware security boundary: run the gateway with least privilege, a read-only filesystem, and a dedicated workload identity. In the single-container sidecar layout, your agent process can read the shared environment — split containers when you need credential isolation from your own agent code.