Roles | Canopy Docs

Overview

Roles are collections of permissions. Rather than managing permissions one by one, you group related permissions into a role, then assign that role to identities. For example, an Invoice Viewer role might include only invoice.read, while an Invoice Manager role might include invoice.read, invoice.create, invoice.update, and invoice.approve. Roles simplify access management by letting you assign multiple permissions at once.

Scope

Roles are scoped to an Environment

When you create a role, you're creating it in the active Environment, the one selected in the Console's Application and Environment switcher, or by selecting its card on Tenant → Applications. Both set the same active Environment, so either one updates the other. Two Environments in the same Application keep fully independent role catalogs.

A role added in Development does not exist in Production until you promote it or create it there too

Renaming or removing a role only affects the Environment you're working in

A role's permission set, and every identity assignment that uses it, live in the same Environment as the role itself

Inside the organizations container a role is one of two kinds: an Environment role, assignable in every organization, or an organization's own role, created with organization_id and held only at that organization's node or beneath it (anywhere else is refused with 400 rbac.role_outside_organization). Names are unique within each kind: once among the Environment's roles and once among each organization's own, so an organization can have its own "Agent" beside yours. An organization never edits a shared role; it starts its own from a copy with copy_from_role_id.

Role lists answer the Environment's roles unless asked otherwise: GET /api/v1/roles?organization_id=… lists one organization's own, with scope=available what can be held inside it, and scope=all every role. Each role carries its scope (environment or organization) and organization_node_id, and on a list its organization_name.

Use the Promote Configuration to…, Export Configuration, and Import Configuration actions on the Environment card to move roles between Environments alongside the rest of the configuration. Only Environment roles travel: an organization's own roles are its data, kept through an import and never promoted.

View the Environments reference →

How Roles Are Used

Roles are assigned to identities at a specific point in your Environment's hierarchy. In flat RBAC, roles are assigned at the root level and apply across the entire Environment. Once assigned, the role grants all of its permissions to that identity.

Example

Continuing the invoice example:

Permissions

invoice.read

invoice.create

invoice.update

invoice.delete

invoice.approve

Roles

Role	Permissions
`Invoice Viewer`	`invoice.read`
`Invoice Manager`	`invoice.read`, `invoice.create`, `invoice.update`, `invoice.approve`
`Invoice Admin`	All invoice permissions

An identity assigned the Invoice Manager role can create, update, and approve invoices, but cannot delete them.

Next Step

Roles define access, but they don't apply until they are assigned.

Environment

API version

v1.0

On this page

Was this page helpful?

Tell us how we can improve this guide.