PATCH /api/v1/admin/orgs/:slug/members/:id/role

This page is auto-generated from src/admin/routes.ts. Do not edit by hand — see docs/dev/docs-auto-sync.md.

:warning: Heuristic extraction — not a contract. Response shapes below are mined from c.json(...) literals in the handler via an AST walker. Computed fields, ternaries, and non-literal returns are shown as placeholders. Refer to the linked source file for the authoritative behaviour.

PATCH /api/v1/admin/orgs/:slug/members/:id/role

Authentication

Requires the following capability(ies):

• members:w

Middleware

Other middleware observed on this route (heuristic):

• requireCapability
• roleEditBodyLimit

Description

PATCH /api/v1/admin/orgs/:slug/members/:id/role — change a member’s role to one of admin / member / viewer. Owner transitions are out of scope for this endpoint; use POST …/transfer-ownership for those.

:id is the Upwarden-side tenant_members.id (NOT the Stytch member id), matching the suspend / reactivate / remove endpoints from #422 / #398b.

Capability: members:w (same gate as the rest of the member-write surface in this file). Owner-only transitions are physically rejected below.

Responses

HTTP 404

{
  "error": "Org not found"
}

HTTP 400

{
  "error": "Invalid JSON body"
}

HTTP 400

{
  "error": "Body must be a JSON object"
}

HTTP 400

{
  "error": "role must be one of owner|admin|member|viewer"
}

HTTP 400

{
  "error": "Use POST /api/v1/admin/orgs/:slug/transfer-ownership to set the owner; this endpoint does not promote to owner."
}

HTTP 404

{
  "error": "Member not found"
}

HTTP 400

{
  "error": "Use POST /api/v1/admin/orgs/:slug/transfer-ownership to change the owner; this endpoint cannot edit an owner row."
}

HTTP 200 (default)

{
  "member_id": <member-expr>,
  "role": <member-expr>,
  "changed": false
}

HTTP 503

{
  "error": "step_up_lookup_failed",
  "message": "Could not verify the target member's MFA factor; retry in a moment."
}

HTTP 412

{
  "error": "step_up_required",
  "message": "Target role requires MFA at this tier. Ask the member to register a TOTP factor at /admin/ui/account/mfa before retrying.",
  "reason": "role_requires_mfa",
  "tier": <member-expr>
}

HTTP 409

{
  "error": "would_remove_last_admin",
  "message": "Cannot demote the last admin/owner — promote another member first, then retry."
}

HTTP 200 (default)

{
  "member_id": <targetMemberId>,
  "role": <requestedRole>,
  "previous_role": <fromRole>,
  "changed": true
}

Source

• File: src/admin/routes.ts
• Line: 3401