> This page is for Gateway.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.merge.dev/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.merge.dev/_mcp/server.

# Roles and permissions

> The four built-in roles, the 36 permissions they bundle, custom roles, and how members get their role.

Every member of a Gateway organization holds exactly one role, a bundle of permissions. Use the four built-in roles, or a custom role when a team needs a different mix.

## Built-in roles

Built-in roles can't be edited or deleted; for a different permission set, create a [custom role](#custom-roles).

| Role          | Intended for                             | Summary                                                                                                                                                                           |
| ------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Admin**     | Org owners and senior platform engineers | All 36 permissions                                                                                                                                                                |
| **Developer** | Engineers building on Gateway            | Manages projects, customers, routing, Custom routing, evals, guardrails, and telemetry export. No billing, and no management of users, roles, credentials, API keys, or security. |
| **Security**  | Security engineers and identity admins   | Manages users, roles, credentials, API keys, guardrails, security alerts, security rules, and SSO. No billing.                                                                    |
| **Read Only** | Auditors, support, observers             | Every view permission except View billing and View telemetry export                                                                                                               |

## Reference

Most resources have View and Manage permissions; logs, traces, audit trail, and request tester are view-only. The same matrix appears under **Settings → Roles**.

| Permission                   | Admin | Developer | Security | Read Only |
| ---------------------------- | :---: | :-------: | :------: | :-------: |
| View users                   |   ✓   |     ✓     |     ✓    |     ✓     |
| Manage users                 |   ✓   |           |     ✓    |           |
| View roles                   |   ✓   |     ✓     |     ✓    |     ✓     |
| Manage roles                 |   ✓   |           |     ✓    |           |
| View credentials             |   ✓   |     ✓     |     ✓    |     ✓     |
| Manage credentials           |   ✓   |           |     ✓    |           |
| View API keys                |   ✓   |     ✓     |     ✓    |     ✓     |
| Manage API keys              |   ✓   |           |     ✓    |           |
| View organization settings   |   ✓   |     ✓     |     ✓    |     ✓     |
| Manage organization settings |   ✓   |           |          |           |
| View billing                 |   ✓   |           |          |           |
| Manage billing               |   ✓   |           |          |           |
| View projects                |   ✓   |     ✓     |     ✓    |     ✓     |
| Manage projects              |   ✓   |     ✓     |          |           |
| View customers               |   ✓   |     ✓     |     ✓    |     ✓     |
| Manage customers             |   ✓   |     ✓     |          |           |
| View routing                 |   ✓   |     ✓     |     ✓    |     ✓     |
| Manage routing               |   ✓   |     ✓     |          |           |
| View Custom routing          |   ✓   |     ✓     |     ✓    |     ✓     |
| Manage Custom routing        |   ✓   |     ✓     |          |           |
| View evals                   |   ✓   |     ✓     |     ✓    |     ✓     |
| Manage evals                 |   ✓   |     ✓     |          |           |
| View guardrails              |   ✓   |     ✓     |     ✓    |     ✓     |
| Manage guardrails            |   ✓   |     ✓     |     ✓    |           |
| View security alerts         |   ✓   |     ✓     |     ✓    |     ✓     |
| Manage security alerts       |   ✓   |           |     ✓    |           |
| View security rules          |   ✓   |     ✓     |     ✓    |     ✓     |
| Manage security rules        |   ✓   |           |     ✓    |           |
| View logs                    |   ✓   |     ✓     |     ✓    |     ✓     |
| View traces                  |   ✓   |     ✓     |     ✓    |     ✓     |
| View audit trail             |   ✓   |     ✓     |     ✓    |     ✓     |
| View telemetry export        |   ✓   |     ✓     |     ✓    |           |
| Manage telemetry export      |   ✓   |     ✓     |          |           |
| View request tester          |   ✓   |     ✓     |     ✓    |     ✓     |
| View SSO                     |   ✓   |     ✓     |     ✓    |     ✓     |
| Manage SSO                   |   ✓   |           |     ✓    |           |

## Custom roles

With Manage roles, click **Add custom role** under **Settings → Roles** in the [dashboard](https://gateway.merge.dev/settings/roles) to add an editable column to the matrix. For example, a "Routing editor" role might hold Manage routing, View projects, and View API keys.

* Role names must be unique within the organization
* A role with members can't be deleted until you reassign them
* Roles are flat, with no inheritance

## Assign roles to members

Invite members and change their roles under **Settings → Organization**, with Manage users.

* An invitation carries the role granted on acceptance and expires after 7 days. Resending restarts the 7 days.
* A role change takes effect immediately and records the old and new role in the [audit trail](/merge-gateway/security/audit-trail)
* You can't remove the last Admin of an organization

Every role and membership change is audited, role edits with a field-level diff.

## Next steps

#### [Audit trail](/merge-gateway/security/audit-trail)

See every privileged action and who performed it

#### [Per-customer restrictions](/merge-gateway/security/per-customer-restrictions)

Block or pin models per customer (Manage organization settings)

#### [Prompt injection protection](/merge-gateway/security/prompt-injection-protection)

PI settings need Manage security rules