API ReferenceManagementUsers
POST
/v2/mgmt/user/search

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. The response includes the following; however, there are additional items in the response that you can see below by expanding the response 200 OK.

  • loginIds
  • userId
  • name
  • email
  • phone
  • verified settings (phone, email)
  • Tenant configurations - which tenantIds, which 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

Endpoint Authentication

Use authorization bearer header with the following format:

Authorization: Bearer \<ProjectId:ManagementKey\>

Try it

/v2/mgmt/user/search

The Authorization access token

Authorization

Authorization
Required
Bearer <token>

< Project ID >:< Management Key > as bearer

In: header

Request Body

loginIdstring

Search for specific login ID

tenantIdsarray<string>

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

roleNamesarray<string>

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

limitinteger

Default is 100 if not specified

Format: "int32"

textstring

Full text search across relevant columns

pageinteger

Page number starting with 0 for the first page

Format: "int32"

ssoOnlyboolean

Bring only users that have SSO external IDs

Default: false

withTestUserboolean

Return also users which are test users

testUsersOnlyboolean

Return only test users

Default: false

customAttributesobject

Search for users with these custom attributes. Custom attributes filter should have string keys (attribute names that were configured for the user). Values should be either strings, ints or bools or lists (arrays) of strings, ints or bools for multiple matches.

statusesarray<string>

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

emailsarray<string>

phonesarray<string>

ssoAppIdsarray<string>

sortarray<object>

loginIdsarray<string>

Status codeDescription
200OK
curl -X POST "https://api.descope.com/v2/mgmt/user/search" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <ProjectId:ManagementKey>" \
  -d '{
  "loginId": "string",
  "tenantIds": [
    "string"
  ],
  "roleNames": [
    "string"
  ],
  "limit": 0,
  "text": "string",
  "page": 0,
  "ssoOnly": false,
  "withTestUser": true,
  "testUsersOnly": false,
  "customAttributes": {},
  "statuses": [
    "string"
  ],
  "emails": [
    "string"
  ],
  "phones": [
    "string"
  ],
  "ssoAppIds": [
    "string"
  ],
  "sort": [
    {
      "field": "string",
      "desc": true
    }
  ],
  "loginIds": [
    "string"
  ]
}'

{
  "users": [
    {
      "loginIds": [
        "string"
      ],
      "userId": "string",
      "name": "string",
      "email": "string",
      "phone": "string",
      "verifiedEmail": true,
      "verifiedPhone": true,
      "roleNames": [
        "string"
      ],
      "userTenants": [
        {
          "tenantId": "string",
          "roleNames": [
            "string"
          ],
          "tenantName": "string"
        }
      ],
      "status": "string",
      "externalIds": [
        "string"
      ],
      "picture": "string",
      "test": false,
      "customAttributes": {},
      "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
    }
  ],
  "total": 0
}

Was this helpful?

Previous

Get User Provider Token

Next

Get User's Login History