Search test Users | API Reference | Descope Documentation

POST

/v2/mgmt/user/search/test

Authorization

Descope Project ID and Management Key

AuthorizationBearer <token>

Project ID:Management Key as bearer token.

In: header

Request Body

application/json

loginId?string

Search for specific login ID

tenantIds?array<string>

string

If not empty then users must be members of at least one of these tenants

roleNames?array<string>

string

If not empty then users must have one of the specified roles

limit?integer

Default is 100 if not specified

Formatint32

text?string

Full text search across relevant columns

page?integer

Page number starting with 0 for the first page

Formatint32

ssoOnly?boolean

Bring only users that have SSO external IDs

Defaultfalse

withTestUser?boolean

Return also users which are test users

testUsersOnly?boolean

Return only test users

Defaultfalse

customAttributes?object

Custom attributes as key-value pairs. Keys must be strings; values can be strings, numbers, booleans, or arrays.

Example

{
  "attribute-key": "attribute-value"
}

statuses?array<string>

string

If not empty then users must be in one of those statuses

emails?array<string>

string

phones?array<string>

string

ssoAppIds?array<string>

string

sort?array<managementv1.SortField>

loginIds?array<string>

string

fromCreatedTime?string

Lower bound on user creation time, inclusive. Unix timestamp in milliseconds, sent as a string (e.g. "1743465600000").

toCreatedTime?string

Upper bound on user creation time, inclusive. Unix timestamp in milliseconds, sent as a string (e.g. "1746057600000").

fromModifiedTime?string

Lower bound on user modification time, inclusive. Unix timestamp in milliseconds, sent as a string.

toModifiedTime?string

Upper bound on user modification time, inclusive. Unix timestamp in milliseconds, sent as a string.

userIds?array<string>

string

scimOnly?boolean

Bring only users that provisioned or updated by SCIM

tenantRoleIds?object

tenantRoleNames?object

includeSubTenants?boolean

password?boolean

totp?boolean

webauthn?boolean

scim?boolean

selectedColumns?array<string>

string

verifiedEmail?boolean

If provided, filter users by whether their email is verified

verifiedPhone?boolean

If provided, filter users by whether their phone is verified

offset?integer

Direct row offset for pagination (0-based). When set to a positive value, this takes precedence over the page-based offset (page * limit).

Formatint32

recoveryEmails?array<string>

string

If not empty then users must have one of the specified recovery emails (exact match)

recoveryPhones?array<string>

string

If not empty then users must have one of the specified recovery phones (exact match)

verifiedRecoveryEmail?boolean

If provided, filter users by whether their recovery email is verified

verifiedRecoveryPhone?boolean

If provided, filter users by whether their recovery phone is verified

searchFields?array<SearchField>

Structured field filters (wildcard LIKE, negation, array match). When set, these are ANDed with the scalar filters above. Field names must match the backend's searchable user columns; unknown fields are ignored. Only honored for widget-originated requests (x-descope-widget-id), gated by the MGMT_SEARCH_USERS_SEARCH_FIELDS feature flag (default on).

fromLastLoginTime?string

Lower bound on the user's last authentication time, inclusive. Unix timestamp in milliseconds, sent as a string (e.g. "1743465600000"). Users that never authenticated are excluded.

toLastLoginTime?string

Upper bound on the user's last authentication time, inclusive. Unix timestamp in milliseconds, sent as a string. Users that never authenticated are excluded.

Search test users, using a valid management key.

curl -X POST "https://api.descope.com/v2/mgmt/user/search/test" \
  -H "Content-Type: application/json" \
  -d '{}'

curl -X POST "https://api.descope.com/v2/mgmt/user/search/test" \  -H "Content-Type: application/json" \  -d '{}'

ResponseOK

{
  "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"
      ],
      "recoveryCodes": true
    }
  ],
  "total": 0
}

{  "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"      ],      "recoveryCodes": true    }  ],  "total": 0}

TypeScript

export interface Response {
users?: {
loginIds?: string[]
userId?: string
name?: string
email?: string
phone?: string
verifiedEmail?: boolean
verifiedPhone?: boolean
roleNames?: string[]
userTenants?: UserTenants[]
status?: string
externalIds?: string[]
picture?: string
test?: boolean
/**
 * Custom attributes as key-value pairs. Keys must be strings; values can be strings, numbers, booleans, or arrays.
 */
customAttributes?: {
[k: string]: string
}
createdTime?: number
TOTP?: boolean
SAML?: boolean
OAuth?: {
[k: string]: boolean
}
webauthn?: boolean
password?: boolean
ssoAppIds?: string[]
givenName?: string
middleName?: string
familyName?: string
editable?: boolean
SCIM?: boolean
push?: boolean
permissions?: string[]
OIDC?: boolean
consentExpiration?: number
recoveryEmail?: string
verifiedRecoveryEmail?: boolean
recoveryPhone?: string
verifiedRecoveryPhone?: boolean
modifiedTime?: 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[]
/**
 * whether the user has set up recovery codes
 */
recoveryCodes?: boolean
}[]
total?: number
}
export interface UserTenants {
tenantId?: string
roleNames?: string[]
tenantName?: string
permissions?: 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[]
}

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[]/** * whether the user has set up recovery codes */recoveryCodes?: boolean}[]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[]}

Was this helpful?