Update a workspace member

Changes the member’s single workspace role and/or sets or replaces externalId. Send at least one field (400 NO_FIELDS_TO_UPDATE). Returns 409 ROLE_UNCHANGED when nothing would change.

Required scope: workspace.members.write

PATCH /api/public/v1/workspaces/{workspaceId}/members/{memberId}

Update a workspace member

cURL

curl --request PATCH \
  --url https://{platformHost}/api/public/v1/workspaces/{workspaceId}/members/{memberId} \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "roleId": "builtin.workspace.workbench_manager",
  "externalId": "00u1abcd2345"
}
'

200

{
  "success": true,
  "data": {
    "memberId": "0193f1c2-7a4e-7b10-9c3d-5e6f7a8b9c0d",
    "role": {
      "roleId": "builtin.workspace.restricted_member",
      "name": "RESTRICTED_MEMBER",
      "type": "system",
      "source": "direct"
    },
    "status": "pending",
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z",
    "revision": 1,
    "userId": "<string>",
    "email": "[e-mail]",
    "name": "<string>",
    "expiresAt": "2023-11-07T05:31:56Z",
    "externalId": "<string>",
    "attributes": {},
    "assignmentSource": "api",
    "projects": [
      {
        "id": "<string>",
        "role": {
          "roleId": "builtin.workspace.restricted_member",
          "name": "RESTRICTED_MEMBER",
          "type": "system",
          "source": "direct"
        },
        "name": "<string>"
      }
    ],
    "projectsTruncated": true
  }
}

Use this endpoint to change a workspace member’s role, set or replace their externalId, or do both. A member has one workspace role. Send at least one field, or the API returns 400 NO_FIELDS_TO_UPDATE. If nothing would change, the API returns 409 ROLE_UNCHANGED.

To avoid overwriting a concurrent change, send the ETag from your last read in the If-Match header. A mismatch returns 412 PRECONDITION_FAILED. Send an Idempotency-Key header so retries are safe. The request needs the workspace.members.write scope.

Authorizations

platformApiKeybearerPlatformKey

X-API-Key · string · header · required

Platform key, for example abl_ws_….

Headers

Idempotency-Key · string

Recommended on every write. A retry with the same key and body replays the first result instead of repeating the change. A different body returns 422 IDEMPOTENCY_KEY_REUSED; a retry while the first is still running returns 409 IDEMPOTENCY_IN_PROGRESS.

Required string length: 1 - 255

If-Match · string

The ETag from your last read. On a mismatch the request fails with 412 PRECONDITION_FAILED.

Example:

"W/\"3\""

Path Parameters

workspaceId · string · required

Minimum string length: 1

memberId · string · required

Minimum string length: 1

Body

application/json

roleId · string

Required string length: 1 - 256

externalId · string

Maximum string length: 1024

Response

200

application/json

Success

success · enum<boolean> · required

Available options: true

data · object · required

Show child attributes