Appearance
Fresh 2026
Roles and permissions
Reference for Merge Gateway's role-based access control. Covers the four built-in roles (Admin, Developer, Security, Read Only), the 29 fine-grained permissions grouped by resource, how to create custom roles, how role assignments flow through invitations and the members page, and how every RBAC change is recorded in the audit trail.
Every member of a Gateway organization holds exactly one role. Each role is a named bundle of permissions, and every privileged action requires one or more permissions to succeed. Use the built-in roles for the common case, or define custom roles to match how your team is organized.
Built-in roles
Four system roles ship with every organization. They cannot be edited or deleted.
| Role | Intended for | Permissions |
|---|---|---|
| Admin | Org owners and senior platform engineers | All 29 permissions |
| Developer | Day-to-day engineers building on Gateway | View access on most resources, plus manage access on guardrails, routing, projects, and Build Your Own Router. No access to billing, and no management of users, roles, credentials, API keys, organization settings, security alerts, security rules, or SSO. |
| Security | Security engineers and admins of identity, secrets, and security policy | Full management of users, roles, credentials, API keys, guardrails, security alerts, security rules, and SSO. Read-only access to organization settings, routing, projects, Build Your Own Router, logs, audit trail, and request tester. No billing access. |
| Read Only | Auditors, support, observers | Every view permission except view billing |
System roles are immutable. To grant a slightly different permission set, create a custom role instead.
Permissions catalog
There are 29 permissions across 16 resources. Most resources have a "Manage" permission for create, update, and delete, and a "View" permission for read access. Three resources (Logs, Audit trail, and Request tester) are view-only.
The matrix below mirrors what you'll see in Settings → Roles. Each row is a permission, each column is a built-in role.
| Permission | Admin | Developer | Security | Read Only |
|---|---|---|---|---|
| View users | ✓ | ✓ | ✓ | ✓ |
| Manage users | ✓ | ✓ | ||
| View roles | ✓ | ✓ | ✓ | ✓ |
| Manage roles | ✓ | ✓ | ||
| View API keys | ✓ | ✓ | ✓ | ✓ |
| Manage API keys | ✓ | ✓ | ||
| View credentials | ✓ | ✓ | ✓ | ✓ |
| Manage credentials | ✓ | ✓ | ||
| View organization settings | ✓ | ✓ | ✓ | ✓ |
| Manage organization settings | ✓ | |||
| View billing | ✓ | |||
| Manage billing | ✓ | |||
| View projects | ✓ | ✓ | ✓ | ✓ |
| Manage projects | ✓ | ✓ | ||
| View routing | ✓ | ✓ | ✓ | ✓ |
| Manage routing | ✓ | ✓ | ||
| View Build Your Own Router | ✓ | ✓ | ✓ | ✓ |
| Manage Build Your Own Router | ✓ | ✓ | ||
| View guardrails | ✓ | ✓ | ✓ | ✓ |
| Manage guardrails | ✓ | ✓ | ✓ | |
| View security alerts | ✓ | ✓ | ✓ | ✓ |
| Manage security alerts | ✓ | ✓ | ||
| View security rules | ✓ | ✓ | ✓ | ✓ |
| Manage security rules | ✓ | ✓ | ||
| View SSO | ✓ | ✓ | ✓ | ✓ |
| Manage SSO | ✓ | ✓ | ||
| View logs | ✓ | ✓ | ✓ | ✓ |
| View audit trail | ✓ | ✓ | ✓ | ✓ |
| View request tester | ✓ | ✓ | ✓ | ✓ |
Custom roles
Custom roles let you slice the permission set however your team needs. For example, a "Routing Editor" role that grants Manage routing plus View projects plus View API keys and nothing else, or a "Billing Manager" role that only includes billing permissions.
Create, edit, and delete custom roles from Settings → Roles in the Gateway dashboard. Only members holding the Manage roles permission see the editing controls.
A few rules apply:
- Role names must be unique within an organization. Creating a role with a name that's already in use fails.
- System roles can't be edited or deleted. The matrix shows them as read-only columns.
- A role with members assigned can't be deleted. Reassign those members to another role first, then retry.
Deleting a role is blocked if members are assigned to it. Reassign members to a different role first, then retry the delete.
Permission Matrix UI
Open Settings → Roles in the Gateway dashboard to see the permission matrix:
- Each row is a permission, labeled with its human-readable name
- Each column is a role. System roles render as read-only columns. Custom roles render as editable columns with a checkbox grid.
- The Add custom role button in the card header inserts a new editable column at the right edge of the matrix and scrolls to it. The form lives inside the table itself. Fill in the role name above the column, then toggle permissions row by row.
Permission checks are enforced both on the server and in the dashboard. If you don't hold a required permission, gated buttons and menu items render as disabled, with a tooltip explaining the missing access.
Assigning roles to users
Invitations
Org admins invite new members from Settings → Members. Each invitation:
- Requires the inviter to hold the Manage users permission
- Carries a role selection. The invitee will hold that role immediately on acceptance.
- Expires after 7 days. After expiry, the invitee sees a "this invitation has expired" message, and the inviter can send a fresh one from the same page.
- Writes a
MEMBER_INVITEDaudit event on send and aMEMBER_JOINEDevent when accepted
You can resend or revoke a pending invitation from the same page. Both actions emit their own audit entries (MEMBER_INVITATION_RESENT, MEMBER_INVITATION_REVOKED) and require Manage users.
Role changes
To change an existing member's role, use the role selector in the members table. The change requires Manage users and emits a MEMBER_ROLE_CHANGED audit event with the old and new role names.
A member always holds exactly one role at a time. There is no multi-role assignment. If you need a specific combination of permissions for a user, create a custom role with that exact combination and assign them to it.
Audit trail integration
Every RBAC operation writes an entry to the audit trail:
| Action | Event |
|---|---|
| Create a custom role | ROLE_CREATED |
| Edit a role's name or permissions | ROLE_UPDATED (with a field-level diff) |
| Delete a custom role | ROLE_DELETED |
| Send an invitation | MEMBER_INVITED |
| Accept an invitation | MEMBER_JOINED |
| Resend an invitation | MEMBER_INVITATION_RESENT |
| Revoke an invitation | MEMBER_INVITATION_REVOKED |
| Change a member's role | MEMBER_ROLE_CHANGED |
| Remove a member | MEMBER_REMOVED |
Use the audit trail to answer "who granted this user admin?" or "when did this role lose a permission?". The diff is captured on every UPDATE event.
FAQ
No. Each member holds exactly one role per organization. If a user belongs to multiple orgs, they have one role in each.
No. System roles are immutable so the baseline permission sets stay predictable across orgs. To customize, create a new role with the permission set you need.
The delete is rejected. Reassign affected members to a different role, then retry the delete.
No. Roles are flat permission sets. The Admin role explicitly enumerates every permission, and does not derive from any other role.
7 days. After expiry, the invitee gets a "this invitation has expired" message. The inviter can resend a fresh invitation from the same page.
Next steps
See every privileged action and the role of the user who performed it
Blocklist operations require the Manage organization settings permission
PI settings live behind Manage security rules for writes, View security rules for reads