Roles and permissions

Every member of a Gateway organization holds exactly one role. Each role is a named bundle of permissions, and every privileged API endpoint 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

Three system roles ship with every organization. They cannot be edited or deleted.

Permissions catalog

Permissions are grouped into 13 resources. Most resources have a manage_* permission for create / update / delete and a view_* permission for read access. Logs is the one resource without a manage_* permission - visibility is the only operation.

The control-plane API exposes the canonical list at GET /organizations/{org_id}/permissions, which returns both the machine codename and the human-readable display name for each.

Custom roles

Custom roles let you slice the permission set however your team needs - for example, a “Routing Editor” role that grants manage_routing + view_projects + view_api_keys and nothing else, or a “Billing Manager” role that only includes billing permissions.

All four operations require the manage_roles permission.

Permission Matrix UI

Open Settings → Roles in the Merge 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 badges (their checkboxes are non-interactive). Custom roles render as editable columns with a checkbox grid.
• The “Create custom role” panel opens from the right of the page and shares the same matrix layout.

Behind the matrix is a feature flag named rbac. While that flag is on (the default for production orgs), permission checks are enforced server-side. When the flag is off - for example, in early-pilot organizations - the frontend bypasses all checks and returns true for every permission.

Assigning roles to users

Invitations

Org admins invite new members from Settings → Members. Each invitation:

• Requires the inviter to hold manage_users.
• Carries a role selection - the invitee will hold that role immediately on acceptance.
• Expires after 7 days.
• Writes a MEMBER_INVITED audit event on send and a MEMBER_JOINED event when accepted.

You can resend (MEMBER_INVITATION_RESENT) or revoke (MEMBER_INVITATION_REVOKED) a pending invitation from the same page. Both actions emit their own audit entries.

Role changes

To change an existing member’s role, use the role selector in the members table. The underlying call is:

$
PATCH /organizations/{org_id}/members/{membership_id}?role_id={role_id}

This also requires manage_users and emits a MEMBER_ROLE_CHANGED audit event with a diff between the old and new role names.

A member always holds exactly one role at a time. There is no concept of multi-role assignment; if you need a custom permission combination for a user, create a role that has that exact combination and assign them to it.

Permission checks at the API layer

Every mutating control-plane endpoint is gated by require_permission(...). The dependency accepts one or more permission codenames; the caller’s role must hold at least one of them for the request to proceed.

For example, the blocklist endpoints declare:

• GET /organizations/{org_id}/blocklist-rules → requires view_org_settings or manage_org_settings
• POST /organizations/{org_id}/blocklist-rules → requires manage_org_settings

If the caller’s role doesn’t satisfy the requirement, the request fails with 403. To find the permission required for any given endpoint, check the OpenAPI reference or the endpoint’s require_permission(...) declaration in the control-plane source.

Audit trail integration

Every RBAC operation writes an entry to the audit trail:

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

Next steps