Authentication

You authenticate to ClutchCall at two levels. Your server authenticates with a long-lived API key. Each end user or session connects with a short-lived token that you mint from that key. This keeps powerful credentials on your backend. Clients get only narrowly-scoped access. Two auth surfaces cover the two kinds of traffic:

Control plane (control-plane API tRPC: voice control, streams CRUD, agents, webhooks, analytics). This uses long-lived API keys scoped to an org and a set of capabilities.
Data plane (MoQT publish / subscribe, audio bridge, robotics topics, games rooms, data pub/sub). This uses short-lived relay tokens scoped to a set of namespaces. The relay’s namespace_auth hook checks each token on every publish or subscribe.

The two are linked. A client uses its API key to mint relay tokens scoped to exactly the namespaces that it needs.

Authenticate your server: API keys

Give your backend an API key so that it can call the control plane. Create one in the dashboard or with streams.apiKeys.create({ orgId, label, scopes }). The API returns the key string once, at creation. The control-plane API stores only the hash.

export CLUTCHCALL_API_KEY=tqs_live_abc123…

Every control-plane API call (voice originate, streams create, webhook list, analytics, agent attach) authenticates with this key over HTTPS. The control-plane API rejects a key that does not have the correct capability scope for the called procedure.

Authenticate a session: relay tokens

To let a client publish or subscribe on the data plane, mint a relay token for it. Do not share your API key. The relay never sees the API key. The control-plane API mints a short-lived relay token. The token is a signed JWT that carries namespace claims. The client presents the token during the MoQT handshake. The relay’s namespace_auth hook checks the JWT signature and extracts the namespace scope. It then gates every subsequent publish / subscribe against that scope. A typical relay token looks like:

{
  "alg": "EdDSA",
  "kid": "rk_live_abc…",
  "iss": "clutchcall-bff",
  "sub": "tenant_abc",
  "ns":  ["voice/sid_xyz/*", "playback/li_xyz"],
  "exp": 1733900000
}

Claim	Meaning
`kid`	Signing-key id. The relay fetches the matching public key from Redis.
`iss`	The control-plane API that minted the token.
`sub`	Tenant id the relay stamps on the session.
`ns`	Namespace patterns this token may publish or subscribe to.
`exp`	Expiry (typically 1h for client tokens, longer for service-to-service).

Every modality client knows which namespaces it needs. It asks the control-plane API for a token with that scope. You do not construct these JWTs by hand. When you give the SDK a control-plane API key, its modality clients call the control-plane API’s token-mint procedures for you.

Authenticate an end user in the browser

In the browser, you cannot ship a long-lived API key. Instead, mint a short-lived relay token on your server for each browser session. Pass the token to the SPA:

// server (your control-plane API)
const token = await streams.signingKeys.mintPlaybackToken({
  inputId: "li_xyz", scopes: ["playback/li_xyz"], ttlSeconds: 3600,
});

// browser
const viewer = await BroadcastViewer.open(signedUrl);

For voice in a browser:

// server
const token = await voice.audioBridge.mintBrowserToken({
  callSid: "sid_xyz", ttlSeconds: 1800,
});
// browser
const v = new Voice({ baseUrl: controlPlaneApi, browserToken: token });

browserToken avoids the API-key-on-client antipattern. The SDK presents the token directly to the relay.

Rotate keys without downtime

A per-org signing key signs every relay token. To rotate keys without downtime:

Call streams.signingKeys.create({ orgId, label }). This issues a new active key.
Wait until the clients’ old tokens expire (1h by default).
Call streams.signingKeys.retire({ id }). The old key then mints no new tokens.

The relay hydrates the active set of public keys from Redis on a 30 s refresh. Retirements take effect within that window.

Legacy: service-account JWT

The original control plane (the ClutchCallClient root import: dial, hangup, barge, push_audio) authenticated with an RSA service-account JSON file. CLUTCHCALL_CREDENTIALS points at that file:

{
  "tenant_id": "acme",
  "private_key": "-----BEGIN PRIVATE KEY-----\n…\n-----END PRIVATE KEY-----",
  "private_key_id": "kid-2026-01"
}

The SDK signed an RS256 JWT (iss=clutchcall-sdk, sub=tenant_id) and presented it on the QUIC handshake. This still works for backwards compat. New code should use API keys + relay tokens via the Voice modality.

Modalities overview
Architecture — where namespace_auth fits in the relay
Streams reference — apiKeys, signingKeys

Getting Started

Concepts

Raw RPC Format

Telephony Reference

Platform

Admin API (raw RPC, no SDK)

Authenticate your server: API keys

Authenticate a session: relay tokens

Authenticate an end user in the browser

Rotate keys without downtime

Legacy: service-account JWT

​Authenticate your server: API keys

​Authenticate a session: relay tokens

​Authenticate an end user in the browser

​Rotate keys without downtime

​Legacy: service-account JWT

​Related

Authenticate your server: API keys

Authenticate a session: relay tokens

Authenticate an end user in the browser

Rotate keys without downtime

Legacy: service-account JWT

Related