1. Docs
  2. Roles
  3. Quickstart

Quickstart

Walk through creating your first role end-to-end.

Using the Dashboard

The Roles page 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.

Create a role
Open the Roles page from the left nav under Access Control — it's scoped to whichever Environment is currently active in the workspace switcher.Click Create Role in the page header. 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.Click Create. The new role appears in the left-hand list and is automatically selected — its permission grid loads in the right-hand panel, ready for you to tick the permissions it should grant.
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 roles through the API instead of using the dashboard. 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 dashboard to manage them in the UI.

 View full API reference →
Environment
On this page
Canopy