List or Search Users

Retrieve details of users. It is possible to:

• Specify a search criteria for users
• Sort the users to be returned
• Select the fields to be returned
• Specify the number of users to retrieve per page and the page index

The q query parameter can be used to get users that match the specified criteria using query string syntax.

Learn more about searching for users.

Read about best practices when working with the API endpoints for retrieving users.

Auth0 limits the number of users you can return. If you exceed this threshold, please redefine your search, use the export job, or the User Import / Export extension.

GET https://{tenantDomain}/api/v2/users

C#

C#

using Auth0.ManagementApi;
using System.Threading.Tasks;

public partial class Examples
{
    public async Task Example() {
        var client = new ManagementClient(
            token: "<token>"
        );

        await client.Users.ListAsync(
            new ListUsersRequestParameters {
                Page = 1,
                PerPage = 1,
                IncludeTotals = true,
                Sort = "sort",
                Connection = "connection",
                Fields = "fields",
                IncludeFields = true,
                Q = "q",
                SearchEngine = SearchEngineVersionsEnum.V1,
                PrimaryOrder = true
            }
        );
    }

}

package example

import (
    context "context"

    management "github.com/auth0/go-auth0/management/management"
    client "github.com/auth0/go-auth0/management/management/client"
    option "github.com/auth0/go-auth0/management/management/option"
)

func do() {
    client := client.NewClient(
        option.WithToken(
            "<token>",
        ),
    )
    request := &management.ListUsersRequestParameters{
        Page: management.Int(
            1,
        ),
        PerPage: management.Int(
            1,
        ),
        IncludeTotals: management.Bool(
            true,
        ),
        Sort: management.String(
            "sort",
        ),
        Connection: management.String(
            "connection",
        ),
        Fields: management.String(
            "fields",
        ),
        IncludeFields: management.Bool(
            true,
        ),
        Q: management.String(
            "q",
        ),
        SearchEngine: management.SearchEngineVersionsEnumV1.Ptr(),
        PrimaryOrder: management.Bool(
            true,
        ),
    }
    client.Users.List(
        context.TODO(),
        request,
    )
}

package com.example.usage;

import com.auth0.client.mgmt.ManagementApi;
import com.auth0.client.mgmt.resources.users.requests.ListUsersRequestParameters;
import com.auth0.client.mgmt.types.SearchEngineVersionsEnum;

public class Example {
    public static void main(String[] args) {
        ManagementApi client = ManagementApi
            .builder()
            .token("<token>")
            .build();

        client.users().list(
            ListUsersRequestParameters
                .builder()
                .page(1)
                .perPage(1)
                .includeTotals(true)
                .sort("sort")
                .connection("connection")
                .fields("fields")
                .includeFields(true)
                .q("q")
                .searchEngine(SearchEngineVersionsEnum.V_1)
                .primaryOrder(true)
                .build()
        );
    }
}

<?php

namespace Example;

use Auth0\SDK\API\Management\Management;
use Auth0\SDK\API\Management\Users\Requests\ListUsersRequestParameters;
use Auth0\SDK\API\Management\Types\SearchEngineVersionsEnum;

$client = new Management(
    token: '<token>',
);
$client->users->list(
    new ListUsersRequestParameters([
        'page' => 1,
        'perPage' => 1,
        'includeTotals' => true,
        'sort' => 'sort',
        'connection' => 'connection',
        'fields' => 'fields',
        'includeFields' => true,
        'q' => 'q',
        'searchEngine' => SearchEngineVersionsEnum::V1->value,
        'primaryOrder' => true,
    ]),
);

from auth0.management import ManagementClient

client = ManagementClient(
    token="<token>",
)

client.users.list(
    page=1,
    per_page=1,
    include_totals=True,
    sort="sort",
    connection="connection",
    fields="fields",
    include_fields=True,
    q="q",
    search_engine="v1",
    primary_order=True,
)

require "auth0"

client = Auth0::Management.new(token: "<token>")

client.users.list(
  page: 1,
  per_page: 1,
  include_totals: true,
  sort: "sort",
  connection: "connection",
  fields: "fields",
  include_fields: true,
  q: "q",
  search_engine: "v1",
  primary_order: true
)

import { ManagementClient } from "auth0";

async function main() {
    const client = new ManagementClient({
        token: "<token>",
    });
    await client.users.list({
        page: 1,
        perPage: 1,
        includeTotals: true,
        sort: "sort",
        connection: "connection",
        fields: "fields",
        includeFields: true,
        q: "q",
        searchEngine: "v1",
        primaryOrder: true,
    });
}
main();

import { ManagementClient } from "auth0";

async function main() {
    const client = new ManagementClient({
        token: "<token>",
    });
    await client.users.list({
        page: 1,
        perPage: 1,
        includeTotals: true,
        sort: "sort",
        connection: "connection",
        fields: "fields",
        includeFields: true,
        q: "q",
        searchEngine: "v1",
        primaryOrder: true,
    });
}
main();

curl --request GET \
  --url https://{tenantDomain}/api/v2/users \
  --header 'Authorization: Bearer <token>'

200

[
  {
    "user_id": "auth0|507f1f77bcf86cd799439020",
    "email": "[e-mail]",
    "email_verified": false,
    "username": "johndoe",
    "phone_number": "[phone]",
    "phone_verified": false,
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z",
    "identities": [
      {
        "connection": "<string>",
        "user_id": "abc",
        "isSocial": true,
        "access_token": "<string>",
        "access_token_secret": "<string>",
        "refresh_token": "<string>",
        "profileData": {
          "email": "<string>",
          "email_verified": true,
          "name": "<string>",
          "username": "johndoe",
          "given_name": "<string>",
          "phone_number": "<string>",
          "phone_verified": true,
          "family_name": "<string>"
        }
      }
    ],
    "app_metadata": {},
    "user_metadata": {},
    "picture": "<string>",
    "name": "<string>",
    "nickname": "<string>",
    "multifactor": [
      "<string>"
    ],
    "multifactor_last_modified": "2023-11-07T05:31:56Z",
    "last_ip": "<string>",
    "last_login": "2023-11-07T05:31:56Z",
    "last_password_reset": "2023-11-07T05:31:56Z",
    "logins_count": 123,
    "blocked": true,
    "given_name": "<string>",
    "family_name": "<string>"
  }
]

Authorizations

bearerAuthoAuth2ClientCredentials

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

page · integer

Page index of the results to return. First page is 0.

Required range: x >= 0

per_page · integer

Number of results per page.

Required range: 0 <= x <= 100

include_totals · boolean

Return results inside an object that contains the total result count (true) or as a direct array of results (false, default).

sort · string

Field to sort by. Use field:order where order is 1 for ascending and -1 for descending. e.g. created_at:1

connection · string

Connection filter. Only applies when using search_engine=v1. To filter by connection with search_engine=v2|v3, use q=identities.connection:"connection_name"

fields · string

Comma-separated list of fields to include or exclude (based on value provided for include_fields) in the result. Leave empty to retrieve all fields.

include_fields · boolean

Whether specified fields are to be included (true) or excluded (false).

q · string

Query in Lucene query string syntax. Some query types cannot be used on metadata fields, for details see Searchable Fields.

search_engine · enum<string>

The version of the search engine

Available options: v1, v2, v3

primary_order · boolean

If true (default), results are returned in a deterministic order. If false, results may be returned in a non-deterministic order, which can enhance performance for complex queries targeting a small number of users. Set to false only when consistent ordering and pagination is not required.

Response

200

application/json

Users successfully retrieved.

object[]

object

user_id · string · default: auth0|507f1f77bcf86cd799439020

ID of the user which can be used when interacting with other APIs.

email · string<email> · default: [e-mail]

Email address of this user.

email_verified · boolean · default: false

Whether this email address is verified (true) or unverified (false).

username · string · default: johndoe

Username of this user.

phone_number · string · default: [phone]

Phone number for this user. Follows the E.164 recommendation.

phone_verified · boolean · default: false

Whether this phone number has been verified (true) or not (false).

created_at · string<date-time>

Date and time when this user was created.

updated_at · string<date-time>

Date and time when this user was last updated/modified.

identities · object[]

Array of user identity objects when accounts are linked.

Show child attributes

app_metadata · object

User metadata to which this user has read-only access.

user_metadata · object

User metadata to which this user has read/write access.

picture · string

URL to picture, photo, or avatar of this user.

name · string

Name of this user.

nickname · string

Preferred nickname or alias of this user.

multifactor · string[]

List of multi-factor authentication providers with which this user has enrolled.

multifactor_last_modified · string<date-time>

Last date and time this user's multi-factor authentication providers were updated.

last_ip · string

Last IP address from which this user logged in.

last_login · string<date-time>

Last date and time this user logged in.

last_password_reset · string<date-time>

Last date and time this user had their password reset.

logins_count · integer

Total number of logins this user has performed.

blocked · boolean

Whether this user was blocked by an administrator (true) or is not (false).

given_name · string

Given name/first name/forename of this user.

family_name · string

Family name/last name/surname of this user.