Skip to main content

Search users

POST 
/resources/v3alpha/users/_search

Search all matching users. By default, we will return all users of your instance. Make sure to include a limit and sorting for pagination.

Request​

Query Parameters

    instance.id string
    instance.domain string
    query.offset uint64
    query.limit int64

    Maximum amount of events returned. If not configured otherwise, the default is 100, the maximum is 1000. If the limit exceeds the maximum, ZITADEL throws an error.

    query.desc boolean

    default is ascending, because together with the creation date sorting column, this returns the most deterministic pagination results.

    sortingColumn string

    Possible values: [FIELD_NAME_UNSPECIFIED, FIELD_NAME_ID, FIELD_NAME_CREATION_DATE, FIELD_NAME_CHANGE_DATE, FIELD_NAME_EMAIL, FIELD_NAME_PHONE, FIELD_NAME_STATE, FIELD_NAME_SCHEMA_ID, FIELD_NAME_SCHEMA_TYPE]

    Default value: FIELD_NAME_UNSPECIFIED

    the field the result is sorted.

Body

required

Define the criteria to query for.

  • Array [

    • orFilter

    object

    Union the results of each sub filter ('OR').

    queries

    object[]

  • Array [

    • 0
    1
    2
    3
    4
    5
    6
    7
    8
    9

  • ]

    • andFilter

    object

    Limit the result to match all sub queries ('AND'). Note that if you specify multiple queries, they will be implicitly used as andQueries. Use the andFilter in combination with orFilter and notFilter.

    queries

    object[]

  • Array [

    • 0
    1
    2
    3
    4
    5
    6
    7
    8
    9

  • ]

    • notFilter

    object

    Exclude / Negate the result of the sub query ('NOT').

    query

    object

    0
    1
    2
    3
    4
    5
    6
    7
    8
    9

    userIdFilter

    object

    Limit the result to a specific user ID.

    id stringrequired

    Possible values: non-empty and <= 200 characters

    Defines the ID of the user to query for.

    method string

    Possible values: [TEXT_FILTER_METHOD_EQUALS, TEXT_FILTER_METHOD_EQUALS_IGNORE_CASE, TEXT_FILTER_METHOD_STARTS_WITH, TEXT_FILTER_METHOD_STARTS_WITH_IGNORE_CASE, TEXT_FILTER_METHOD_CONTAINS]

    Default value: TEXT_FILTER_METHOD_EQUALS

    Defines which text comparison method used for the id query.

    organizationIdFilter

    object

    Limit the result to a specific organization.

    id stringrequired

    Possible values: non-empty and <= 200 characters

    Defines the ID of the organization to query for.

    method string

    Possible values: [TEXT_FILTER_METHOD_EQUALS, TEXT_FILTER_METHOD_EQUALS_IGNORE_CASE, TEXT_FILTER_METHOD_STARTS_WITH, TEXT_FILTER_METHOD_STARTS_WITH_IGNORE_CASE, TEXT_FILTER_METHOD_CONTAINS]

    Default value: TEXT_FILTER_METHOD_EQUALS

    Defines which text comparison method used for the id query.

    usernameFilter

    object

    Limit the result to a specific username.

    username stringrequired

    Possible values: non-empty and <= 200 characters

    Defines the username to query for.

    method string

    Possible values: [TEXT_FILTER_METHOD_EQUALS, TEXT_FILTER_METHOD_EQUALS_IGNORE_CASE, TEXT_FILTER_METHOD_STARTS_WITH, TEXT_FILTER_METHOD_STARTS_WITH_IGNORE_CASE, TEXT_FILTER_METHOD_CONTAINS]

    Default value: TEXT_FILTER_METHOD_EQUALS

    Defines which text comparison method used for the username query.

    isOrganizationSpecific boolean

    Defines that the username must only be unique in the organisation.

    emailFilter

    object

    Limit the result to a specific contact email.

    address stringrequired

    Possible values: <= 200 characters

    email address of the user

    method string

    Possible values: [TEXT_FILTER_METHOD_EQUALS, TEXT_FILTER_METHOD_EQUALS_IGNORE_CASE, TEXT_FILTER_METHOD_STARTS_WITH, TEXT_FILTER_METHOD_STARTS_WITH_IGNORE_CASE, TEXT_FILTER_METHOD_CONTAINS]

    Default value: TEXT_FILTER_METHOD_EQUALS

    Defines which text comparison method used for the email query.

    phoneFilter

    object

    Limit the result to a specific contact phone.

    number stringrequired

    Possible values: non-empty and <= 20 characters

    Defines the phone of the user to query for.

    method string

    Possible values: [TEXT_FILTER_METHOD_EQUALS, TEXT_FILTER_METHOD_EQUALS_IGNORE_CASE, TEXT_FILTER_METHOD_STARTS_WITH, TEXT_FILTER_METHOD_STARTS_WITH_IGNORE_CASE, TEXT_FILTER_METHOD_CONTAINS]

    Default value: TEXT_FILTER_METHOD_EQUALS

    Defines which text comparison method used for the phone query.

    stateFilter

    object

    Limit the result to a specific state of the user.

    state string

    Possible values: [USER_STATE_UNSPECIFIED, USER_STATE_ACTIVE, USER_STATE_INACTIVE, USER_STATE_DELETED, USER_STATE_LOCKED]

    Default value: USER_STATE_UNSPECIFIED

    Defines the state to query for.

    schemaIdFilter

    object

    Limit the result to a specific schema ID.

    id stringrequired

    Possible values: non-empty and <= 200 characters

    Defines the ID of the schema to query for.

    schemaTypeFilter

    object

    Limit the result to a specific schema type.

    type stringrequired

    Possible values: non-empty and <= 200 characters

    Defines which type to query for.

    method string

    Possible values: [TEXT_FILTER_METHOD_EQUALS, TEXT_FILTER_METHOD_EQUALS_IGNORE_CASE, TEXT_FILTER_METHOD_STARTS_WITH, TEXT_FILTER_METHOD_STARTS_WITH_IGNORE_CASE, TEXT_FILTER_METHOD_CONTAINS]

    Default value: TEXT_FILTER_METHOD_EQUALS

    Defines which text comparison method used for the type query.

  • ]

Responses​

A list of all users matching the query

Schema

    details

    object

    Details provides information about the returned result including total amount found.

    appliedLimit uint64
    totalResult uint64
    timestamp date-time

    the last time the projection got updated

    result

    object[]

    The result contains the user schemas, which matched the queries.

  • Array [

    • details

    object

    Details provide some base information (such as the last change date) of the user.

    id string
    created date-time

    the timestamp of the first event applied to the object.

    changed date-time

    the timestamp of the last event applied to the object.

    owner

    object

    the parent object representing the returned objects context.

    type string

    Possible values: [OWNER_TYPE_UNSPECIFIED, OWNER_TYPE_SYSTEM, OWNER_TYPE_INSTANCE, OWNER_TYPE_ORG]

    Default value: OWNER_TYPE_UNSPECIFIED

    id string

    schema

    object

    The schema the user and it's data is based on.

    id string

    The unique identifier of the user schema.

    type string

    The human readable name of the user schema.

    revision int64

    The revision the user's data is based on of the revision.

    data object

    contact

    object

    Contact information for the user. ZITADEL will use this in case of internal notifications.

    email

    object

    Email contact information of the user.

    address string

    Email address of the user.

    isVerified boolean

    IsVerified states if the email address has been verified to belong to the user.

    phone

    object

    Phone contact information of the user.

    number string

    Phone number of the user.

    isVerified boolean

    IsVerified states if the phone number has been verified to belong to the user.

    authenticators

    object

    The user's authenticators. They are used to identify and authenticate the user during the authentication process.

    usernames

    object[]

    All of the user's usernames, which will be used for identification during authentication.

  • Array [

    • usernameId string

    unique identifier of the username.

    username string

    The user's unique username. It is used for identification during authentication.

    isOrganizationSpecific boolean

    By default usernames must be unique across all organizations in an instance. This option allow to restrict the uniqueness to the user's own organization. As a result, this username can only be used if the authentication is limited to the corresponding organization.

    This can be useful if you provide multiple usernames for a single user, where one if specific to your organization, e.g.:

    • gigi-giraffe@zitadel.com (unique across organizations)
    • gigi-giraffe (unique only inside the ZITADEL organization)

  • ]

    • password

    object

    If the user has set a password, the time it was last changed will be returned.

    lastChanged date-time

    States the time the password was last changed.

    webAuthN

    object[]

    Meta information about the user's WebAuthN authenticators.

  • Array [

    • webAuthNId string

    unique identifier of the WebAuthN authenticator.

    name string

    Name of the WebAuthN authenticator. This is used for easier identification.

    isVerified boolean

    State whether the WebAuthN registration has been completed.

    userVerified boolean

    States if the user has been verified during the registration. Authentication with this device will be considered as multi-factor authentication (MFA) without the need to check a password (typically known as Passkeys). Without user verification it will be a second factor authentication (2FA), typically done after a password check.

    More on WebAuthN User Verification: https://www.w3.org/TR/webauthn/#user-verification

  • ]

    • totps

    object[]

    A list of the user's time-based one-time password (TOTP) authenticators, incl. the name for identification.

  • Array [

    • totpId string

    unique identifier of the time-based one-time password (TOTP) authenticator.

    name string

    The name provided during registration. This is used for easier identification.

    isVerified boolean

    State whether the TOTP registration has been completed.

  • ]

    • otpSms

    object[]

    A list of the user's one-time password (OTP) SMS authenticators.

  • Array [

    • otpSmsId string

    unique identifier of the one-time password (OTP) SMS authenticator.

    phone string

    The phone number used for the OTP SMS authenticator.

    isVerified boolean

    State whether the OTP SMS registration has been completed.

  • ]

    • otpEmail

    object[]

    A list of the user's one-time password (OTP) Email authenticators.

  • Array [

    • otpEmailId string

    unique identifier of the one-time password (OTP) Email authenticator.

    address string

    The email address used for the OTP Email authenticator.

    isVerified boolean

    State whether the OTP Email registration has been completed.

  • ]

    • authenticationKeys

    object[]

    A list of the user's authentication keys. They can be used to authenticate e.g. by JWT Profile.

  • Array [

    • authenticationKeyId string

    ID is the read-only unique identifier of the authentication key.

    details

    object

    id string
    created date-time

    the timestamp of the first event applied to the object.

    changed date-time

    the timestamp of the last event applied to the object.

    owner

    object

    the parent object representing the returned objects context.

    type string

    Possible values: [OWNER_TYPE_UNSPECIFIED, OWNER_TYPE_SYSTEM, OWNER_TYPE_INSTANCE, OWNER_TYPE_ORG]

    Default value: OWNER_TYPE_UNSPECIFIED

    id string
    type the file type of the key (string)

    Possible values: [AUTHN_KEY_TYPE_UNSPECIFIED, AUTHN_KEY_TYPE_JSON]

    Default value: AUTHN_KEY_TYPE_UNSPECIFIED

    expirationDate date-time

    After the expiration date, the key will no longer be usable for authentication.

  • ]

    • identityProviders

    object[]

    A list of the user's linked identity providers (IDPs).

  • Array [

    • idpId string

    IDP ID is the read-only unique identifier of the identity provider in ZITADEL.

    idpName string

    IDP name is the name of the identity provider in ZITADEL.

    userId string

    The user ID represents the ID provided by the identity provider. This ID is used to link the user in ZITADEL with the identity provider.

    username string

    The username represents the username provided by the identity provider.

  • ]

    • state string

    Possible values: [USER_STATE_UNSPECIFIED, USER_STATE_ACTIVE, USER_STATE_INACTIVE, USER_STATE_DELETED, USER_STATE_LOCKED]

    Default value: USER_STATE_UNSPECIFIED

    State of the user.

  • ]

Loading...