User Search

Auth0 allows you, as an administrator, to search for users using Lucene Query Syntax.

This document will demonstrate how you can search for users and give some example queries. It is however suggested that you also reference the Query String Syntax document for more examples of the query string syntax.

Searchable Fields

You can search for users using the following fields:

  • All the normalized user profile fields

  • Only the profile information under the user_metadata object:

    • name
    • nickname
    • given_name
    • family_name

New tenants, starting September 1st 2017, cannot search any of the app_metadata fields. Paid tenants (i.e. tenants that have a credit card associated in the Dashboard), that were created up to August 31st 2017, can search using the app_metadata fields.

For more information on user related metadata refer to User Metadata.

Search for Users Using the Management API

You can also search for users using the Management API. Two of the easiest ways to do this is by either making use of the API Explorer or by using Postman. These two techniques are discussed briefly below, but please note that the Auth0 Management API is a REST API, so you can make API calls using anything that can make HTTP requests, or by using one of the Auth0 SDKs.

In order to make requests to the Management API, you will need a token. Please refer to The Auth0 Management APIv2 Token for more information.

Search using the API Explorer

To search users using the Management API Explorer, go to the Users section and then select List or search users. Scroll down to the q parameter. You can use any query string which uses the query string syntax in this field.

Searching users in API Explorer

Search using Postman

You can also search users using the Postman Collection for the Management API. Make sure you read Using the Auth0 API with our Postman Collections for more information on how to install the collection and also configure your Postman environment correctly.

Once you have downloaded the collection, and configured your environment, select the Management API collection. Navigate to the Users folder and select List or search users. You can enter your query in the q parameter of the URL:

Searching users in Postman

For general information on making Postman request, please refer to the Postman documentation.

Sorting Search Results

To sort the list of users returned from the Management API, you can make use of the sort parameter. Use the format field:order for the value of the sort field, where field is the name of the field you want to sort by, and order can be 1 for ascending and -1 for descending. For example, to sort users in ascending order by the created_at field you can pass the value of created_at:1 for the sort parameter.

For more information on the sort and other parameters, please refer to the Management API Explorer documentation.

If there is no default sort field specified, some users that have never logged in, may not appear. No default sort field may also result in duplicate records returned and the order of list of users may appear random.

Exact Matching and Tokenization

Because of the manner in which ElasticSearch handles tokenization on + and -, unexpected results can occur when searching by some fields. For example, when searching for a user whose name is jane (name:"jane"), the results will be both for jane and jane-doe, because both of these contain the exact search term that you used. The difference may not affect some searches, but it will affect others, and provide unanticipated results.

You can solve this problem either by using structured JSON in your metadata, or by using the raw subfield.

Using the raw Subfield

If you wish to avoid the potential pitfalls of analyzed data and search for an exact match to your term - an exact string comparison - then for some fields you can use the raw subfield, which will be not_analyzed.

So, in the example name.raw:"jane", the user data for jane would match, but jane-doe would not.

The fields that support raw subfield queries are:

  • identities.connection⁠⁠⁠⁠
  • ⁠⁠⁠⁠identities.provider⁠⁠⁠⁠
  • ⁠⁠⁠⁠identities.user_id⁠⁠⁠⁠
  • ⁠⁠⁠⁠email⁠
  • ⁠⁠⁠⁠phone_number⁠⁠
  • ⁠⁠⁠⁠family_name⁠⁠⁠⁠
  • ⁠⁠⁠⁠given_name⁠⁠⁠⁠
  • ⁠⁠⁠⁠username⁠⁠⁠⁠
  • ⁠⁠⁠⁠name⁠⁠
  • ⁠⁠⁠⁠nickname

Example Queries

Below are some example queries to illustrate the kinds of queries that are possible using the Management API V2.

Use Case Query
Search across all fields for "john" john
Search for all users whose name contains "john" name:"john"
Search all users whose name is exactly "john" name.raw:"john"
Search for all user names starting with "john" name:john*
Search for user names that start with "john" and end with "smith" name:john*smith
Search for all users whose email is exactly "john@contoso.com" email.raw:"john@contoso.com"
Search for all users whose email is exactly "john@contoso.com" or "mary@contoso.com" using OR email.raw:("john@contoso.com" OR "mary@contoso.com")
Search for users without verified email email_verified:false OR _missing_:email_verified
Search for users who have the user_metadata field named name with the value of "John Doe" user_metadata.name:"John Doe"
Search for users from a specific connection or provider identities.provider:"google-oauth2"
Search for all users that have never logged in (_missing_:logins_count OR logins_count:0)
Search for all users who logged in before 2015 last_login:[* TO 2014-12-31]
Fuzziness: Search for terms that are similar to, but not exactly like, jhn name:jhn~

Example Request

Below is an example request for searching all users whose email is exactly "john@contoso.com".


curl --request GET \
  --url 'https://YOUR_AUTH0_DOMAIN/api/v2/users?q=email.raw%3A%22john%40contoso.com%22&search_engine=v2' \
  --header 'authorization: Bearer ACCESS_TOKEN'
var client = new RestClient("https://YOUR_AUTH0_DOMAIN/api/v2/users?q=email.raw%3A%22john%40contoso.com%22&search_engine=v2");
var request = new RestRequest(Method.GET);
request.AddHeader("authorization", "Bearer ACCESS_TOKEN");
IRestResponse response = client.Execute(request);
package main

import (
	"fmt"
	"net/http"
	"io/ioutil"
)

func main() {

	url := "https://YOUR_AUTH0_DOMAIN/api/v2/users?q=email.raw%3A%22john%40contoso.com%22&search_engine=v2"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("authorization", "Bearer ACCESS_TOKEN")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := ioutil.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.get("https://YOUR_AUTH0_DOMAIN/api/v2/users?q=email.raw%3A%22john%40contoso.com%22&search_engine=v2")
  .header("authorization", "Bearer ACCESS_TOKEN")
  .asString();
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://YOUR_AUTH0_DOMAIN/api/v2/users?q=email.raw%3A%22john%40contoso.com%22&search_engine=v2",
  "method": "GET",
  "headers": {
    "authorization": "Bearer ACCESS_TOKEN"
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});
var request = require("request");

var options = { method: 'GET',
  url: 'https://YOUR_AUTH0_DOMAIN/api/v2/users',
  qs: { q: 'email.raw:"john@contoso.com"', search_engine: 'v2' },
  headers: { authorization: 'Bearer ACCESS_TOKEN' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
#import <Foundation/Foundation.h>

NSDictionary *headers = @{ @"authorization": @"Bearer ACCESS_TOKEN" };

NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://YOUR_AUTH0_DOMAIN/api/v2/users?q=email.raw%3A%22john%40contoso.com%22&search_engine=v2"]
                                                       cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                   timeoutInterval:10.0];
[request setHTTPMethod:@"GET"];
[request setAllHTTPHeaderFields:headers];

NSURLSession *session = [NSURLSession sharedSession];
NSURLSessionDataTask *dataTask = [session dataTaskWithRequest:request
                                            completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) {
                                                if (error) {
                                                    NSLog(@"%@", error);
                                                } else {
                                                    NSHTTPURLResponse *httpResponse = (NSHTTPURLResponse *) response;
                                                    NSLog(@"%@", httpResponse);
                                                }
                                            }];
[dataTask resume];
$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://YOUR_AUTH0_DOMAIN/api/v2/users?q=email.raw%3A%22john%40contoso.com%22&search_engine=v2",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "authorization: Bearer ACCESS_TOKEN"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
import http.client

conn = http.client.HTTPSConnection("")

headers = { 'authorization': "Bearer ACCESS_TOKEN" }

conn.request("GET", "/YOUR_AUTH0_DOMAIN/api/v2/users?q=email.raw%3A%22john%40contoso.com%22&search_engine=v2", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))
require 'uri'
require 'net/http'

url = URI("https://YOUR_AUTH0_DOMAIN/api/v2/users?q=email.raw%3A%22john%40contoso.com%22&search_engine=v2")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new(url)
request["authorization"] = 'Bearer ACCESS_TOKEN'

response = http.request(request)
puts response.read_body
import Foundation

let headers = ["authorization": "Bearer ACCESS_TOKEN"]

var request = NSMutableURLRequest(URL: NSURL(string: "https://YOUR_AUTH0_DOMAIN/api/v2/users?q=email.raw%3A%22john%40contoso.com%22&search_engine=v2")!,
                                        cachePolicy: .UseProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.HTTPMethod = "GET"
request.allHTTPHeaderFields = headers

let session = NSURLSession.sharedSession()
let dataTask = session.dataTaskWithRequest(request, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    println(error)
  } else {
    let httpResponse = response as? NSHTTPURLResponse
    println(httpResponse)
  }
})

dataTask.resume()

Search using ranges

Inclusive ranges are specified with square brackets: [min TO max] and exclusive ranges with curly brackets: {min TO max}. Curly and square brackets can be combined in the same range expression: logins_count:[100 TO 200}.

Use Case Query
All users with more than 100 logins logins_count:>100
Logins count >= 100 and <= 200 logins_count:[100 TO 200]
Logins count >= 100 logins_count:[100 TO *]
Logins count > 100 and < 200 logins_count:{100 TO 200}