1. Docs
  2. API Reference
  3. Assign a role to an identity at a node

Assign a role to an identity at a node

POST/api/v1/assignments

Assigns a role to an identity at a specific hierarchy node, granting that role's permissions at the node and — through inheritance — at every descendant node. Authorization is evaluated as rbac.manage_assignments at the target node_id; the node must belong to the current Environment, the identity must have an active membership in it, and the role must be active and non-system (400 for system roles). Optional effective_from/effective_to schedule the assignment; a duplicate identity + role + node triple returns 409. Emits an assignment.created audit event.

Authentication

Bearer TokenAuthorization Option A

JWT access token. Never send alongside X-API-Key: a request carrying both is refused.

API KeyX-API-Key Option B

API key for management-tier access. Never send alongside an Authorization header: a request carrying both is refused.

Request body

application/json

identity_idstring Required
node_idstring Required
role_idstring Required
effective_fromstring Optional
effective_tostring Optional

Responses

application/json

  • dataAssignmentResponseDto*

application/json

  • errorApiErrorBodyDto*

application/json

  • errorApiErrorBodyDto*

application/json

  • errorApiErrorBodyDto*

application/json

  • errorApiErrorBodyDto*

Returned object

AssignmentResponseDtoView all properties on this resource
Request
curl -X POST "https://auth.canopy-io.com/api/v1/assignments" \
  -H "X-API-Key: $CANOPY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "identity_id": "string",
    "node_id": "string",
    "role_id": "string",
    "effective_from": "string",
    "effective_to": "string"
  }'
Response
{
  "data": {
    "id": "string",
    "identity_id": "string",
    "application_node_id": "string",
    "role_id": "string",
    "effective_from": "2026-04-20T12:00:00.000Z",
    "effective_to": "2026-04-20T12:00:00.000Z",
    "created_at": "2026-04-20T12:00:00.000Z",
    "updated_at": "2026-04-20T12:00:00.000Z"
  }
}
 Related endpoints
GETList all assignments across the Application
GETGet App-wide assignment summary
PATCHUpdate an assignment
DELETERemove an assignment
POSTBulk remove assignments
POSTBulk change role on assignments
POSTBulk-create role assignments. All-or-nothing: any failure rolls back the entire batch
 Was this page helpful?

Tell us how we can improve this guide.

Canopy