---
title: "Change a member's system role and custom roles"
method: POST
path: "/user-management/v1/update-user-role"
tags: ["User Management"]
---

# Change a member's system role and custom roles

`POST /user-management/v1/update-user-role`

## Request

- Base URL: `https://api.langdock.com`
- URL: `https://api.langdock.com/user-management/v1/update-user-role`
- Auth: HTTP bearer

Changes an active human member's workspace system role by email.
Send `member`, `editor`, or `admin`. Optional `customRoleIds` replaces
that member's custom roles. Omit it to keep them, except when the new
role is `admin`, which clears custom roles and extra permissions.
The call is authorized by the workspace API key's `USER_MANAGEMENT_API` scope
and does not run as the person who created the key.

## Request body

- UpdateUserRoleRequest
  - `email` string, email, required: Email address of the active workspace member
  - `role` 'member' | 'editor' | 'admin', required: Workspace system role. Values are lowercase.
  - `customRoleIds` string[]: Custom role UUIDs from `GET /user-management/v1/roles`. Omit the field to keep the member's current custom roles, except when `role` is `admin`. Send a list, including an empty list, to replace them. At most 15 IDs. Duplicate IDs count toward that limit and are applied once. System role names are not accepted.

## Response `200`

Role updated successfully

- UpdateUserRoleResponse
  - `status` 'success', required: Always "success" when the role is updated
  - `email` string, email, required: Email address of the updated member
  - `role` 'member' | 'editor' | 'admin', required: System role after the update
  - `customRoleIds` string[], required: Custom role IDs assigned to the member after this call, ordered by when each role was assigned. Empty after a promotion to `admin`.

## Other responses

- `400`: Invalid request, unknown custom role, custom roles sent with admin, or the change would leave the workspace without an active admin
- `401`: API key is missing, invalid, or expired
- `403`: API key is missing the USER_MANAGEMENT_API scope
- `404`: User is not an active human member of this workspace
- `500`: Internal server error

## Changes

- **2026-11-03** `c62bf90b4013`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/langdock/apis/langdock-api/changes/user-management/v1/update-user-role/post.md)

---

[API](https://skmtc.dev/langdock/apis/langdock-api.md) - [All operations](https://skmtc.dev/langdock/apis/langdock-api/llms.txt) - [OpenAPI document](https://skmtc.dev/langdock/apis/langdock-api/revisions/c62bf90b4013?raw)