1. Docs
  2. Assign Permissions
  3. Quickstart

Quickstart

Assign your first role to an identity end-to-end.

Flat RBACHierarchy RBAC

Using the Dashboard

Assignments live on the Identities Directory page. From the Identities tab you can bulk-select one or more identities and assign a role at a node in a single dialog. If the user doesn't exist yet, the Invite & Assign action on the Identities hub invites them and pre-assigns the role in one flow — see the alternative path below.

Assign a role
Open the Identities → Directory page from the left nav under Access Control — it's scoped to whichever Environment is currently active in the workspace switcher.On the Identities tab, tick the checkbox next to one or more identities you want to grant access to.Click Assign Role in the bulk action bar that appears at the top.In the dialog, pick the role you want to grant and pick the node it applies at. In flat RBAC only the Environment's root node is selectable; in hierarchy RBAC any node in the tree.(Optional) Set Effective from or Effective to dates if the access should start later or end automatically. Leave blank for permanent, immediate access.Click Assign. The new assignments appear under the Assignments tab and the role's permissions are immediately in effect for those identities at that node and every descendant.
Alternative entry point
Invite & Assign: from the Identities page action hub, this opens a dialog that invites a brand-new user and pre-assigns them a role at a node in a single flow. Use this when the user doesn't exist in your Account yet — when they accept the invite, the assignment is already in place.
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 two setup banners — one for Roles & Permissions, one for Invite & Assign Users. Each opens the Setup Guide on the matching tab. The slide-out panel walks you through every onboarding step, with each step linking directly to the right page and surfacing 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 rolesInvite identitiesAssign roles to identities

Using the API

You can also create assignments through the API instead of using the dashboard. Use this when you're provisioning access in bulk, syncing from an external HR system, or scheduling future access programmatically. Each API key is scoped to one Environment — POST /api/v1/assignments creates the assignment in that Environment and nowhere else.

Endpoint 
POST /api/v1/assignments

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

Example

Send the identity, node, and role IDs in the request body. effective_from and effective_to are optional ISO-8601 timestamps:

{
  "identity_id": "9d7e3a6f-2c4b-4e1a-9f5d-1a3c4b5d6e7f",
  "node_id":     "0aa1b2c3-d4e5-4f6a-7b8c-9d0e1f2a3b4c",
  "role_id":     "5e1f2a3b-4c5d-4e6f-7a8b-9c0d1e2f3a4b",
  "effective_from": "2026-05-01T00:00:00Z",
  "effective_to":   "2026-12-31T23:59:59Z"
}

The response returns the created assignment with its id and computed lifecycle state. The role's permissions are immediately in effect for the identity at that node and every descendant — no separate evaluation step or cache flush is required.

 View full API reference →
Environment
On this page
Canopy