Get/search user list

This document is automatically generated based on https://github.com/authing/authing-docs-factory based on https://api-explorer.genauth.ai V3 API, and is consistent with API parameters and return results. If this document description is incorrect, please refer to V3 API.

This interface is used to obtain user lists, supports fuzzy search, and filters users by user basic fields, user custom fields, user department, user history login application and other dimensions.

Fuzzy search example

Fuzzy search will perform fuzzy search on users from five fields by default: phone, email, name, username, nickname. You can also set options.fuzzySearchOn to determine the field range of fuzzy matching:

{
  "keywords": "xxx",
  "options": {
    "fuzzySearchOn": ["address"]
  }
}

Advanced search example

You can use advancedFilter to perform advanced search. Advanced search supports filtering users by basic information, custom data, department, user source, login application, external identity source information, etc. **These filtering conditions can be combined arbitrarily. **

Filter users with disabled status

User status (status) is a string type, and the optional values are Activated and Suspended:

{
  "advancedFilter": [
    {
      "field": "status",
      "operator": "EQUAL",
      "value": "Suspended"
    }
  ]
}

Filter users whose mailboxes contain @example.com

User mailboxes (email) are string types and can be fuzzy searched:

{
  "advancedFilter": [
    {
      "field": "email",
      "operator": "CONTAINS",
      "value": "@example.com"
    }
  ]
}

Search based on any extended fields of the user

{
  "advancedFilter": [
    {
      "field": "some-custom-key",
      "operator": "EQUAL",
      "value": "some-value"
    }
  ]
}

Filter by number of user logins

Filter users with more than 10 logins:

{
  "advancedFilter": [
    {
      "field": "loginsCount",
      "operator": "GREATER",
      "value": 10
    }
  ]
}

Filter users with 10 to 100 login times:

{
  "advancedFilter": [
    {
      "field": "loginsCount",
      "operator": "BETWEEN",
      "value": [10, 100]
    }
  ]
}

Filter based on the user's last login time

Filter users who have logged in within the last 7 days:

{
"advancedFilter": [
{
"field": "lastLoginTime",
"operator": "GREATER",
"value": new Date(Date.now() - 7 * 24 * 60 * 60 * 1000)
}
]
}

Filter users who have logged in within a certain period of time:

{
"advancedFilter": [
{
"field": "lastLogin",
"operator": "BETWEEN",
"value": [
Date.now() - 14 * 24 * 60 * 60 * 1000,
Date.now() - 7 * 24 * 60 * 60 * 1000
]
}
]
}

Filter based on the applications that the user has logged in

Filter users who have logged in to applications appId1 or appId2:

{
  "advancedFilter": [
    {
      "field": "loggedInApps",
      "operator": "IN",
      "value": ["appId1", "appId2"]
    }
  ]
}

Filter by user's department

{
  "advancedFilter": [
    {
      "field": "department",
      "operator": "IN",
      "value": [
        {
          "organizationCode": "steamory",
          "departmentId": "root",
          "departmentIdType": "department_id",
          "includeChildrenDepartments": true
        }
      ]
    }
  ]
}

Method Name

ManagementClient.listUsers

Request Parameters

Name	Type	Is it required?	Default value	Description	Sample value
keywords	string	No	-	Fuzzy search keywords	xxxx xxx
advancedFilter	<a ListUsersAdvancedFilterItemDto[]	No	-	Advanced search	[{"field":"status","operator":"EQUAL","value":"Activated"}]
searchQuery	object	No	-	Use ES query statements to execute search commands	{"query":{"bool":{"must":[{"term":{"phone":"18818888888"}}],"must_not":[]}},"sort":["_score",{"created_at":"ASC"}]}
options	<a ListUsersOptionsDto	No	-	Optional	{"pagination":{"page":1,"limit":10},"fuzzySearchOn":["phone","email","name","username","nickname","identityNumber"],"withCustomData":true,"withIdentities":true,"withDepartmentIds":true}

Example Code

import { ManagementClient, Models } from "authing-node-sdk";

// Init ManagementClient
const managementClient = new ManagementClient({
  // Need to be replaced with your GenAuth Access Key ID
  accessKeyId: "GEN_AUTH_ACCESS_KEY_ID",
  // Need to be replaced with your GenAuth Access Key Secret
  accessKeySecret: "GEN_AUTH_ACCESS_KEY_SECRET",
  // If you are a private deployment customer, you need to set the GenAuth service domain name
  // host: 'https://api.your-authing-service.com'
});

(async () => {
  const result = await managementClient.listUsers({
    page: 1,
    limit: 10,
    withCustomData: true,
    withIdentities: true,
    withDepartmentIds: true,
  });

  console.log(JSON.stringify(result, null, 2));
})();

Request Response

type: UserPaginatedRespDto

Name	Type	Description
statusCode	number	Business status code, which can be used to determine whether the operation is successful. 200 means success.
message	string	Description
apiCode	number	Segmented error code, which can be used to get the specific error type (no return for successful requests). For a detailed list of error codes, please see: API Code List
requestId	string	Request ID. Returned when the request fails.
data	<a UserPagingDto	Response data

Sample result:

{
  "statusCode": 200,
  "message": "Success",
  "requestId": "934108e5-9fbf-4d24-8da1-c330328abd6c",
  "data": {
    "list": {
      "userId": "6229ffaxxxxxxxxcade3e3d9",
      "createdAt": "2022-07-03T03:20:30.000Z",
      "updatedAt": "2022-07-03T03:20:30.000Z",
      "status": "Activated",
      "workStatus": "Active",
      "externalId": "10010",
      "email": "test@example.com",
      "phone": "188xxxx8888",
      "phoneCountryCode": "+86",
      "username": "bob",
      "name": "xxxx",
      "nickname": "xxxx",
      "photo": "https://files.authing.co/authing-console/default-user-avatar.png",
      "loginsCount": 3,
      "lastLogin": "2022-07-03T03:20:30.000Z",
      "lastIp": "127.0.0.1",
      "gender": "M",
      "emailVerified": true,
      "phoneVerified": true,
      "passwordLastSetAt": "2022-07-03T03:20:30.000Z",
      "birthdate": "2022-06-03",
      "country": "CN",
      "province": "BJ",
      "city": "BJ",
      "address": "xxxxxxx",
      "streetAddress": "xxx street",
      "postalCode": "438100",
      "company": "steamory",
      "browser": "Mozilla/5.0 (Linux; Android 10; V2001A; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/87.0.4280.141 Mobile Safari/537.36 VivoBrowser/10.2.10.0",
      "device": "iOS",
      "givenName": "xx",
      "familyName": "xx",
      "middleName": "James",
      "profile": "alice",
      "preferredUsername": "alice",
      "website": "https://my-website.com",
      "zoneinfo": "GMT-08:00",
      "locale": "af",
      "formatted": "132, My Street, Kingston, New York 12401.",
      "region": "Xinjiang Uyghur Autonomous Region",
      "userSourceType": "register",
      "passwordSecurityLevel": 1,
      "departmentIds": "[\"624d930c3xxxx5c08dd4986e\",\"624d93102xxxx012f33cd2fe\"]",
      "identities": {
        "identityId": "62299d8b866d2dab79a89dc4",
        "extIdpId": "6076bacxxxxxxxxd80d993b5",
        "provider": "wechat",
        "type": "openid",
        "userIdInIdp": "oj7Nq05R-RRaqak0_YlMLnnIwsvg",
        "accessToken": "57_fK0xgSL_NwVlS-gmUwlMQ2N6AONNIOAYxxxx",
        "refreshToken": "57_IZFu91Ak1Wg6DRytZFFIOd3upNF5lH7vPxxxxx",
        "originConnIds": "[\"605492ac41xxxxe0362f0707\"]"
      },
      "identityNumber": "420421xxxxxxxx1234",
      "customData": {
        "school": "xxx",
        "age": 22
      },
      "statusChangedAt": "2022-07-03T03:20:30.000Z"
    }
  }
}

Data Structure

ListUsersAdvancedFilterItemDto

| Name | Type | Is this field required? | Description | Sample value | | ----------------- | ------- | ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- | --- | ---------------------------------------- | ------ | | field | string | yes | User fields specified for advanced search:
- id: User ID
- phone: Phone number
- email: Email address
- username: User name
- externalId: User ID in the external system
- name: Name
- status: User status, optional values are Activated and Suspended
- gender: User gender, optional values are M (male), F (female) and U (unknown)
- birthdate: Date of birth
- givenName: First name
- familyName: Last name
- preferredUsername: Preferred Username
- profile: Profile
- country: Country
- province: Province
- zoneinfo: Time zone
- website: personal website
- address: address
- streetAddress: street address
- company: company
- postalCode: postal code
- formatted: formatted address
- signedUp: registration time
- locale: language information
- lastLogin: last login time, as timestamp type
- loginsCount: number of logins, as numeric type
- lastLoginApp: last logged in application ID
- userSource: user source, see the example for specific usage
- department: user department, see the example for specific usage
- loggedInApps: applications that have been logged in, see the example for specific usage
- identity: user external identity source information, see the example for specific usage
- ... other custom fields
| nickname | | operator | string | It is the | operator, and the optional values are:
- EQUAL: all equal, applicable to all equal matching of numbers and strings
- NOT_EQUAL: not equal, applicable to matching of numbers and strings
- CONTAINS: string contains
- NOT_CONTAINS: string does not contain
- IS_NULL: empty
- NOT_NULL: not empty
- IN: an element in an array
- GREATER: greater than or equal to, applicable to comparison of numbers and date type data
- LESSER: less than or equal to, applicable to comparison of numbers and date type data
- BETWEEN: between something, applicable to comparison of numbers and date type data
| EQUAL | | value | object | No | Search value, different field may correspond to different value types, see the example for details. ost | boolean | No | Whether to obtain department information | true | | withIdentities | boolean | no | whether to obtain identities | true | | withDepartmentIds | boolean | no | whether to obtain department ID list | true | | flatCustomData | boolean | no | whether to flatten the extension field | |

PaginationDto

Name	Type	Is it required?	Description	Sample value
page	number	No	Current page number, starting from 1	1
limit	number	No	Number per page, maximum cannot exceed 50, default is 10	10

SortingDto

Name	Type	Is it required?	Description	Sample value
field	string	yes	The field to be sorted. Optional values are: - createdAt: creation time - updatedAt: modification time - email: email address - phone: phone number - username: username - externalId: external ID - status: public account status - statusChangedAt: status change time - passwordLastSetAt: password change time - loginsCount: number of logins - gender: gender - lastLogin: last login time - userSourceType: public account registration source - lastMfaTime: last MFA authentication time - passwordSecurityLevel: password security level - phoneCountryCode: Mobile phone area code - lastIp: IP used for last login	createdAt
order	string	yes	Sorting order: - desc: Sort by descending order from largest to smallest. - asc: Sort by ascending order from smallest to largest.	desc

UserPagingDto

Name	Type	Is it required?	Description	Sample value
totalCount	number	Yes	Total number of records
list	array	Yes	Data list Nested type: <a UserDto.

UserDto

Name	Type	Is it required?	Description	Sample value
userId	string	Yes	The unique identifier of the user, which can be user ID, user name, email address, mobile phone number, externalId, or ID in the external identity source. For details, see the description of the userIdType field. The default is user id.	6229ffaxxxxxxxxcade3e3d9
createdAt	string	Yes	Creation time	2022-07-03T03:20:30.000Z
updatedAt	string	yes	Update time	2022-07-03T03:20:30.000Z
status	string	yes	Current status of the account: - Activated: Normal status - Suspended: Deactivated - Deactivated: Disabled - Resigned: Resigned - Archived: Archived	Suspended
workStatus	string	yes	Current work status of the account	Closed
externalId	string	no	Third-party external ID	10010
email	string	no	Email address, case insensitive	test@example.com
phone	string	no	Mobile number without area code. If it is a foreign mobile number, please specify the area code in the phoneCountryCode parameter.	188xxxx8888
phoneCountryCode	string	No	Mobile phone area code. This field is optional for mainland China mobile phone numbers. The GenAuth SMS service does not yet support international mobile phone numbers. You need to configure the corresponding international SMS service in the GenAuth console. For a complete list of mobile phone area codes, please refer to https://en.wikipedia.org/wiki/List_of_country_calling_codes.	+86
username	string	No	Username, unique in the user pool	bob
name	string	No	User's real name, not unique	xxxx xxx
nickname	string	No	Nickname	xxxx xxx
photo	string	No	Avatar link	https://files.authing.co/authing-console/default-user-avatar.png
loginsCount	number	No	Total number of historical logins	3
lastLogin	string	No	Last login time	2022-07-03T03:20:30.000Z
lastIp	string	No	Last login IP	127.0.0.1
gender	string	Yes	Gender: - M: Male, male - F: Female, female - U: Unknown, unknown	M
emailVerified	boolean	yes	Is the email verified?	true
phoneVerified	boolean	yes	Is the phone number verified?	true
passwordLastSetAt	string	no	The time when the user last changed his password	2022-07-03T03:20:30.000Z
birthdate	string	no	Date of birth	2022-06-03
country	string	no	Country	CN
province	string	no	Province	BJ
city	string	no	City	BJ
address	string	no	Address	Beijing Chaoyang
streetAddress	string	no	Street address	Beijing Chaoyang District xxx Street
postalCode	string	no	Postal code	438100
company	string	no	Company	steamory
browser	string	no	Last login browser UA	Mozilla/5.0 (Linux; Android 10; V2001A; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/87.0.4280.141 Mobile Safari/537.36 VivoBrowser/10.2.10.0
device	string	no	Last login device	iOS
givenName	string	no	First name	xx
familyName	string	no	Last name	xx
middleName	string	no	Middle name	James
profile	string	no	Preferred Username	alice
preferredUsername	string	no	Preferred Username	alice
website	string	no	User personal website	https://my-website.com
zoneinfo	string	no	User time zone information	GMT-08:00
locale	string	no	Locale	af
formatted	string	no	Full standard address	132, My Street, Kingston, New York 12401.
region	string	no	User region	Xinjiang Uyghur Autonomous Region
userSourceType	string	yes	Source type: - excel: Imported through excel - register: User self-registration - adminCreated: Manually created by the administrator backend (including using the management API) Create user ) - syncTask: synchronization task in sync center	excel
userSourceId	string	No	Application ID or synchronization task ID
lastLoginApp	string	No	Application ID of the user's last login
mainDepartmentId	string	No	User's main department ID
lastMfaTime	string	No	Time of the user's last MFA authentication
passwordSecurityLevel	number	No	User password security strength level	1
resetPasswordOnNextLogin	boolean	No	Require password reset on next login
registerSource	array	No	Registration method
departmentIds	array	No	User's department ID list	["624d930c3xxxx5c08dd4986e","624d93102xxxx012f33cd2fe"]
identities	array	No	External identity source nested type: <a IdentityDto.
identityNumber	string	No	User ID number	420421xxxxxxxx1234
customData	object	No	User's extended field data	{"school":"Peking University","age":22}
postIdList	array	No	User-associated department ID
statusChangedAt	string	No	User status last modified time	2022-07-03T03:20:30.000Z
tenantId	string	No	User tenant ID

IdentityDto

Name	Type	Is this field required?	Description	Sample value
identityId	string	yes	Identity source ID	62299d8b866d2dab79a89dc4
extIdpId	string	yes	Identity source connection ID	6076bacxxxxxxxxd80d993b5
provider	string	yes	External identity source type: - wechat: WeChat - qq: QQ - wechatwork: WeChat Work - dingtalk: DingTalk - weibo: Weibo - github: GitHub - alipay: Alipay - baidu: Baidu - lark: Feishu - welink: Welink - yidun: NetEase Yidun - qingcloud: Qingyun - google: Google - gitlab: GitLab - gitee: Gitee - twitter: Twitter - facebook: Facebook - slack: Slack - linkedin: Linkedin - instagram: Instagram - oidc: OIDC-based enterprise identity source - oauth2: OAuth2-based enterprise identity source - saml: SAML-based enterprise identity source - ldap: LDAP-based enterprise identity source - ad: AD-based enterprise identity source - cas: CAS-based enterprise identity source - azure-ad: Azure AD-based enterprise identity source	oidc
type	string	Yes	Identity type, such as unionid, openid, primary	openid
userIdInIdp	string	Yes	ID in external identity source	oj7Nq05R-RRaqak0_YlMLnnIwsvg
userInfoInIdp	object	yes	User's identity information in idp
accessToken	string	no	Access Token in external identity source (this parameter is returned only when user actively obtains it, and it is not returned by management interface).	57_fK0xgSL_NwVlS-gmUwlMQ2N6AONNIOAYxxxx
refreshToken	string	no	Refresh Token in external identity source (this parameter is returned only when user actively obtains it, and it is not returned by management interface).	57_IZFu91Ak1Wg6DRytZFFIOd3upNF5lH7vPxxxxx
originConnIds	array	yes	Identity source connection ID list from which identity comes	one ["605492AS41XXXXXX0362F0707"]A