Authorization
Descope Project ID and Management Key Project ID:Management Key as bearer token.
In: header
Request Body
application/json
Search for specific login ID
If not empty then users must be members of at least one of these tenants
If not empty then users must have one of the specified roles
Default is 100 if not specified
int32Full text search across relevant columns
Page number starting with 0 for the first page
int32Bring only users that have SSO external IDs
falseReturn also users which are test users
Return only test users
falseCustom attributes as key-value pairs. Keys must be strings; values can be strings, numbers, booleans, or arrays.
{
"attribute-key": "attribute-value"
}If not empty then users must be in one of those statuses
Bring only users that provisioned or updated by SCIM
If provided, filter users by whether their email is verified
If provided, filter users by whether their phone is verified
Direct row offset for pagination (0-based). When set to a positive value, this takes precedence over the page-based offset (page * limit).
int32Search users, using a valid management key.
curl -X POST "https://api.descope.com/v1/mgmt/user/search" \ -H "Content-Type: application/json" \ -d '{}'{ "users": [ { "loginIds": [ "string" ], "userId": "string", "name": "string", "email": "string", "phone": "string", "verifiedEmail": true, "verifiedPhone": true, "roleNames": [ "string" ], "userTenants": [ { "tenantId": "string", "roleNames": [ "string" ], "tenantName": "string", "permissions": [ "string" ] } ], "status": "string", "externalIds": [ "string" ], "picture": "string", "test": false, "customAttributes": { "attribute-key": "attribute-value" }, "createdTime": 0, "TOTP": false, "SAML": false, "OAuth": { "property1": false, "property2": false }, "webauthn": true, "password": true, "ssoAppIds": [ "string" ], "givenName": "string", "middleName": "string", "familyName": "string", "editable": true, "SCIM": true, "push": true, "permissions": [ "string" ], "OIDC": true, "consentExpiration": 0 } ], "total": 0}export interface Response {users?: {loginIds?: string[]userId?: stringname?: stringemail?: stringphone?: stringverifiedEmail?: booleanverifiedPhone?: booleanroleNames?: string[]userTenants?: UserTenants[]status?: stringexternalIds?: string[]picture?: stringtest?: boolean/** * Custom attributes as key-value pairs. Keys must be strings; values can be strings, numbers, booleans, or arrays. */customAttributes?: {[k: string]: string}createdTime?: numberTOTP?: booleanSAML?: booleanOAuth?: {[k: string]: boolean}webauthn?: booleanpassword?: booleanssoAppIds?: string[]givenName?: stringmiddleName?: stringfamilyName?: stringeditable?: booleanSCIM?: booleanpush?: booleanpermissions?: string[]OIDC?: booleanconsentExpiration?: number}[]total?: number}export interface UserTenants {tenantId?: stringroleNames?: string[]tenantName?: stringpermissions?: string[]}See also
-
See Manage Users for further details on managing users.
-
See The User Object for further details on the user object. full: true seoTitle: Search Users | API Reference | Descope Documentation noIndex: true _openapi: method: POST toc: [] structuredData: headings: [] contents:
-
content: >-
Search for users, using a valid management key.
This API endpoint will search for users utilizing a valid management key. Searches can be defined with any combination of roles or tenants. You can also only send the request with an empty payload to return all users.
The response will include the following details on all users within an array of objects:
-
loginIds
-
userId
-
name
-
email
-
phone
-
verified settings (phone, email)
-
Tenant configurations (tenantIds, roleNames)
Next Steps
You can then parse through the response in order to find any users which you may need to delete, update, etc.
See also
-
See Manage Users for further details on managing users.
-
See The User Object for further details on the user object.
-
-
Authorization
Descope Project ID and Management Key Project ID:Management Key as bearer token.
In: header
Request Body
application/json
Search for specific login ID
If not empty then users must be members of at least one of these tenants
If not empty then users must have one of the specified roles
Default is 100 if not specified
int32Full text search across relevant columns
Page number starting with 0 for the first page
int32Bring only users that have SSO external IDs
falseReturn also users which are test users
Return only test users
falseCustom attributes as key-value pairs. Keys must be strings; values can be strings, numbers, booleans, or arrays.
{
"attribute-key": "attribute-value"
}If not empty then users must be in one of those statuses
Bring only users that provisioned or updated by SCIM
If provided, filter users by whether their email is verified
If provided, filter users by whether their phone is verified
Direct row offset for pagination (0-based). When set to a positive value, this takes precedence over the page-based offset (page * limit).
int32Search for users, using a valid management key.
This API endpoint will search for users utilizing a valid management key. Searches can be defined with any combination of roles or tenants. You can also only send the request with an empty payload to return all users.
The response will include the following details on all users within an array of objects:
- loginIds
- userId
- name
- phone
- verified settings (phone, email)
- Tenant configurations (tenantIds, roleNames)
Next Steps
You can then parse through the response in order to find any users which you may need to delete, update, etc.
See also
- See Manage Users for further details on managing users.
- See The User Object for further details on the user object.
curl -X POST "https://api.descope.com/v2/mgmt/user/search" \ -H "Content-Type: application/json" \ -d '{}'{ "users": [ { "loginIds": [ "string" ], "userId": "string", "name": "string", "email": "string", "phone": "string", "verifiedEmail": true, "verifiedPhone": true, "roleNames": [ "string" ], "userTenants": [ { "tenantId": "string", "roleNames": [ "string" ], "tenantName": "string", "permissions": [ "string" ] } ], "status": "string", "externalIds": [ "string" ], "picture": "string", "test": false, "customAttributes": { "attribute-key": "attribute-value" }, "createdTime": 0, "TOTP": false, "SAML": false, "OAuth": { "property1": false, "property2": false }, "webauthn": true, "password": true, "ssoAppIds": [ "string" ], "givenName": "string", "middleName": "string", "familyName": "string", "editable": true, "SCIM": true, "push": true, "permissions": [ "string" ], "OIDC": true, "consentExpiration": 0 } ], "total": 0}export interface Response {users?: {loginIds?: string[]userId?: stringname?: stringemail?: stringphone?: stringverifiedEmail?: booleanverifiedPhone?: booleanroleNames?: string[]userTenants?: UserTenants[]status?: stringexternalIds?: string[]picture?: stringtest?: boolean/** * Custom attributes as key-value pairs. Keys must be strings; values can be strings, numbers, booleans, or arrays. */customAttributes?: {[k: string]: string}createdTime?: numberTOTP?: booleanSAML?: booleanOAuth?: {[k: string]: boolean}webauthn?: booleanpassword?: booleanssoAppIds?: string[]givenName?: stringmiddleName?: stringfamilyName?: stringeditable?: booleanSCIM?: booleanpush?: booleanpermissions?: string[]OIDC?: booleanconsentExpiration?: number}[]total?: number}export interface UserTenants {tenantId?: stringroleNames?: string[]tenantName?: stringpermissions?: string[]}Get User Provider Token GET
### Get an existing user's provider token, using a valid management key. This API endpoint will loads the user's access token generated by the OAuth/OIDC provider, using a valid management key. When querying for OAuth providers, this only applies when utilizing your own account with the provider and have selected `Manage tokens from provider` selected under the [social auth methods](https://app.descope.com/settings/authentication/social). ### Query Params - `loginId` - The loginId of the user you want to get the provider token for. - `provider` - The provider you want to get the token for. - `withRefreshToken (optional)` - set to true to also return the refresh token. - `forceRefresh (optional)` - set to true to force a refresh of the token. ### See also - See [Manage Users](/manage/users) for further details on managing users. - See [The User Object](/api/overview#the-user-object) for further details on the user object. - See [Provider Options](/auth-methods/oauth#social-login-oauth-providers) for a the out of the box list of providers.
Get User's Login History POST
### Get an user's login history, using a valid management key. This API endpoint will loads the user's login history based on the user's userId. ### See also - See [Manage Users](/manage/users) for further details on managing users. - See [The User Object](/api/overview#the-user-object) for further details on the user object.