1. Docs
  2. API Reference
  3. Change a member's role

Change a member's role

PATCH/api/v1/organizations/{id}/members/{identityId}

Replaces the member's role in this organization with role_id. A member holds exactly one role per organization, so this updates the existing membership in place; changing to the role already held is a no-op. Returns 404 when the identity is not a member. Requires the rbac.manage_assignments permission at the organization and emits organization.member.role_changed.

Authentication

Bearer TokenAuthorization Option A

JWT access token

API KeyX-API-Key Option B

API key for management-tier access

Path Parameters

idstring Required
identityIdstring Required

Request body

application/json

role_idstring Required

The replacement role. A member holds exactly one role per organization, so this updates the existing membership in place.

Responses

application/json

  • dataOrganizationMemberResponseDto*

application/json

  • errorApiErrorBodyDto*

application/json

  • errorApiErrorBodyDto*

application/json

  • errorApiErrorBodyDto*

Returned object

OrganizationMemberResponseDtoView all properties on this resource
Request
curl -X PATCH "https://auth.canopy-io.com/api/v1/organizations/value/members/value" \
  -H "X-API-Key: $CANOPY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "role_id": "string"
  }'
Response
{
  "data": {
    "id": "string",
    "identity": {
      "id": "string",
      "email": "string",
      "first_name": "string",
      "last_name": "string"
    },
    "role": {
      "id": "string",
      "name": "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
GETList organizations
POSTCreate an organization
GETGet an organization
PATCHUpdate an organization
DELETEDelete an organization
GETList an organization's members
POSTAdd a member to an organization
DELETERemove a member from an organization
GETList an organization's invitations
POSTInvite a member into an organization
DELETERevoke an organization invitation
 Was this page helpful?

Tell us how we can improve this guide.

Canopy