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.manage Create administrator roles, decide which capabilities each one carries, and grant them to people. This is the capability that hands out authority, so treat it as the most consequential one on the list after deleting the account.
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. Entries marked Owner only: no role can grant this cannot be selected.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 the Granted by column. A capability carried by one of your roles names that role; one 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 the Directory 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 is not under Administrators. Composing roles needs admin_governance.manage. With admin_governance.view alone you see who holds each role and can read the Capabilities reference, but cannot open Roles.A capability cannot be selected in the wizard. It is owner-only, or it is outside the ceiling of what your own role may hand out.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