Manage roles and permissions
Enterprise Tier
Access to the Tetrate Agent Router Admin Dashboard is governed by roles. A role is a named set of permissions, and the role granted to a user or a team determines which menus, pages, and actions that person is shown. A role applies either across the whole organization or inside a single project, so a delegated operator can be given exactly one project to administer and nothing beyond it.
Persona: Platform operator working in the Admin Dashboard, holding a role that can manage access.
Estimated time: 10 to 20 minutes to define a role and grant it; recurring thereafter as people join, move, and leave.
When this guide applies
| Situation | What it covers |
|---|---|
| A new administrator needs a subset of Admin Dashboard capabilities | Selecting a built-in role, or defining a custom one |
| An operator should administer one project and nothing else | Granting a project-scoped role |
| Several people all need the same access | Granting a role to a team once instead of per person |
| Access has become broader or narrower than intended | Reviewing, editing, and revoking grants on the Access page |
| A granted role must be confirmed to restrict as intended | Verifying the result from the recipient's own session |
Outcomes
By the end of this guide:
- The difference between read and write permissions is clear, along with how each is reflected in the Admin Dashboard.
- A built-in role has been selected, or a custom role has been created.
- That role has been granted to a user and to a team, at organization or project scope.
- The combined effect of overlapping grants is understood.
- The restriction has been verified from the recipient's session.
Prerequisites
- Access to the Admin Dashboard (
https://dashboard.<tenant>.tetrate.ai) with a role that can manage access, such as Super Admin. - The users involved already exist in Agent Router. A user record is created on first sign-in, as described in Onboard developers and issue keys.
- For team-based grants, a team under Directory → Teams with the intended members.
The two pages used throughout this guide sit in the sidebar under Directory: Roles and Access.
In this guide
- Concepts: how a role decides what a person is shown
- Tasks: define access and grant it
- Reference
How access is decided
Every menu and page in the Admin Dashboard is tied to a permission. A menu is shown only when the role includes its read permission, and the page itself rejects anyone who arrives without that permission. Enforcement happens in two places at once. Hiding a menu is therefore a genuine restriction, not a cosmetic one.
Permissions come in two kinds:
- Read: view a resource, for example view models, view users, or view audit logs. Read permissions determine which menus are visible.
- Write: create, edit, or delete a resource. Write permissions determine whether the New, Edit, and Delete buttons appear and whether the action is accepted.
role permissions: { models.read, providers.read }
↓
sidebar shows: Models, Providers (their read permissions)
buttons shown: none (no write permissions)
other pages: redirect to "unauthorized"
A role carrying read permissions only is view-only: every change button is hidden, and the server refuses the change even when it is submitted directly.
Scope: organization or project
Every role applies at one of two levels.
| Scope | What it covers |
|---|---|
| Organization | The whole organization, including organization-wide resources such as users, teams, API keys, billing, and the shared model, provider, and Model Context Protocol (MCP) catalog. |
| Project | A single project only: the models, providers, MCP servers, and members of that project, and nothing outside it. |
A user can hold an organization role, one or more project roles, or a combination of the two. Someone holding a project role alone is shown only that project's pages; the organization-wide administrative pages (Users, Roles, Settings, and Audit Logs) remain closed.
Built-in roles
The following roles are predefined. Each can be granted as-is, or copied as the starting point for a custom role.
Organization roles
| Role | What it is for |
|---|---|
| Super Admin | Full access to every resource and setting. |
| Viewer | Read-only access to every resource: all menus are visible, nothing can be changed. |
| Model Admin | Manage models and providers. |
| Provider Admin | Manage providers. |
| MCP Admin | Manage MCP servers. |
| User Admin | Manage users, teams, and API keys. |
| Billing Admin | Manage billing, service accounts, and bonus claims. |
Project roles
| Role | What it is for |
|---|---|
| Project Owner | Full administration within the project, covering models, providers, MCP, members, settings, and the gateway. |
| Project Member | Work within the project without managing its members or settings. |
Step 1: create a custom role
The built-in roles cover most deployments. This step applies only where no built-in role matches the intended access, for example a role that is shown the Models and Providers menus and nothing else.
- In the Admin Dashboard, go to Directory → Roles.
- Choose New role, or open a built-in role and choose Copy to start from its permission set.
- Enter a name and a slug. The slug must be lower case with words joined by underscores, for example
gateway_viewer. - Choose the scope, either Organization or Project.
- Select the permissions the role carries. Include a resource's read permission to make its menu visible; add its create, edit, and delete permissions to allow changes.
- Save the role.
Example: a role limited to the catalog menus
An organization role named Gateway Viewer that carries only the read permissions for Models and Providers restricts its holder to the catalog. The sidebar shows Home, the Catalog group, Models, and Providers, and nothing else; every other address redirects to the unauthorized page. Adding the Models and Providers edit permissions extends the same role to changing those two resources, while the rest of the Admin Dashboard stays closed.
Step 2: grant a role to a user
- Go to Directory → Access. Every grant is listed here, grouped by person or team, which makes the current distribution of access reviewable in one place.
- Choose Grant access.
- Select the user, select the role, and set the scope:
- An organization role applies across the organization.
- A project role requires the project it applies to.
- Save the grant.
The grant takes effect on the recipient's next page load; no sign-out is required. To change or remove access later, the grant is opened from the Access page and edited or revoked there.
Step 3: grant a role to a team
Granting a role to a team once, rather than to each member separately, is the lower-maintenance option for a group of people who need the same access: adding someone to the team grants it, and removing them withdraws it.
- Confirm the team exists and holds the intended members. Teams are managed under Directory → Teams.
- Go to Directory → Access and choose Grant access.
- Select the team rather than an individual user, select the role, and set the scope.
- Save the grant.
Team grants behave as follows:
- A role granted to a team confers nothing until someone is a member of that team.
- A member inherits exactly the team's role and no more. A team holding a view-only role gives its members view-only access.
- The grant is live: a person added to the team gains the access on their next page load, and a person removed loses it immediately.
When a person has access from more than one place
A person can hold a role directly and also belong to one or more teams. The resulting access is the sum of all of them: every permission from every role held directly, plus every permission from every team the person belongs to. Grants only ever add access; there is no deny grant that cancels another.
For example, a person holding a direct role that permits editing models, who also belongs to a team holding a view-only role, can edit models (from the direct role) and view everything else (from the team). Removing them from the team leaves only the model editing the direct role provides; removing the direct role leaves only the view-only access inherited from the team.
Step 4: verify the effect
Verification is carried out from the recipient's session rather than the administrator's, because a broader administrative role masks the restriction under test. Once the recipient has reloaded the Admin Dashboard, confirm that:
- The sidebar lists only the menus the read permissions allow.
- Action buttons (New, Edit, Delete, and Grant access) appear only where the matching write permission is held.
- Entering the address of a page the role does not cover redirects to the unauthorized page.
If a page that should be closed is still reachable, the likely cause is a second grant. The Access page lists every grant held by that person, including access inherited through team membership.
Operational notes
- Built-in roles can be edited, but copying a built-in role and editing the copy is the safer pattern: the originals stay intact for comparison and reuse.
- Role and grant changes are recorded. Every change writes an entry that can be reviewed under Audit Logs, as described in Audit Agent Router activity.
- Developers working in the Console rather than the Admin Dashboard are not governed by these dashboard roles. Their access to a gateway follows project membership.
- Where roles are assigned from identity-provider claims, the mapping is evaluated on every login and overwrites the stored role. The precedence rules are documented in Configure SSO role mapping.
Where to go next