1. Docs
  2. Permissions
  3. Quickstart

Quickstart

Walk through defining your permissions end-to-end.

Using the Console

The Permissions page is where you manage this Environment's permission catalog. The page 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.

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 the Create Permission Group card (under Create permissions). 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 (Canopy 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 Console 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 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",     "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
API version
v1.0
 On this page Was this page helpful?

Tell us how we can improve this guide.

Canopy