Create and Manage Permissions in the Console

Using the Console

In the Developer Console, Access Control → Permissions is where you manage this Environment's permission catalog. Its Overview offers three entry points as action cards; for a first run-through, the Create Permission Group card is the most efficient: it lets you define a resource and generate a complete set of permissions for it in one pass. The Directory alongside lists every permission and is where you edit and delete them.

Application: Developer Console
Path: Access ControlPermissionsOverview
Opens with: env_permissions.manage Create, edit, and delete permissions and permission groups.
Context: Select an Application and an Environment in the switcher first; the page belongs to that Environment.

Create a permission group

Open Permissions from the left nav under Access Control. It's scoped to whichever Environment is active in the switcher. Someone who may manage permissions lands on the Overview hub; a view-only reader lands on the Directory.

Click Create group on the Create Permission Group card. The wizard opens on its first step, Name the resource for this group.

Type a single resource name (e.g. invoice, users, document) and click Next. The name becomes the group's category and prefixes every permission inside it.

The wizard pre-populates four standard actions: create, read, update, delete. Edit, remove, or add custom actions like approve or archive.

Click Create Group. A Permission group created confirmation opens with a View Permissions button; each action is now a permission in your catalog, categorised under the resource name.

Other entry points

Create Permission: click Create permission on its card for the single-permission dialog. Enter a Permission Key such as invoice.approve (lowercase, dot-separated; it cannot be changed later), a Name, an optional description, and a Category; the category select also offers + New category. Confirm with Create Permission; a Permission created confirmation opens.

Create & Assign: click Create & assign on its card for the three-step wizard that creates permissions across several resources and assigns them to roles in one pass. The card is disabled until the Environment has at least one role.

Application: Developer Console
Path: Access ControlPermissionsDirectory
Opens with: env_permissions.view Read the Environment's permission catalog.
Context: Select an Application and an Environment in the switcher first; the page belongs to that Environment.

Browse, edit, and delete permissions

Open Permissions → Directory from the left nav. The table lists the Environment's permissions with their Key, Description, Category, Source, and Created columns.

Type in the search box to narrow the list by key, description, or category, or pick a category from the All categories dropdown.

Click a row. The Permission Details drawer opens with a Where it is used group that lists every role granting the permission and how many identities hold each, or reads Not granted by any role. Clicking a role there opens the Roles page with that role selected.

Click Edit to change the description or category (choose + New category to create one), then Save Changes. The drawer updates in place. The key itself cannot be changed. When organizations are on, the list also holds Canopy's own canopy:organization.manage and canopy:access.manage permissions (Source System): only their descriptions can be edited, and they cannot be deleted.

Click Delete. The Delete permission dialog warns that deleting the permission removes it from every role that includes it and cannot be undone. Confirm with Delete; the drawer closes, the row disappears, and the roles that carried it simply lose it.

If you don't see this

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

Permissions 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_permissions.view.

You land on the Directory and there is no Overview, no create cards, and no Edit or Delete in the drawer. You hold env_permissions.view but not env_permissions.manage. Ask whoever administers your Account to grant it.

The Create & Assign card is greyed out. The Environment has no roles yet; create one first, then the wizard has something to assign to.

Create Permission stays disabled in the dialog. A required field is missing or the key is not valid: Permission Key, Name and Category are required (a new category also needs its Category Name), and the key must be lowercase and dot-separated, like resource.action.

The permission you created is missing. Permissions belong to one Environment. Check the Environment in the switcher: a permission 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 permissions through the API instead of using the Developer Console. Use this when you want to seed your permission catalog from code, automate setup, or keep Canopy in sync with the actions your application supports. Each API key is scoped to one Environment: POST /api/v1/permissions writes the new permissions into that Environment's catalog and nowhere else.

Endpoint

POST /api/v1/permissions

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

Example

Send all the permissions you want to create in a single request:

{
  "permissions": [
    { "key": "invoice.read",    "name": "View invoices",    "category": "Invoices" },
    { "key": "invoice.create",  "name": "Create invoices",  "category": "Invoices" },
    { "key": "invoice.update",  "name": "Edit invoices",    "category": "Invoices" },
    { "key": "invoice.delete",  "name": "Delete invoices",  "category": "Invoices" },
    { "key": "invoice.approve", "name": "Approve invoices", "category": "Invoices",
      "description": "Sign off an invoice for payment" }
  ]
}

Once created, these permissions appear in your permission catalog and can be assigned to roles.

View full API reference →

Environment

API version

v1.0

On this page

Was this page helpful?

Tell us how we can improve this guide.