1. Docs
  2. API Reference
  3. Grant an identity a role at a hierarchy node

Grant an identity a role at a hierarchy node

POST/portal/v1/accounts/{accountSlug}/applications/{appSlug}/environments/{envSlug}/workspace/assignments

Grants an identity a role at a hierarchy node, with an optional effectiveFrom and effectiveTo window, and records an assignment.created audit event. Requires access.assign at nodeId, and the role must be on the caller's grant ceiling; otherwise the response is 403. Returns 404 when the node, the identity or an active role is not found in the Environment. Returns 400 for a system role or when effectiveFrom is not before effectiveTo, and 409 when the identity already holds that role at that node.

Authentication

Bearer TokenAuthorization

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

Path Parameters

accountSlugstring Required

The Account's slug. An unknown one answers 404.

appSlugstring Required

The Application's slug within the Account.

envSlugstring Required

The Environment's slug within the Application.

Request body

application/json

identityIdstring Required

Identity to grant the role to

roleIdstring Required

Identity role to grant

nodeIdstring Required

Hierarchy node the role is granted at

effectiveFromstring Optional

When the assignment becomes effective

effectiveTostring Optional

When the assignment expires

Responses

application/json

  • dataWorkspaceAssignmentResponseDto*

application/json

  • errorApiErrorBodyDto*

application/json

  • errorApiErrorBodyDto*

application/json

  • errorApiErrorBodyDto*

application/json

  • errorApiErrorBodyDto*

application/json

  • errorApiErrorBodyDto*

Returned object

WorkspaceAssignmentResponseDtoView all properties on this resource
Request
curl -X POST "https://auth.canopy-io.com/portal/v1/accounts/value/applications/value/environments/value/workspace/assignments" \
  -H "Authorization: Bearer $CANOPY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "identityId": "string",
    "roleId": "string",
    "nodeId": "string",
    "effectiveFrom": "string",
    "effectiveTo": "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"
  }
}
 Related endpoints
GETResolve the caller's operational authority in the Environment
GETList identities within the caller's operational scope
GETList an identity's responsibilities within the caller's scope
GETList the identity roles the caller may grant
GETList the hierarchy locations the caller may assign at
GETList the hierarchy nodes the caller can see in this Environment
GETList identity invitations within the caller's scope
POSTInvite an identity into a location with a role
GETList scoped operational activity within the caller's scope
GETDownload the scoped activity feed as CSV
GETHow long activity history is kept for this Account
POSTResend a scoped invitation
DELETERevoke a scoped invitation
PATCHMove or re-role an existing assignment
DELETERemove an identity's role assignment
 Was this page helpful?

Tell us how we can improve this guide.

Canopy