> ## Documentation Index
> Fetch the complete documentation index at: https://docs.langdock.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Update User Role

> Change an active member's workspace system role to member, editor, or admin

This endpoint changes an active human member's workspace system role by email. Send `member`, `editor`, or `admin`. Custom roles are not part of this endpoint.

The call is authorized by the workspace API key's `USER_MANAGEMENT_API` scope. It does not run as the person who created the key, so it keeps working after that admin leaves the workspace.

## Base URL

```
https://api.langdock.com/user-management/v1/update-user-role
```

<Warning>
  **Dedicated deployments**

  Replace `api.langdock.com` with `<your-deployment-url>/api/public` in all requests.
</Warning>

## Prerequisites

* **API Key** with the `USER_MANAGEMENT_API` scope
* The API key must be created by a workspace admin

## Behavior

* **Not an active human member?** Returns `404` (unknown email, invited, deactivated, service account, or another workspace).
* **Last remaining admin?** Returns `400` with `code: "BAD_REQUEST"`.
* Repeating the member's current role succeeds.
* Email matching is case-insensitive. Role values are lowercase: `member`, `editor`, `admin`. `ADMIN` returns `400`.

<Info>
  Langdock intentionally blocks browser-origin requests to protect your API key and ensure your applications remain secure. For more information, please see our guide on [API Key Best Practices](/en/admin/ai-adoption-and-rollout/best-practices/api-key-best-practices).
</Info>


## OpenAPI

````yaml POST /user-management/v1/update-user-role
openapi: 3.0.0
info:
  title: Langdock API
  version: 3.0.0
servers:
  - url: https://api.langdock.com
    description: Production
security:
  - bearerAuth: []
paths:
  /user-management/v1/update-user-role:
    post:
      tags:
        - User Management
      summary: Change a member's system role
      description: >
        Changes an active human member's workspace system role by email.

        Send `member`, `editor`, or `admin`. Custom roles are not part of this
        endpoint.

        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.
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateUserRoleRequest'
            examples:
              update_role:
                summary: Change a member to editor
                value:
                  email: user@example.com
                  role: editor
      responses:
        '200':
          description: Role updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateUserRoleResponse'
              examples:
                success:
                  summary: Role updated
                  value:
                    status: success
                    email: user@example.com
                    role: editor
        '400':
          description: >-
            Invalid role or request body, or the change would leave the
            workspace without an active admin
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserManagementError'
              examples:
                last_admin:
                  summary: Last remaining admin
                  value:
                    code: BAD_REQUEST
                    message: A workspace must retain at least one active admin.
                invalid_role:
                  summary: Invalid role value
                  value:
                    message: Invalid request
                    errors:
                      - code: invalid_value
                        values:
                          - member
                          - editor
                          - admin
                        path:
                          - role
                        message: >-
                          Invalid option: expected one of
                          "member"|"editor"|"admin"
        '401':
          description: API key is missing, invalid, or expired
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserManagementError'
        '403':
          description: API key is missing the USER_MANAGEMENT_API scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserManagementError'
              examples:
                insufficient_scopes:
                  summary: Missing scope
                  value:
                    message: Insufficient API key permissions.
                    error: INSUFFICIENT_SCOPES
                    details:
                      required:
                        - USER_MANAGEMENT_API
                      missing:
                        - USER_MANAGEMENT_API
        '404':
          description: User is not an active human member of this workspace
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserManagementError'
              examples:
                not_found:
                  summary: User not found
                  value:
                    code: NOT_FOUND
                    message: User is not an active member of this workspace
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserManagementError'
components:
  schemas:
    UpdateUserRoleRequest:
      type: object
      additionalProperties: false
      required:
        - email
        - role
      properties:
        email:
          type: string
          format: email
          description: Email address of the active workspace member
          example: user@example.com
        role:
          type: string
          enum:
            - member
            - editor
            - admin
          description: Workspace system role. Values are lowercase.
          example: editor
    UpdateUserRoleResponse:
      type: object
      properties:
        status:
          type: string
          enum:
            - success
          description: Always "success" when the role is updated
          example: success
        email:
          type: string
          format: email
          description: Email address of the updated member
          example: user@example.com
        role:
          type: string
          enum:
            - member
            - editor
            - admin
          description: System role after the update
          example: editor
      required:
        - status
        - email
        - role
    UserManagementError:
      type: object
      properties:
        message:
          type: string
          description: Error message
          example: User not found or not an active member
      required:
        - message
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: API key as Bearer token. Format "Bearer YOUR_API_KEY"

````