Change a member's role (admin; role-capped, last-owner guarded)

PATCH

/v1/admin/orgs/{org_id}/members/{user_id}

• Production
• Local

Changes a member’s role. Role-capped to the actor’s own effective role; demoting the org’s LAST owner is refused (409 last_owner).

Authorizations

• ClerkSession

Parameters

Path Parameters

org_id

required

string

user_id

required

string

Request Body ^required

Change an existing member’s role. Role-capped: the actor cannot grant a role above their own effective role. Demoting the org’s last owner is refused (409).

object

role

required

string

Allowed values: owner admin member viewer billing

Responses

200

Updated membership.

One org membership row.

object

clerk_user_id

required

string

email

required

string

role

required

string

Allowed values: owner admin member viewer billing

created_at

required

string format: date-time

updated_at

required

string format: date-time

400

Invalid request.

The canonical error envelope. error is a stable machine code.

object

error

required

Stable error code (e.g. unauthorized, forbidden, not_found, invalid, quota_exceeded, rate_limited).

string

Example

forbidden

message

Human-readable detail (never leaks internals).

string

Example

missing required scope

401

Missing or invalid credential.

The canonical error envelope. error is a stable machine code.

object

error

required

Stable error code (e.g. unauthorized, forbidden, not_found, invalid, quota_exceeded, rate_limited).

string

Example

forbidden

message

Human-readable detail (never leaks internals).

string

Example

missing required scope

403

Authenticated but lacking the required scope, or out of quota.

The canonical error envelope. error is a stable machine code.

object

error

required

Stable error code (e.g. unauthorized, forbidden, not_found, invalid, quota_exceeded, rate_limited).

string

Example

forbidden

message

Human-readable detail (never leaks internals).

string

Example

missing required scope

404

Resource not found.

The canonical error envelope. error is a stable machine code.

object

error

required

Stable error code (e.g. unauthorized, forbidden, not_found, invalid, quota_exceeded, rate_limited).

string

Example

forbidden

message

Human-readable detail (never leaks internals).

string

Example

missing required scope

409

Resource conflict (e.g. a duplicate entry).

The canonical error envelope. error is a stable machine code.

object

error

required

Stable error code (e.g. unauthorized, forbidden, not_found, invalid, quota_exceeded, rate_limited).

string

Example

forbidden

message

Human-readable detail (never leaks internals).

string

Example

missing required scope