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

# List users

> Returns a list of project users.

The list supports pagination and sorting:
- The `sort` parameter only supports the `created` field (use `created` for ascending, `-created` for descending).
- Users can be filtered by:
  - Single user ID using `userID`
  - Multiple user IDs using `userIDs` (max 1000)
  - Multiple WebAuthn IDs using `webauthnIDs` (max 1000)
  - Single identifier using `identifierValue` and `identifierType` together
  - Multiple identifiers using `identifierValues` and `identifierType` together (max 1000)

Filtering rules:
- Only one filter type can be used at a time: `userID`, `userIDs`, `webauthnIDs`, or identifier filters
- `userID` and `userIDs` are mutually exclusive
- `identifierValue` and `identifierValues` are mutually exclusive
- When filtering by identifier(s), `identifierType` must be provided




## OpenAPI

````yaml https://backendapi.cloud.corbado.io/v2/openapi.yaml get /users
openapi: 3.0.3
info:
  version: 2.0.0
  title: Corbado Backend API
  description: >
    # Introduction

    This documentation gives an overview of all Corbado Backend API calls to
    implement passwordless authentication with Passkeys.
  contact:
    name: Corbado team
    email: support@corbado.com
    url: https://www.corbado.com
servers:
  - url: https://backendapi.corbado.io/v2
security:
  - basicAuth: []
tags:
  - name: Users
    description: All API calls to manage users
  - name: Sessions
    description: All API calls to manage sessions
  - name: Challenges
    description: All API calls to manage challenges
  - name: Identifiers
    description: All API calls to manage login identifiers
  - name: Passkeys
    description: All API calls for passkey flows
  - name: SSO
    description: All API calls for SSO flows
  - name: AuthEvents
    description: All API calls to manage authentication events
  - name: PasskeyEvents
    description: All API calls to manage passkey events
  - name: ProjectConfig
    description: All API calls to manage project configurations
  - name: ConnectTokens
    description: All API calls to manage connectTokens
  - name: PasskeyChallenges
    description: All API calls to manage passkey challenges
  - name: WebhookEndpoints
    description: All API calls to manage webhook endpoints
  - name: PasswordManagers
    description: All API calls to manage password managers
  - name: ClientEnvs
    description: All API calls to manage client environments
  - name: Devices
    description: All API calls to manage devices
  - name: Exports
    description: All API calls to manage project export files
paths:
  /users:
    get:
      tags:
        - Users
      summary: List users
      description: >
        Returns a list of project users.


        The list supports pagination and sorting:

        - The `sort` parameter only supports the `created` field (use `created`
        for ascending, `-created` for descending).

        - Users can be filtered by:
          - Single user ID using `userID`
          - Multiple user IDs using `userIDs` (max 1000)
          - Multiple WebAuthn IDs using `webauthnIDs` (max 1000)
          - Single identifier using `identifierValue` and `identifierType` together
          - Multiple identifiers using `identifierValues` and `identifierType` together (max 1000)

        Filtering rules:

        - Only one filter type can be used at a time: `userID`, `userIDs`,
        `webauthnIDs`, or identifier filters

        - `userID` and `userIDs` are mutually exclusive

        - `identifierValue` and `identifierValues` are mutually exclusive

        - When filtering by identifier(s), `identifierType` must be provided
      operationId: UserList
      parameters:
        - name: userID
          in: query
          description: >-
            Filter by specific user ID (format `usr-<number>`). Cannot be used
            together with `userIDs`.
          required: false
          schema:
            type: string
            example: usr-4693224802260150919
        - name: userIDs
          in: query
          description: >-
            Filter by multiple user IDs (comma-separated). Cannot be used
            together with `userID`, `webauthnIDs`, or identifier filters.
            Maximum 1000 IDs.
          required: false
          schema:
            type: array
            items:
              type: string
            example:
              - usr-4693224802260150919
              - usr-1234567890123456789
          style: form
          explode: false
        - name: userIDPattern
          in: query
          description: >-
            Filter by user IDs matching the given pattern. Supports `%` as a
            wildcard character. Cannot be used together with other filter types.
          required: false
          schema:
            type: string
            example: usr-%
        - name: webauthnIDs
          in: query
          description: >-
            Filter by multiple WebAuthn IDs (comma-separated). Cannot be used
            together with other filter types. Maximum 1000 IDs.
          required: false
          schema:
            type: array
            items:
              type: string
            example:
              - abc123def456
              - xyz789ghi012
          style: form
          explode: false
        - name: identifierValue
          in: query
          description: >-
            Filter by identifier value (email, phone, or username). Must be used
            together with `identifierType`. Cannot be used together with
            `identifierValues`.
          required: false
          schema:
            type: string
            example: jane@doe.com
        - name: identifierValues
          in: query
          description: >-
            Filter by multiple identifier values (comma-separated). Must be used
            together with `identifierType`. Cannot be used together with
            `identifierValue`. Maximum 1000 values.
          required: false
          schema:
            type: array
            items:
              type: string
            example:
              - jane@doe.com
              - john@example.com
          style: form
          explode: false
        - name: identifierType
          in: query
          description: >-
            Type of identifier to filter by. Must be used together with
            `identifierValue` or `identifierValues`.
          required: false
          schema:
            type: string
            enum:
              - email
              - phone
              - username
            example: email
        - name: status
          in: query
          description: Filter by user status.
          required: false
          schema:
            type: string
            enum:
              - active
              - pending
              - disabled
              - deleted
            example: active
        - name: sort
          in: query
          description: |
            Sort field. Only `created` is supported.
            - Use `+created` for ascending order
            - Use `-created` for descending order
          required: false
          schema:
            type: string
            enum:
              - +created
              - '-created'
            example: '-created'
        - name: includeIdentifiers
          in: query
          description: >-
            Whether to include login identifiers in the response. Defaults to
            `true`.
          required: false
          schema:
            type: boolean
            default: true
        - name: page
          in: query
          description: |
            The page number to retrieve for paginated results.
          required: false
          schema:
            type: integer
            default: 1
            example: 1
        - name: pageSize
          in: query
          description: |
            The number of items to return per page. Useful for pagination.
          required: false
          schema:
            type: integer
            default: 10
            example: 20
      responses:
        '200':
          description: List of users.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/userList'
        default:
          $ref: '#/components/responses/error'
      security:
        - basicAuth: []
components:
  schemas:
    userList:
      type: object
      required:
        - users
        - paging
      properties:
        users:
          type: array
          items:
            $ref: '#/components/schemas/userAggregate'
        paging:
          type: object
          required:
            - page
            - totalPages
            - totalItems
          properties:
            page:
              description: current page returned in response
              type: integer
              default: 1
            totalPages:
              description: total number of pages available
              type: integer
            totalItems:
              description: total number of items available
              type: integer
    userAggregate:
      type: object
      required:
        - userID
        - status
        - emailIdentifiers
        - phoneNumberIdentifiers
        - usernameIdentifiers
        - socialAccounts
        - created
        - createdMS
        - updated
        - updatedMs
      properties:
        userID:
          type: string
          example: usr-4693224802260150919
        fullName:
          type: string
          example: Jane Doe
        status:
          $ref: '#/components/schemas/userStatus'
        explicitWebauthnID:
          type: string
        emailIdentifiers:
          type: array
          items:
            $ref: '#/components/schemas/identifier'
        phoneNumberIdentifiers:
          type: array
          items:
            $ref: '#/components/schemas/identifier'
        usernameIdentifiers:
          type: array
          items:
            $ref: '#/components/schemas/identifier'
        socialAccounts:
          type: array
          items:
            $ref: '#/components/schemas/socialAccount'
        created:
          type: string
        createdMS:
          type: integer
          format: int64
        updated:
          type: string
        updatedMs:
          type: integer
          format: int64
    userStatus:
      type: string
      enum:
        - pending
        - active
        - disabled
    identifier:
      type: object
      required:
        - identifierID
        - type
        - value
        - status
        - userID
      properties:
        identifierID:
          type: string
          description: Unique identifier of the login identifier.
          example: ide-4693224802260150919
        type:
          $ref: '#/components/schemas/identifierType'
        value:
          type: string
          description: Value of the identifier (here email address).
          example: jane@doe.com
        status:
          $ref: '#/components/schemas/identifierStatus'
        userID:
          type: string
          description: Unique identifier of the user.
          example: usr-4693224802260150919
    socialAccount:
      type: object
      required:
        - socialAccountID
        - providerType
        - identifierValue
        - userID
        - foreignID
        - avatarURL
        - fullName
      properties:
        socialAccountID:
          type: string
          description: Unique identifier of the social account.
          example: soc-6060375336139150919
        providerType:
          type: string
          description: Type of the social provider.
          example: github
        identifierValue:
          type: string
          description: Login identifier of the user (here email address).
          example: jane@doe.com
        userID:
          type: string
          description: Unique identifier of the user.
          example: usr-4693224802260150919
        foreignID:
          type: string
          description: Unique identifier of the user in the social provider.
          example: '53150919'
        avatarURL:
          type: string
          description: URL of the avatar of the user in the social provider.
          example: https://avatars.githubusercontent.com/u/53150919?v=4
        fullName:
          type: string
          description: Full name of the user in the social provider.
          example: Jane Doe
    identifierType:
      type: string
      enum:
        - email
        - phone
        - username
    identifierStatus:
      type: string
      enum:
        - pending
        - primary
        - verified
  responses:
    error:
      description: Error
      content:
        application/json:
          schema:
            allOf:
              - type: object
                required:
                  - httpStatusCode
                  - message
                  - requestData
                  - runtime
                properties:
                  httpStatusCode:
                    description: HTTP status code of operation
                    type: integer
                    format: int32
                  message:
                    type: string
                    example: OK
                  requestData:
                    description: Data about the request itself, can be used for debugging
                    type: object
                    required:
                      - requestID
                    properties:
                      requestID:
                        description: >-
                          Unique ID of request, you can provide your own while
                          making the request, if not the ID will be randomly
                          generated on server side
                        type: string
                        example: req-557...663
                      link:
                        description: Link to dashboard with details about request
                        type: string
                        example: >-
                          https://my.corbado.com/requests/req-xxxxxxxxxxxxxxxxxxx
                  runtime:
                    description: Runtime in seconds for this request
                    type: number
                    format: float
                    example: 0.06167686
              - type: object
                required:
                  - error
                properties:
                  data:
                    type: object
                  error:
                    type: object
                    required:
                      - type
                    properties:
                      type:
                        description: Type of error
                        type: string
                      details:
                        description: Details of error
                        type: string
                      validation:
                        description: Validation errors per field
                        type: array
                        items:
                          type: object
                          required:
                            - field
                            - message
                          properties:
                            field:
                              type: string
                            message:
                              type: string
                      links:
                        description: Additional links to help understand the error
                        type: array
                        items:
                          type: string
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: >
        Basic authentication is used to authenticate requests to the Backend
        API. The username is the project ID and the password is the API secret.


        The project ID and API secret can be found in the [Developer
        Panel](https://app.corbado.com/settings/api-secrets).

````