> ## Documentation Index
> Fetch the complete documentation index at: https://docs.neuraltrust.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Roles

> Roles power identity-based routing: an OIDC token's claims select a role, and the role decides which registries, models, and MCP tools the caller may use.

A **role** is the routing unit for **identity-based** access. It is used only with
[consumers](/trustgate/concepts/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

| Field            | Meaning                                                                  |
| ---------------- | ------------------------------------------------------------------------ |
| `name`           | Display name.                                                            |
| `registry_ids`   | The [registries](/trustgate/concepts/registries) this role may use.      |
| `model_policies` | Per-registry allow-list and default model (same shape as on a consumer). |
| `mcp_policies`   | MCP toolkit and fail mode for agent traffic.                             |
| `oidc_mapping`   | Claim-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](/trustgate/concepts/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](/trustgate/api/overview).