Custom Roles

When no built-in role fits, an Owner can compose a custom role from the permission catalog. A custom role sets an access level for each module and, where you need it, for each page inside a module. Anything the role does not grant is No access.

Where to find them

Go to Organization Settings → Custom Roles. The list shows each role with these columns:

Custom roles belong to one organization. Every project in that organization can use them.

Create a custom role

Setting permissions

Access levels

Each module and page offers only the levels that mean something for it. A read-only page such as Risk Dashboard offers only No access and Read.

Pages tab

The Pages tab is laid out like the sidebar, with a section per sidebar heading (Discover AI, Gauge AI, Budget AI, Governance) and a Settings & administration section for settings tabs and data permissions that have no sidebar page.

• Each row is a page (or a group of pages that share one permission) with a level dropdown.
• A page that you have not set shows Inherit from its module, with the inherited level. Select a level to override it, or the reset icon to go back to inheriting.
• An override wins in both directions: you can turn one page off inside a module you granted, or grant one page inside a module set to No access.
• Set all pages… on a section heading applies one level to every page in it.
• Filter pages… narrows the list by page name or key.
• Module defaults (advanced) sets the fallback level for a whole module at once. It also grants the module-wide permissions that no single page carries, such as configuring notification automations in Governance and running evaluation jobs in Gauge AI. Modules marked Sensitive (Budget AI, PII / raw-prompt content, Integrations & service accounts, Tenant security, Billing) deserve extra care.

Some pages sit under a sidebar heading that differs from the module that controls them. Tracing and Sessions appear under Discover AI but inherit from Governance. AI Agent Center appears under Discover AI but belongs to Gauge AI. AI Inventory appears under Gauge AI but belongs to Governance. The row always names the module it inherits from.

Permission catalog

Sub-pages offer only the levels that apply to them. For example, Governance's request queue offers Admin (final approval), while AI Violations is read-only. A module level above what a page offers resolves down to the page's highest level.

JSON tab

The JSON tab shows the same permissions as an object of keys and levels. Values are READ, WRITE or ADMIN. Omit a key to inherit its module's level.

• Page keys follow the sidebar: <heading>.<page>, for example discoverAi.tracing.
• A bare heading key such as "discoverAi": "READ" expands into one key per page under that heading.
• Module keys (shadowAi, roiAi, guardianAi, gatewayAi, auditLogs, piiRawPrompt, dataExport, userDataExport, agentDataExport, userRoleManagement, integrations, tenantSecurity, billing, antsAssist, trailmap) and their dotted sub-module keys (for example guardianAi.tracing) are always accepted. Module keys are what the platform stores.
• Settings permissions keep their module spelling, for example integrations.apiKeys or tenantSecurity.dataRetention.
• Unknown keys, customRoleAuthoring, and levels a key does not offer are rejected with an error that names the key. The key reference under the editor lists every valid key.

Separation of duties

Some combinations are blocked in every custom role, whoever creates it:

The check counts a module at the highest level held by the module or any of its pages, so a rule cannot be avoided by granting only pages.

Assign a custom role

Custom roles are assigned in the same places as built-in roles. The role dropdowns show a Custom roles group below the built-in roles.

• Organization level: in Organization Settings → Members, pick the custom role in a member's role dropdown. The role applies in every project where the member has no project role.
• Project level: in Project Settings → Members, pick the custom role as the member's project role. It replaces their organization role in that project. Project-level assignment needs the rbac-project-roles entitlement.
• Invitations: when you select Add member, choose a custom role as the Organization Role or Project Role. The invitee receives it when they join.
• Identity provider groups: map an Okta or other identity provider group to the custom role, at organization or project scope, with group role mappings. Members get the role at sign-in and on SCIM group changes, so least-privilege roles follow the groups you manage in your identity provider.

A membership holds either a built-in role or a custom role at each level, never both. Assigning a custom role requires the Owner role and is checked against your own access. Changing an existing member's role asks for step-up verification. Expired roles appear in the dropdown marked Expired and cannot be selected.

The roles attribute in SCIM provisioning sets built-in roles only. Use group role mappings to assign custom roles from your identity provider.

Edit, expire and delete

• Edit: select the edit icon, change the role, and select Save changes. Step-up verification is required. The new permissions apply to everyone who holds the role. Their memberships do not change.
• Expiry: after the expiry date, the role grants nothing. Members who hold it keep the membership but lose all access it gave until you extend the date or assign another role.
• Delete: select the delete icon and confirm Delete custom role?. The dialog says how many members hold it. They fall back to the role None and lose the access the custom role granted.
• A custom role that grants nothing does not let its holder open a project. The editor warns you: "Grants nothing. A member holding only this role cannot open the project."

Creating, editing and deleting custom roles, and assigning them, are recorded in Audit Logs.

Examples

Next steps

• Members & Roles: built-in roles and member management.
• Access Control (RBAC): how roles, modules and scopes fit together.