1. Docs
  2. Assign Roles
  3. Quickstart

Quickstart

Assign roles to identities — one at a time or many at once.

Flat RBACHierarchy RBAC

Using the Dashboard

There are two flows on the Identities page: open a single identity's drawer to manage their assignments one at a time, or tick checkboxes across multiple rows to assign the same role to all of them at once.

Assign a role to a single identity
Open Identities → Directory 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 on the one identity you want to grant access to. The action bar slides in from the top, showing 1 identity selected.Click Assign Role in the action bar. The dialog opens labeled with the selected identity.Pick the role. In flat RBAC the node is fixed to your Environment's root, so there's nothing else to pick.(Optional) Set Effective from or Effective to dates if the access should start later or end automatically.Click Assign. The assignment lands under the Assignments tab and the role's permissions take effect immediately.
Bulk-assign a role to multiple identities
On Identities → Directory, tick the checkbox next to each identity you want to grant the role to. The action bar shows the selection count.Click Assign Role in the action bar. The dialog opens labeled with the number of identities you're assigning to.Pick the role. In flat RBAC the node is fixed to your Environment's root.(Optional) Set Effective from or Effective to dates.Click Assign. Successful assignments take effect immediately. If any identity already had the role, the toast reports how many were assigned versus how many were skipped.
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 "You haven't invited any users or assigned them roles yet." Click Complete Invite & Assign Users Setup to open the Setup Guide on its Invite & Assign Users tab — an interactive slide-out panel that walks you through inviting identities and assigning them roles. 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:

Invite identitiesAssign roles to identities

Using the API

Two endpoints cover the same two flows. Use the single-create endpoint when adding access for one identity at a time; use the bulk-create endpoint when provisioning a cohort, syncing from an HR system, or backfilling roles after a migration. Each API key is scoped to one Environment — assignments are created in that Environment and nowhere else.

Single — 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 take effect immediately at that node and every descendant — no separate evaluation step or cache flush is required.

 View full API reference →
Bulk — Endpoint 
POST /api/v1/assignments/bulk-create

Same auth as the single-create endpoint. The body is an array of assignments processed independently.

Example

Send an array of { identity_id, node_id, role_id } entries. Per-item effective_from / effective_to are optional:

{
  "assignments": [
    {
      "identity_id": "9d7e3a6f-2c4b-4e1a-9f5d-1a3c4b5d6e7f",
      "node_id":     "0aa1b2c3-d4e5-4f6a-7b8c-9d0e1f2a3b4c",
      "role_id":     "5e1f2a3b-4c5d-4e6f-7a8b-9c0d1e2f3a4b"
    },
    {
      "identity_id": "ab1cd2ef-3456-4789-abcd-ef1234567890",
      "node_id":     "0aa1b2c3-d4e5-4f6a-7b8c-9d0e1f2a3b4c",
      "role_id":     "5e1f2a3b-4c5d-4e6f-7a8b-9c0d1e2f3a4b"
    }
  ]
}

The endpoint returns 200 OK with { summary, results } when every item succeeded, or 207 Multi-Status with the same shape when at least one item failed (e.g., the identity already had the role). Iterate results to know which entries landed and which were skipped — partial success is the norm here, not an error.

 View full bulk-create reference →
Environment
On this page
Canopy