Auth model

CallVault uses three credential layers. Mixing them up is the most common integration mistake — each layer has a distinct audience and lifetime.

Auth0 operator session

Humans (operators, delegators) sign in to the dashboard with Auth0. Their access token plus X-Broker-Tenant-Id authorizes tenant-scoped control routes: connections, approvals, billing previews, webhooks, and GET /v1/ops/openapi.json.

Control API keys (bk_*)

Server-side only. Prefix must be bk_test_ or bk_live_ (legacy sk_* keys are rejected). Used to mint broker JWTs via POST /v1/broker/token and for other control-plane operations documented in the operator OpenAPI spec.

Never embed control keys in agent containers, browser bundles, or mobile apps.

Broker JWT (agent runtime)

Short-lived bearer token returned from /v1/broker/token. Scoped to tenant, agent app, and environment (test / live). Agents present this JWT to POST /v1/tools/execute and related agent routes.

The SDK's BrokerAgentClient throws if you pass a bk_* string where a broker JWT is expected.

OAuth tokens (upstream SaaS)

Stored encrypted in CallVault after operator connect flows. Agents and your app code receive connection handles (connected_account_id), not refresh tokens.