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 IDP 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.
idp_mappingClaim-match rules: which IDP token claims select this role.

​
How selection works

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

​
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.