Roles and permissions

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.

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.

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.

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_INVITED audit event on send and a MEMBER_JOINED event 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:

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