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


uststring------Current user's session token (UST)
current_appstring------Name of application that the call is attempted from
user_idstringYes---ID of user to find (will match either one or no user)
usernamestringYes---Username (ditto)
emailstringYes---E-mail (There is no requirement that it be unique)
display_namestringYes---Match by display name
first_namestringYes---Match by first name
middle_namestringYes---Match by middle name
last_namestringYes---Match by last name
sign_up_statusstringYes---User's sign up status, must be one of: before_confirmation, to_approve, final
approval_statusstringYes---User's approval status, must be one of: before_decision, approved, rejected
paginateboolYestrueShould the results be paginated
cur_pageintYes1Current page to return from a list of result pages (counted from 1)
page_sizeintYes50How many results to return on a single page
name_opstringYes"and"How to join name criteria (display/first/middle/last name), must be one of "and" or "or"
is_name_exactboolYestrueAre name criteria considered exact values to match or are they sub-strings


cidstring---Correlation ID assigned to request
statusstring---Overall status code
sub_statuslistYesReturned only if status is not "ok", a list of error or warning codes
resultlist---A list of results, possibly empty. Each element is a dictionary describing a single user.
result.user_idstring---ID of the user returned
result.usernamestring---Username of the user
result.display_namestringYesDisplay name
result.first_namestringYesFirst name
result.middle_namestringYesMiddle name
result.last_namestringYesLast name
result.is_totp_enabledboolYesShould TOTP-based two factor authentication be enabled for user
result.totp_keystringYesUser'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_labelstringYesAn arbitrary label assigned to user's TOTP key for convenience
result.is_activeboolYes(Reserved for future use)
result.is_internalboolYesDoes the account belong to Zato internally?
result.is_super_userboolYesIs the user a super-user?
result.is_approval_neededboolYesIs a super-user's approval needed for this account to become fully active?
result.approval_statusstringYesCurrent approval status, one of: before_decision, approved, rejected
result.approval_status_mod_bystringYesBy whom the approval status was last changed, will be 'auto' for users created from command line
result.approval_status_mod_timedatetimeYesWhen was the approval status last changed
result.is_lockedboolYesHas this account been locked by a super-user?
result.locked_timestringYesIf locked, when was it?
result.locked_bystringYesIf locked, who by?
result.creation_ctxstringYes(Reserved for future use)
result.approv_rej_timestringYesIf approved or rejected, when was it?
result.approv_rej_bystringYesIf approved or rejected, who by?
result.password_expirystringYesWhen will that account's password expire?
result.password_is_setboolYes(Reserved for future use)
result.password_must_changeboolYesIs the user required to change password on next login?
result.password_last_setstringYesWhen was the password last set?
result.sign_up_statusstringYesSignup process status, returned values are: before_confirmation, to_approve, final
result.sign_up_timedatetimeYesWhen did the user sign up with the system?


$ 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"