Skip to main content
A role is the routing unit for identity-based access. It is used only with consumers whose routing_mode is role_based: instead of the consumer owning registries directly, each request’s OIDC token is matched to a role, and the role decides what that caller can reach. This lets one consumer (one endpoint) serve many identities — each user or group routed to different models and tools based on their token — without minting a consumer per tenant.

​
What a role defines

FieldMeaning
nameDisplay name.
registry_idsThe registries this role may use.
model_policiesPer-registry allow-list and default model (same shape as on a consumer).
mcp_policiesMCP toolkit and fail mode for agent traffic.
oidc_mappingClaim-match rules: which OIDC token claims select this role.

​
Claim matching

Each oidc_mapping is a set of claim rules, matched with any or all semantics. A rule tests a claim with equals, contains_any, or contains_all against the values you list — so you can route on a groups, roles, or custom claim.

​
How selection works

  1. A client calls a role_based consumer with an Authorization: Bearer <oidc-jwt>.
  2. The oidc auth validates the token (issuer, audience, JWKS, scopes).
  3. The token’s claims are matched against each role’s oidc_mapping.
  4. The matched role’s registry_ids, model_policies, and mcp_policies govern routing for that request — intersected with what the token is allowed to reach.

​
Managing roles

CRUD lives under /v1/gateways/{gateway_id}/roles, plus registry binding:
  • …/roles/{role_id}/registries/{registry_id} (POST/DELETE) — attach/detach a registry to the role.
  • Attach a role to a consumer via …/consumers/{id}/roles/{role_id}.
See the Roles API.