1. Docs
  2. Assign Roles
  3. Quick Start

Quick Start

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

Flat RBACHierarchy RBAC

Using the Console

There are two flows: open a single identity's drawer to manage their assignments one at a time, or use the Assign roles card on Identities → Overview to give one role to many members at once. Both offer the Environment's roles; an organization's own role is given from that organization's Members tab (Manage Organizations).

Assign a role to a single identity
Open Identities → Directory from the left nav under Access Control. It's scoped to whichever Environment is active in the Application and Environment switcher.Click the identity's row. Its drawer opens, listing the role assignments it already holds.Click Add Role Assignment. The Add Role Assignment dialog opens for that 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. Dates are days in your own time zone: access starts at the beginning of the first day and ends at the close of the last.Click Assign. A Role assigned toast appears, the assignment shows in the drawer and on the Assignments tab, and the role's permissions take effect immediately.
Bulk-assign a role to multiple identities
Open Identities → Overview from the left nav under Access Control and click the Assign roles card. The Assign roles dialog opens, listing the Environment's current members. The card is disabled until the Environment has at least one role.Tick each identity you want to grant the role to. Search and filters narrow the list, selections carry across pages, and the count beside the buttons shows how many are selected.Pick the Role. In flat RBAC the node is fixed to your Environment's root, shown as Applies at.(Optional) Set Effective from or Effective to dates; every selected identity gets the same window. Dates are days in your own time zone: access starts at the beginning of the first day and ends at the close of the last.Click Assign to selected. A toast reports how many were assigned and how many were skipped (for example, because they already held the role there), then you land on the Assignments tab.
First time setting up?

On a fresh Environment (every new Application is seeded with an empty Development and Production Environment), Access Control → Overview 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, a floating checklist that opens on its first unfinished invite or assignment step. Each step links directly to the right page and offers 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:

Invite IdentitiesAssign Role to Identity

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, its effective dates and its version. The role's permissions take effect immediately at that node and every descendant, with no separate evaluation step; apps that evaluate locally with the SDK see it once their cached grants expire or are cleared.

 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
API version
v1.0
 On this page Was this page helpful?

Tell us how we can improve this guide.

Canopy