List users

GET /users
Bearer auth

Get paginated list of users with hierarchical authorization

Query parameters

  • page integer

    Page number

    Minimum value is 1. Default value is 1.

  • page_size integer

    Items per page

    Minimum value is 1, maximum value is 100. Default value is 20.

  • sort_by string

    Field to sort users by

    Values are name, email, username, created_at, updated_at, latest_login_at, or organization.

  • sort_direction string

    Sort direction

    Values are asc or desc. Default value is asc.

Responses

  • 200 application/json

    Users retrieved successfully

    Hide response attributes Show response attributes object
    • code integer
    • message string
    • data object
      Hide data attributes Show data attributes object
      • users array[object]
        Hide users attributes Show users attributes object
        • id string

          User account ID

        • logto_id string | null

          Logto user ID

        • username string

          Username

        • email string(email)

          Email address

        • name string

          Full name

        • phone string | null

          Phone number

        • organization object | null

          Organization information

          Hide organization attributes Show organization attributes object | null
          • id string

            Local database organization ID

          • logto_id string

            Logto organization ID

          • name string

            Organization name

        • roles array[object]

          User roles with names

          Hide roles attributes Show roles attributes object
          • id string

            Role ID

          • name string

            Role name

        • custom_data object

          Custom user data

          Additional properties are allowed.

        • created_at string(date-time)

          Account creation timestamp

        • updated_at string(date-time)

          Last update timestamp

        • logto_synced_at string(date-time) | null

          Last Logto synchronization timestamp

        • latest_login_at string(date-time) | null

          Timestamp of the last successful login via /auth/exchange endpoint. NULL means user has never logged in.

        • deleted_at string(date-time) | null

          Soft delete timestamp (null if not deleted)

        • suspended_at string(date-time) | null

          Suspension timestamp (null if not suspended)

      • pagination object
        Hide pagination attributes Show pagination attributes object
        • page integer

          Current page number

          Minimum value is 1.

        • page_size integer

          Number of items per page

          Minimum value is 1, maximum value is 100.

        • total_count integer

          Total number of items

          Minimum value is 0.

        • total_pages integer

          Total number of pages

          Minimum value is 0.

        • has_next boolean

          Whether there is a next page

        • has_prev boolean

          Whether there is a previous page

        • next_page integer | null

          Next page number if available

        • prev_page integer | null

          Previous page number if available

        • sort_by string | null

          Field used for sorting

        • sort_direction string | null

          Sort direction

          Values are asc or desc.
  • 401 application/json

    Unauthorized - invalid or missing token

    Hide response attributes Show response attributes object
    • code integer
    • message string
    • data object | null
  • 403 application/json

    Forbidden - insufficient permissions

    Hide response attributes Show response attributes object
    • code integer
    • message string
    • data object | null
GET /users 
curl \
 --request GET 'https://api.your-domain.com/api/users' \
 --header "Authorization: Bearer $ACCESS_TOKEN"
Response examples (200) 
{
  "code": 200,
  "message": "users retrieved successfully",
  "data": {
    "users": [
      {
        "id": "usr_123456789",
        "logto_id": "user_abc123def456",
        "username": "john.doe",
        "email": "john@example.com",
        "name": "John Doe",
        "phone": "+39 333 123456",
        "organization": {
          "id": "12345678-1234-1234-1234-123456789abc",
          "logto_id": "org_123456789",
          "name": "ACME Corp"
        },
        "roles": [
          {
            "id": "rol_admin_123",
            "name": "Admin"
          }
        ],
        "custom_data": {
          "position": "Senior Developer",
          "department": "IT"
        },
        "created_at": "2025-06-20T14:30:00Z",
        "updated_at": "2025-06-21T10:45:00Z",
        "logto_synced_at": "2025-06-21T10:45:00Z",
        "latest_login_at": "2025-06-21T15:30:45Z",
        "deleted_at": "2025-05-04T09:42:00Z",
        "suspended_at": "2025-05-04T09:42:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "page_size": 20,
      "total_count": 156,
      "total_pages": 8,
      "has_next": true,
      "has_prev": false,
      "next_page": 2,
      "prev_page": 42,
      "sort_by": "name",
      "sort_direction": "asc"
    }
  }
}
Response examples (401) 
{
  "code": 401,
  "message": "invalid token",
  "data": {}
}
Response examples (403) 
{
  "code": 403,
  "message": "insufficient permissions",
  "data": {}
}