> ## 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.

# List Roles

> List the system roles and custom roles you can assign with the User Management API

This endpoint lists the system roles and custom roles you can assign with [Update User Role](https://docs.langdock.com/en/developer/user-management-api/update-user-role.md). Custom role names are not unique. Use `id` when you assign a role.

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/roles
```

> [!WARNING]
>
> **Dedicated deployments**
>
> Replace `api.langdock.com` with `<your-deployment-url>/api/public` in all requests.

## Prerequisites

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

## Behavior

* System roles come first, in this order: `member`, `editor`, `admin`. `kind` is `system`. `name` is Member, Editor, or Admin. `description` is empty. `id` is that lowercase role name.
* Custom roles follow, oldest first. `kind` is `custom`. Deleted custom roles are left out.
* Each role has `id`, `kind`, `name`, and `description`. Permission settings are not included.
* The call takes no query parameters.

> [!NOTE]
>
> 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](https://docs.langdock.com/en/admin/ai-adoption-and-rollout/best-practices/api-key-best-practices.md).


## OpenAPI

````yaml GET /user-management/v1/roles
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/roles:
    get:
      tags:
        - User Management
      summary: List assignable roles
      description: >
        Lists the workspace system roles and custom roles you can assign

        with Update User Role. System roles come first (`member`, `editor`,
        `admin`),

        then custom roles from oldest to newest. Each role includes `id`,
        `kind`,

        `name`, and `description`. Permission settings are not included.

        Custom role names are not unique, so use `id` when assigning a role.

        Requires an API key with the `USER_MANAGEMENT_API` scope.
      parameters: []
      responses:
        '200':
          description: Assignable roles
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListRolesResponse'
              examples:
                roles:
                  summary: System roles and one custom role
                  value:
                    roles:
                      - id: member
                        kind: system
                        name: Member
                        description: ''
                      - id: editor
                        kind: system
                        name: Editor
                        description: ''
                      - id: admin
                        kind: system
                        name: Admin
                        description: ''
                      - id: 33333333-3333-4333-8333-333333333333
                        kind: custom
                        name: Support lead
                        description: Can view analytics and governance
        '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
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserManagementError'
components:
  schemas:
    ListRolesResponse:
      type: object
      required:
        - roles
      properties:
        roles:
          type: array
          description: |
            System roles first (`member`, `editor`, `admin`), then live custom
            roles from oldest to newest. Deleted custom roles are omitted.
          items:
            type: object
            required:
              - id
              - kind
              - name
              - description
            properties:
              id:
                type: string
                description: >
                  System role name (`member`, `editor`, or `admin`) or the
                  custom

                  role UUID. Use this value in `customRoleIds`.
                example: 33333333-3333-4333-8333-333333333333
              kind:
                type: string
                enum:
                  - system
                  - custom
                description: Whether the role is a system role or a custom role
                example: custom
              name:
                type: string
                description: Display name. Custom role names are not unique.
                example: Support lead
              description:
                type: string
                description: Role description. Empty for system roles.
                example: Can view analytics and governance
    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"

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.