Client identity¶

Who may call the gateway, and as whom. A client identity is a dedicated bearer bound to a client_id; it decides which routes a caller may reach and nothing about which credential pays — spending is decided by the entitlement model, and a valid bearer never implies agent authority.

Shape¶

Each boot-time identity is one entry in the JSON array BRAMA_MODEL_ROUTER_CLIENT_IDENTITIES (assembled by the launcher from dedicated Skarbiec token items; see configuration):

Missing, malformed, duplicate, or contradictory entries fail startup. A bearer that carries allowed_models may reach only the six inference and discovery paths (/v1/chat/completions, /v1/messages, /v1/responses, /v1/embeddings, /v1/moderations, /v1/models) plus the account routes; anything else answers 403.

Identity classification¶

The boot table is a warm start, not a precondition — it is a copy taken at boot, so it cannot expire, cannot be revoked, and cannot contain a client registered since the process started. Brama classifies a presented bearer into one of two disjoint identity kinds:

1. Static boot-table and Skarbiec-introspected tokens are workload/model-client identities. They do not require or acquire organization context.
2. A JWT validated by the Wisent Identity authority (the origin and anon key BRAMA_WISENT_AUTH_URL and BRAMA_WISENT_AUTH_ANON_KEY name; nothing is compiled in) is a human identity. The request must also carry X-Wisent-Organization-ID: <uuid>; Brama calls authorize_organization(target_org_id) with the same bearer and accepts only its matching user, organization, and typed owner/admin/member role.

A bearer outside the boot table is put to its authority on every request: nothing remembers a resolved workload or human identity, so a revocation holds from the next request and switching organizations always authorizes the requested one. The raw bearer is never logged (src/core/server/admission/authority/mod.rs).

Special identities¶

Two client_id values are special in code:

• brama-desktop — the only identity the /v1/admin/* family answers, and it must carry no model allowlist. Every other caller gets 403.
• brama-user — a human identity verified by Wisent Supabase and authorize_organization; the only identity the /v1/account/* family serves. Account ownership remains derived from the verified user, never from the organization or a caller-supplied identifier.

In managed deployments, startup additionally checks two allowlists for internal consistency when the table is present: wisent-backend must hold wisent-backend, wisent-backend/embeddings and wisent-backend/moderation; the weles identity must hold best and weles. Either grant may hold more: an alias this build does not compile in is the operator's to add, and a release that refused it could not be restarted under the policy written for its successor. The launcher derives the backend identity from these required aliases, not from optional deployment aliases that share the wisent-backend/ prefix.

Refusals¶

A startup refusal reports the required and observed alias lists after must give CLIENT every required alias. observed=None means that the client or its allowlist is absent; no bearer value is printed.

A request without a bearer asks no provider, so its refusal carries no attempts:

$ curl -s http://127.0.0.1:8080/v1/models        # no bearer
{"error":{"code":"unauthenticated","message":"unauthorized",
 "retryable":false,"type":"authentication_error"}}       # HTTP 401

• Human bearer with missing, duplicate, or malformed X-Wisent-Organization-ID → 400.
• Missing, malformed, or invalid bearer → 401 unauthorized. The body is deliberately blank about why: an unauthenticated caller learns nothing.
• Valid human bearer without membership in the requested organization → 403 forbidden.
• Unavailable Skarbiec/Supabase identity authority → 503 identity upstream unavailable: <which authority, the operation that failed and its cause>. A workload bearer Wisent Identity rejects while Skarbiec did not answer carries Skarbiec's cause (the authority it belongs to: the workload authority (Skarbiec) did not answer for this bearer, and Wisent Identity does not know it: …); a person's bearer carries Wisent Identity's or the organization authority's. The gateway log keeps the same cause under workload_authority_unavailable, wisent_identity_unavailable or organization_authority_unavailable.
• Valid bearer outside its path scope, or a signed agent that contradicts the workload bearer's agent_id binding or the path agent → 403 forbidden.
• Non-brama-desktop identity on /v1/admin/* → 403 forbidden.

Lifecycle¶

Identities are read once at startup; the gateway does not reload the client table in place — restart after any identity change (configuration). Bearers not in the table live and die with their authority: Skarbiec token revocation and Supabase human membership changes take effect within the five-second, identity-kind-specific cache.

Not to be confused with¶

• An agent identity. The bearer authenticates transport; the HMAC trio (x-agent-id/x-agent-timestamp/x-agent-signature) proves an agent and is what selects and spends subscriptions. See entitlement.
• An alias. An alias is a deployment-owned model name; it never unlocks a credential its caller does not own.