1. Docs
  2. Administrators and Roles
  3. Compose an Administrator Role

Compose an Administrator Role

Create a custom administrator role from the capability catalog in the Admin Workspace, read what each capability permits, and delete a role nobody holds.

Create a role from the catalog

In the Admin Workspace, Administrators → Roles lists the built-in roles and any custom ones, each showing how many capabilities it carries and how many people hold it. A role is composed from the platform's fixed catalog rather than typed in, which is what keeps a delegated administrator from inventing authority nobody granted.

Application
Admin Workspace
Path
AdministratorsRoles
Opens with
  • admin_governance.view Read the administrator roles that exist and see who holds each one. Enough to answer who can do what, without being able to change it.
Context
Account-wide, for administrators who govern the Account.
Create a role from the catalog
Open Administrators → Roles from the left nav and click New administrator role ("Compose from the catalog"). The Create administrator role wizard opens.On Name the role, name it and choose where it applies: Account-wide, or One Environment. This cannot be changed afterwards, because every grant of the role depends on it.On Pick the capabilities, select a small, coherent set. Each entry states what it lets someone do and which product it opens. The picker offers only the capabilities the scope you chose can hold, and never the owner-only one, deleting the account.Click Create role. A Role created. toast appears and the role is listed with the capability count you chose. Grant it from Administrators → Users → Assignments.To change a custom role later, open its card's menu and click Edit role, or open the role and click Edit capabilities. A Role updated toast confirms the change. Built-in roles cannot be edited.

Read what a capability permits

Administrators → Capabilities is the reference behind the wizard: every capability the platform defines, what it lets someone do, which product it opens, and which of your roles grant it.

Application
Admin Workspace
Path
AdministratorsCapabilities
Opens with
  • admin_governance.view Read the administrator roles that exist and see who holds each one. Enough to answer who can do what, without being able to change it.
Context
Account-wide, for administrators who govern the Account.
Read what a capability permits
Open Administrators → Capabilities from the left nav.Filter by product: Both products, Workspace (administering people, access, and billing), or Developer Console (applications, environments, keys, and integrations). Filter by scope: Account-wide or Per environment.Read Granted by on each row. Every one of your roles that carries the capability appears as a chip; a capability carried by none reads No role yet; owner-only ones read Owner only: no role can grant this.Search by key or description to narrow the list. When nothing matches, No capability matches offers Clear filters.

Delete a role

A custom role can be deleted only once nobody holds it. Built-in roles cannot be deleted at all.

Delete a role
On Administrators → Roles, open the role's card menu and click Delete role.While anyone still holds the role, deletion is refused: This role is still granted to people. Revoke those assignments on Users first. Revoke them on Administrators → Users → Assignments, then try again.The Delete this role? dialog warns that the role will be removed and that this cannot be undone. Confirm; a Role deleted toast appears and the role leaves the list.
If you don't see this

Each control on these pages exists only for someone who may use it. When something described above is missing, one of these is why:

Roles offers no Create role, Edit role or Delete role. Composing roles needs admin_governance.manage. With admin_governance.view alone, Roles and Capabilities open and show every role and who holds it, and nothing on them can be changed.The wizard offers fewer capabilities than the Capabilities page lists. The picker is filtered to the scope you chose on the first step, and the owner-only capability is never offered to any role.A role offers no Edit role or Delete role. It is built in. Its name and capabilities are platform constants; create a custom role when you need something different.Delete role is refused. Someone still holds the role. The refusal names the remedy: revoke the grants first.
What an administrator role is and how one is composed → Every capability, described → Invite and manage administrators →
Environment
API version
v1.0
 On this page Was this page helpful?

Tell us how we can improve this guide.

Canopy