# Update a member's role

**PUT** `/users/{userId}/role`

Changes the role of a tenant member. The caller must hold a role with
authority over the requested role transition. Admins can shuffle
members between admin and agent; only Owners can mint or demote
Owners. A tenant must retain at least one Owner — demoting the last
one is rejected.

Authentication: bearerAuth
Required scopes: `user:assign_role_admin`, `user:assign_role_agent`, `user:assign_role_owner`
Allowed roles: `owner`, `admin`
Authorization: Assign a user role; required action depends on request body role.

## Parameters

- `userId` (path string, required)

## Request body

- `application/json`: `UpdateUserRoleRequest` required.

## Responses

- `200`: Member updated
- `400`: Invalid request. Codes:
  - `auth_user_invalid_role` — role is not one of owner/admin/agent
  - `auth_user_self_role_change_forbidden` — caller targeted themselves
- `403`: Caller lacks authority for this role change. Codes:
  - `auth_authz_user_assign_role_denied` — matrix rejects the new role (e.g. Admin attempting Owner)
  - `auth_user_role_assignment_forbidden` — caller cannot edit an Owner target
- `404`: Target user not found in the caller's tenant. Code:
  - `auth_user_not_found`
- `409`: Tenant invariant would be violated. Code:
  - `auth_user_last_owner_required` — demotion would leave zero Owners
- `default`: Error