1. Docs
  2. Permissions
  3. Quickstart

Quickstart

Walk through defining your permissions end-to-end.

Using the Dashboard

The Permissions page is where you manage this Environment's permission catalog. The header has three entry points; for a first run-through, the Create Permission Group wizard is the most efficient — it lets you define a resource and generate a complete set of permissions for it in one pass.

Create a permission group
Open the Permissions page from the left nav under Access Control — it's scoped to whichever Environment is currently active in the workspace switcher.Click Create Permission Group in the page header. The wizard opens to step one.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. Each action becomes a permission in your catalog, all categorised under the resource name. The wizard closes and the new permissions appear in the list.
Other entry points
Create Permission: single-permission dialog. Use this when you only need to add one new permission to an existing or new group.Create & Assign: three-step wizard that creates permissions across multiple resources and assigns them to roles in one pass. Use this when you're setting up a new feature area end-to-end.
First time setting up?

When you land on a fresh Environment — the dashboard seeds every Account with a Development and Production env at signup, both empty — the Overview page shows a banner that reads "Your roles & permissions setup is incomplete." Click Complete Roles & Permissions Setup to open the Setup Guide on its Roles & Permissions tab — an interactive slide-out panel that walks you through every foundational step end-to-end. Each step links directly to the right page and surfaces contextual help alongside, so you don't have to bounce between docs and the dashboard to figure out where to click next.

What the guide walks you through:

Create permissionsCreate rolesAssign permissions to roles

Using the API

You can also create permissions through the API instead of using the dashboard. 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",     "description": "View invoices",   "category": "Invoices" },
    { "key": "invoice.create",   "description": "Create invoices", "category": "Invoices" },
    { "key": "invoice.update",   "description": "Edit invoices",   "category": "Invoices" },
    { "key": "invoice.delete",   "description": "Delete invoices", "category": "Invoices" },
    { "key": "invoice.approve",  "description": "Approve invoices","category": "Invoices" }
  ]
}

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

 View full API reference →
Environment
On this page
Canopy