1. Docs
  2. API Reference
  3. Move or re-role an existing assignment

Move or re-role an existing assignment

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

Moves an assignment to another node, changes its role, or reschedules it, and records an assignment.updated audit event. For the dates, an omitted field is left unchanged and null clears that end of the window. Requires access.assign at the assignment's current node and, when moving, at the destination. A new role must also be on the caller's grant ceiling; otherwise the response is 403. A request that changes nothing returns the assignment as it is. Returns 404 for an assignment, destination node or active role not in the Environment, 400 for a system role or an inverted date window, and 409 when the identity already holds the target role at the target 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.

assignmentIdstring Required

Headers

  • If-Match

    Optimistic-lock version of the resource. Send the `version` field returned on read; the server rejects with 409 if the row has changed since.

Request body

application/json

nodeIdstring Optional
roleIdstring Optional
effectiveFromstring Optional

When access begins; null clears it so access starts now

effectiveTostring Optional

When access ends; null clears it so access never 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 PATCH "https://auth.canopy-io.com/portal/v1/accounts/value/applications/value/environments/value/workspace/assignments/value" \
  -H "If-Match: "3"" \
  -H "Authorization: Bearer $CANOPY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "nodeId": "string",
    "roleId": "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
POSTGrant an identity a role at a hierarchy node
DELETERemove an identity's role assignment
 Was this page helpful?

Tell us how we can improve this guide.

Canopy