v2/mgmt/user/searchAuthorization
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
Lower bound on user creation time, inclusive. Unix timestamp in milliseconds, sent as a string (e.g. "1743465600000").
Upper bound on user creation time, inclusive. Unix timestamp in milliseconds, sent as a string (e.g. "1746057600000").
Lower bound on user modification time, inclusive. Unix timestamp in milliseconds, sent as a string.
Upper bound on user modification time, inclusive. Unix timestamp in milliseconds, sent as a string.
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).
int32If not empty then users must have one of the specified recovery emails (exact match)
If not empty then users must have one of the specified recovery phones (exact match)
If provided, filter users by whether their recovery email is verified
If provided, filter users by whether their recovery phone is verified
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
- 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" ], "roleIds": [ "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, "recoveryEmail": "string", "verifiedRecoveryEmail": true, "recoveryPhone": "string", "verifiedRecoveryPhone": true, "modifiedTime": 0, "roleIds": [ "string" ] } ], "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?: numberrecoveryEmail?: stringverifiedRecoveryEmail?: booleanrecoveryPhone?: stringverifiedRecoveryPhone?: booleanmodifiedTime?: number/** * roleIds holds the IDs of this entry's roles. Order is NOT guaranteed to match * roleNames — do not pair them by index. Use roleIds or roleNames independently. */roleIds?: string[]}[]total?: number}export interface UserTenants {tenantId?: stringroleNames?: string[]tenantName?: stringpermissions?: string[]/** * roleIds holds the IDs of this entry's roles. Order is NOT guaranteed to match * roleNames — do not pair them by index. Use roleIds or roleNames independently. */roleIds?: 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.
Create User POST
### Create a new user, using a valid management key. This API endpoint will create a new user utilizing a valid management key. This API endpoint allows you to configure all aspects of a user: - loginId - email - phone - verified settings (phone, email) - one must be set to true - displayName - roleNames - Tenant configurations - which tenantIds, which roleNames. The userTenants can include multiple items Ex: ``` "userTenants": [ { "tenantId": "T2IMjmRfYTQHlbaastz3im59ERS3", "roleNames": [ "Test" ] }, { "tenantId": "T2Igau6dX1R6SkomtFCdBLrc3r67", "roleNames": [ "Test" ] } ``` Additionally, you can create a user with multiple login IDs by passing an array of loginIds in string format within the `additionalIdentifiers` key. ### Next Steps Once the user is created, the user can then login utilizing any sign-in api supported. This will then switch the user from invited to active. ### See also - See [Manage User](/manage/users) for further details on managing users. - See [The User Object](/api/overview#the-user-object) for further details on the user object.