Create and Manage Roles in the Console

Using the Console

In the Developer Console, Access Control → Roles is where you manage this Environment's roles. Each role is a named bundle of permissions you can assign to identities: define a role once, then reuse it for everyone who needs the same access. The page is a split view: the roles list on the left, and the selected role's permissions on the right.

Application: Developer Console
Path: Access ControlRoles
Opens with: env_roles.view Read the Environment's roles and the permissions each one grants.
Context: Select an Application and an Environment in the switcher first; the page belongs to that Environment.

Create a role

Open Roles from the left nav under Access Control. It's scoped to whichever Environment is active in the switcher. The first role in the list is selected automatically, with its permissions shown on the right.

Click the + button (Create Role) at the top of the Custom Roles list (left panel). The Create Custom Role dialog opens.

Enter a Role Name like Regional Manager. Common starting points are Owner, Admin, Editor, and Viewer.

(Optional) Add a description so teammates understand what the role is for, and under Start From pick a role whose permissions the new one copies. With organizations on, Scope chooses Environment (available in every organization) or One organization, then the Organization it belongs to: that role is held only inside it.

Click Create Role. A Role created toast appears; the new role is added to the left-hand list and selected, and its permission grid loads on the right, ready for you to tick the permissions it should grant.

With organizations on, the list has two tabs: Environment for the roles every organization shares, and Organizations for each organization's own, each row naming its organization. With none yet, the Organizations tab reads No organization has a role of its own yet., and Create your first custom role opens the dialog with One organization chosen. The selected role carries the badge Environment or Organization: <name>. An organization's page has a Roles tab too, listing its own roles; a row opens the role here.

Set the role's permissions

With the role selected, the right-hand panel lists the Environment's permissions as checkboxes, grouped by category. When organizations are on, Canopy's own canopy:organization.manage and canopy:access.manage appear under a separate Canopy capabilities heading and are granted the same way; the role that carries the first is the one whose holders administer their own organization, the role that carries the second administers access at the node it is held at and beneath.

Tick the permissions the role should grant, or untick ones it should lose. Save Changes enables as soon as something differs from what is saved.

Click Save Changes. A Permissions saved toast appears and the role's permission count updates. Saving replaces the whole set, so the checkboxes always show exactly what the role grants.

Selecting another role while you have unsaved ticks opens the Unsaved changes dialog, with Save Changes, Discard changes, and Cancel.

Rename, deactivate, or delete a role

Rename: click the pen icon beside the role's name in the right-hand panel, type the new name, then press Enter or click Save (Escape or Cancel discards it). A Role renamed toast appears and the list updates. The description edits the same way, with a Role updated toast.

Deactivate: click Deactivate. The Deactivate Role dialog explains that the role will be hidden from role pickers and grant no permissions while inactive; existing assignments are kept, so everyone holding it loses its access until it is reactivated. Confirm with Deactivate; a Role deactivated toast appears and the button becomes Activate.

Reactivate: click Activate. A Role activated toast appears and the role is offered in pickers again, and everyone still assigned it gets its permissions back.

Delete: click Delete. The Delete Role dialog warns that the role will be permanently deleted and removed from every identity assignment, and that this cannot be undone. Confirm with Delete; a Role deleted toast appears and the role leaves the list. Deletion is refused while the role is the one an organization's directory gives arriving people, or one the Environment lets identity providers grant; take it out of those settings first.

If you don't see this

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

Roles is not in the left nav. Either no Application and Environment is selected yet (the Access Control group appears once one is), or your administrator role does not carry env_roles.view.

The page opens, but there is no Create Role button, no Save Changes, and no Deactivate or Delete. You hold env_roles.view but not env_roles.manage. Ask whoever administers your Account to grant it.

The role you created is missing. Roles belong to one Environment. Check the Environment in the switcher: a role created in Development does not exist in Production until you promote it.

First time setting up?

On a fresh Environment (every new Application is seeded with an empty Development and Production Environment), Access Control → Overview shows a banner that reads "Your roles & permissions setup is incomplete." Click Complete Roles & Permissions Setup to open the Setup guide, a floating checklist that opens on its first unfinished step. Each step links directly to the right page and offers help alongside, so you don't have to bounce between docs and the Console to figure out where to click next.

What the guide walks you through:

Create Permissions

Create Roles

Assign Permissions to Roles

Using the API

You can also create roles through the API instead of using the Developer Console. Use this when you want to seed your role catalog from code, automate setup, or keep Canopy in sync with the access tiers your application defines. Each API key is scoped to one Environment: POST /api/v1/roles creates the role in that Environment's catalog and nowhere else.

Endpoint

POST /api/v1/roles

Authenticate with your API key in the X-API-Key header.

Example

Send the role's name (and an optional description) in the request body:

{
  "name": "Regional Manager",
  "description": "Manages regional sales teams"
}

The response returns the created role with its id. Use that id with PUT /api/v1/roles/{id}/permissions to attach permissions, or jump back to the Console to manage them in the UI. Two optional fields shape a new role: organization_id makes it that organization's own role, and copy_from_role_id starts it with another role's permissions, and its description when you send none. The role copied is an Environment role or one of the same organization's own.

View full API reference →

Environment

API version

v1.0

On this page

Was this page helpful?

Tell us how we can improve this guide.