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

# List Users

> Retrieves all Users with pagination.



## OpenAPI

````yaml /es/openapi/v3-current/AM-identity.yaml get /v1/users
openapi: 3.0.1
info:
  contact: {}
  description: This is a swagger documentation for the Identity API
  termsOfService: http://swagger.io/terms/
  title: Identity API
  version: 1.0.0
servers:
  - url: //localhost:4001/
security: []
paths:
  /v1/users:
    get:
      tags:
        - Users
      summary: List Users
      description: Retrieves all Users with pagination.
      parameters:
        - description: Page number
          in: query
          name: page
          schema:
            default: 1
            type: integer
        - description: Items per page
          in: query
          name: limit
          schema:
            default: 10
            type: integer
        - description: Filter by name (case-insensitive substring)
          in: query
          name: name
          schema:
            type: string
        - description: Filter by role ID (relational listing)
          in: query
          name: roleId
          schema:
            type: string
        - description: Filter by group ID (relational listing)
          in: query
          name: groupId
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_200_4'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/pkg.HTTPError'
          description: Bad Request
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/pkg.HTTPError'
          description: Not Found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/pkg.HTTPError'
          description: Internal Server Error
      security:
        - BearerAuth: []
components:
  schemas:
    inline_response_200_4:
      example:
        Pagination:
          total: 10
          limit: 10
          page: 1
          items: '{}'
        items:
          - firstName: John
            lastName: Doe
            phone: 5511998888777
            countryCode: BR
            groups:
              - groups
              - groups
            mfa: '{}'
            id: 123e4567-e89b-12d3-a456-426614174000
            email: john@example.com
            username: johndoe
          - firstName: John
            lastName: Doe
            phone: 5511998888777
            countryCode: BR
            groups:
              - groups
              - groups
            mfa: '{}'
            id: 123e4567-e89b-12d3-a456-426614174000
            email: john@example.com
            username: johndoe
      properties:
        Pagination:
          $ref: '#/components/schemas/Pagination'
        items:
          items:
            $ref: '#/components/schemas/UserResponse'
          type: array
      type: object
    pkg.HTTPError:
      properties:
        code:
          type: string
        entityType:
          type: string
        err:
          type: object
        message:
          type: string
        title:
          type: string
      type: object
    Pagination:
      description: >-
        Pagination is the struct designed to store the pagination data of an
        entity list.
      example:
        total: 10
        limit: 10
        page: 1
        items: '{}'
      properties:
        items:
          type: object
        limit:
          example: 10
          type: integer
        page:
          example: 1
          type: integer
        total:
          example: 10
          type: integer
      type: object
    UserResponse:
      description: UserResponse payload
      example:
        firstName: John
        lastName: Doe
        phone: 5511998888777
        countryCode: BR
        groups:
          - groups
          - groups
        mfa: '{}'
        id: 123e4567-e89b-12d3-a456-426614174000
        email: john@example.com
        username: johndoe
      properties:
        countryCode:
          example: BR
          type: string
        email:
          example: john@example.com
          type: string
        firstName:
          example: John
          type: string
        groups:
          items:
            type: string
          type: array
        id:
          example: 123e4567-e89b-12d3-a456-426614174000
          type: string
        lastName:
          example: Doe
          type: string
        mfa:
          allOf:
            - $ref: '#/components/schemas/MFAStatusResponse'
          description: "The member's MFA status. NULLABLE, and the null is meaningful — this field\nis tri-state and a consumer MUST handle all three:\n\n\t{\"mfa\": {\"enabled\": false, \"methods\": [], ...}}  known: this member has no MFA\n\t{\"mfa\": {\"enabled\": true,  \"methods\": [\"app\"]}}  known: this member has MFA\n\t{\"mfa\": null}                                    UNKNOWN: not resolved\n\nnull is NOT \"no MFA\". It means the authoritative per-member read did not\ncomplete — Casdoor was unavailable, the row was skipped, or the listing's\nenrichment budget expired. Reporting those as enabled=false would tell an\nadministrator that a possibly-protected member is unprotected, so they are\nreported honestly as unknown instead. Render null as \"unknown\", never as\n\"off\", and never dereference without a null check: `user.mfa.enabled` throws\nexactly when Casdoor is degraded, which is the worst moment to throw.\n\nSingle-user reads (GET /v1/users/{id}) always populate it — the read that\nwould have failed is the request itself. Only the member LISTING can return\nnull; see enrichUsersWithMFAStatus in internal/services/user_mfa_enrichment.go.\n\nCarries no secrets — only enablement flags, methods and the preferred type."
          nullable: true
          type: object
        phone:
          example: 5511998888777
          type: string
        username:
          example: johndoe
          type: string
      type: object
    MFAStatusResponse:
      description: MFAStatusResponse payload
      example:
        preferredType: app
        methods:
          - app
          - email
        emailEnabled: false
        totpEnabled: true
        enabled: true
      properties:
        emailEnabled:
          description: Whether email MFA is enabled
          example: false
          type: boolean
        enabled:
          description: Whether MFA is enabled for the user
          example: true
          type: boolean
        methods:
          description: List of configured MFA methods
          example:
            - app
            - email
          items:
            type: string
          type: array
        preferredType:
          description: Preferred MFA type (if enabled)
          example: app
          type: string
        totpEnabled:
          description: Whether TOTP (app) is enabled
          example: true
          type: boolean
      type: object
  securitySchemes:
    BearerAuth:
      description: 'Bearer authentication. Send Authorization: Bearer <token>.'
      in: header
      name: Authorization
      type: apiKey

````