User.search - REST API

Super-users may look up other users using several search criteria, such as display name, user ID or username. Consult the introduction to user search APIs for more information on how the parameters can be combined.

On output, a list of results is returned, possibly empty or with one matching element only, along with metadata describing what is being returned, such as current page or total number of results.

Passwords are never returned on output.

Input parameters may be sent in query string or JSON body - there is no difference.

  • HTTP method: GET
  • URL path: /zato/sso/user/search

Request

Name Datatype Optional Default Notes
ust string --- --- Current user's session token (UST)
current_app string --- --- Name of application that the call is attempted from
user_id string Yes --- ID of user to find (will match either one or no user)
username string Yes --- Username (ditto)
email string Yes --- E-mail (There is no requirement that it be unique)
display_name string Yes --- Match by display name
first_name string Yes --- Match by first name
middle_name string Yes --- Match by middle name
last_name string Yes --- Match by last name
sign_up_status string Yes --- User's sign up status, must be one of: before_confirmation, to_approve, final
approval_status string Yes --- User's approval status, must be one of: before_decision, approved, rejected
paginate bool Yes true Should the results be paginated
cur_page int Yes 1 Current page to return from a list of result pages (counted from 1)
page_size int Yes 50 How many results to return on a single page
name_op string Yes "and" How to join name criteria (display/first/middle/last name), must be one of "and" or "or"
is_name_exact bool Yes true Are name criteria considered exact values to match or are they sub-strings

Response

Name Datatype Optional Notes
cid string --- Correlation ID assigned to request
status string --- Overall status code
sub_status list Yes Returned only if status is not "ok", a list of error or warning codes
result list --- A list of results, possibly empty. Each element is a dictionary describing a single user.
result.user_id string --- ID of the user returned
result.username string --- Username of the user
result.email string Yes E-mail
result.display_name string Yes Display name
result.first_name string Yes First name
result.middle_name string Yes Middle name
result.last_name string Yes Last name
result.is_totp_enabled bool Yes Should TOTP-based two factor authentication be enabled for user
result.totp_key string Yes User's TOTP key, one will be auto-generated for user if it is not given on input, even if is_totp_enabled is False
result.totp_label string Yes An arbitrary label assigned to user's TOTP key for convenience
result.is_active bool Yes (Reserved for future use)
result.is_internal bool Yes Does the account belong to Zato internally?
result.is_super_user bool Yes Is the user a super-user?
result.is_approval_needed bool Yes Is a super-user's approval needed for this account to become fully active?
result.approval_status string Yes Current approval status, one of: before_decision, approved, rejected
result.approval_status_mod_by string Yes By whom the approval status was last changed, will be 'auto' for users created from command line
result.approval_status_mod_time datetime Yes When was the approval status last changed
result.is_locked bool Yes Has this account been locked by a super-user?
result.locked_time string Yes If locked, when was it?
result.locked_by string Yes If locked, who by?
result.creation_ctx string Yes (Reserved for future use)
result.approv_rej_time string Yes If approved or rejected, when was it?
result.approv_rej_by string Yes If approved or rejected, who by?
result.password_expiry string Yes When will that account's password expire?
result.password_is_set bool Yes (Reserved for future use)
result.password_must_change bool Yes Is the user required to change password on next login?
result.password_last_set string Yes When was the password last set?
result.sign_up_status string Yes Signup process status, returned values are: before_confirmation, to_approve, final
result.sign_up_time datetime Yes When did the user sign up with the system?

Usage

$ curl "localhost:17010/zato/sso/user/search" -d '
{
    "ust": "gAAAAABapYP...",
    "current_app": "CRM",
    "last_name": "smith",
    "is_name_exact": false,
    "page_size": 2
}
'

{
    "cid": "cef98c3476d000b6685e685d",
    "cur_page": 1,
    "has_next_page": true,
    "has_prev_page": false,
    "next_page": 2,
    "num_pages": 3,
    "page_size": 2,
    "status": "ok",
    "total": 6
    "result": [
        {
            "approval_status": "approved",
            "approval_status_mod_by": "zusr69g59s4x3v9n1bwj978vfnf330",
            "approval_status_mod_time": "2028-03-10T17:41:26",
            "creation_ctx": null,
            "display_name": "Paul Greensmith",
            "email": "",
            "first_name": "Paul",
            "is_active": true,
            "is_internal": false,
            "is_locked": false,
            "is_super_user": false,
            "last_name": "Greensmith",
            "locked_by": null,
            "locked_time": null,
            "middle_name": null,
            "password_expiry": "2020-03-09T17:41:25",
            "password_is_set": true,
            "password_last_set": "2028-03-10T17:41:25",
            "password_must_change": false,
            "sign_up_status": "final",
            "sign_up_time": "2028-03-10T17:41:25",
            "user_id": "zusr5ts4qz0j5389ma37ja5j4zmtby",
            "username": "paul.greensmith"
        },
        {
            "approval_status": "approved",
            "approval_status_mod_by": "zusr69g59s4x3v9n1bwj978vfnf330",
            "approval_status_mod_time": "2028-03-10T17:41:04",
            "creation_ctx": null,
            "display_name": "Judith Smith",
            "email": "",
            "first_name": "Judith",
            "is_active": true,
            "is_internal": false,
            "is_locked": false,
            "is_super_user": false,
            "last_name": "Smith",
            "locked_by": null,
            "locked_time": null,
            "middle_name": null,
            "password_expiry": "2020-03-09T17:41:03",
            "password_is_set": true,
            "password_last_set": "2028-03-10T17:41:03",
            "password_must_change": false,
            "sign_up_status": "final",
            "sign_up_time": "2028-03-10T17:41:03",
            "user_id": "zusr3yqm708em08yn9tqmff5n1dkb6",
            "username": "judith.smith"
        }
    ]
}