Skip to main content

List users

POST 
/v3alpha/users/search

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

Request​

Body

required

    query

    object

    list limitations and ordering.

    offset uint64
    limit int64

    Maximum amount of events returned. The default is set to 1000 in https://github.com/zitadel/zitadel/blob/new-eventstore/cmd/zitadel/startup.yaml. If the limit exceeds the maximum configured ZITADEL will throw an error. If no limit is present the default is taken.

    asc boolean

    default is descending

    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.

    queries

    object[]

    Define the criteria to query for.

  • Array [

    • orQuery

    object

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

    queries

    object[]

  • Array [

    • 0
    1
    2
    3
    4
    5
    6
    7
    8
    9

  • ]

    • andQuery

    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 andQuery in combination with orQuery and notQuery.

    queries

    object[]

  • Array [

    • 0
    1
    2
    3
    4
    5
    6
    7
    8
    9

  • ]

    • notQuery

    object

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

    query

    object

    0
    1
    2
    3
    4
    5
    6
    7
    8
    9

    userIdQuery

    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_QUERY_METHOD_EQUALS, TEXT_QUERY_METHOD_EQUALS_IGNORE_CASE, TEXT_QUERY_METHOD_STARTS_WITH, TEXT_QUERY_METHOD_STARTS_WITH_IGNORE_CASE, TEXT_QUERY_METHOD_CONTAINS, TEXT_QUERY_METHOD_CONTAINS_IGNORE_CASE, TEXT_QUERY_METHOD_ENDS_WITH, TEXT_QUERY_METHOD_ENDS_WITH_IGNORE_CASE]

    Default value: TEXT_QUERY_METHOD_EQUALS

    Defines which text comparison method used for the id query.

    organizationIdQuery

    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_QUERY_METHOD_EQUALS, TEXT_QUERY_METHOD_EQUALS_IGNORE_CASE, TEXT_QUERY_METHOD_STARTS_WITH, TEXT_QUERY_METHOD_STARTS_WITH_IGNORE_CASE, TEXT_QUERY_METHOD_CONTAINS, TEXT_QUERY_METHOD_CONTAINS_IGNORE_CASE, TEXT_QUERY_METHOD_ENDS_WITH, TEXT_QUERY_METHOD_ENDS_WITH_IGNORE_CASE]

    Default value: TEXT_QUERY_METHOD_EQUALS

    Defines which text comparison method used for the id query.

    usernameQuery

    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_QUERY_METHOD_EQUALS, TEXT_QUERY_METHOD_EQUALS_IGNORE_CASE, TEXT_QUERY_METHOD_STARTS_WITH, TEXT_QUERY_METHOD_STARTS_WITH_IGNORE_CASE, TEXT_QUERY_METHOD_CONTAINS, TEXT_QUERY_METHOD_CONTAINS_IGNORE_CASE, TEXT_QUERY_METHOD_ENDS_WITH, TEXT_QUERY_METHOD_ENDS_WITH_IGNORE_CASE]

    Default value: TEXT_QUERY_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.

    emailQuery

    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_QUERY_METHOD_EQUALS, TEXT_QUERY_METHOD_EQUALS_IGNORE_CASE, TEXT_QUERY_METHOD_STARTS_WITH, TEXT_QUERY_METHOD_STARTS_WITH_IGNORE_CASE, TEXT_QUERY_METHOD_CONTAINS, TEXT_QUERY_METHOD_CONTAINS_IGNORE_CASE, TEXT_QUERY_METHOD_ENDS_WITH, TEXT_QUERY_METHOD_ENDS_WITH_IGNORE_CASE]

    Default value: TEXT_QUERY_METHOD_EQUALS

    Defines which text comparison method used for the email query.

    phoneQuery

    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_QUERY_METHOD_EQUALS, TEXT_QUERY_METHOD_EQUALS_IGNORE_CASE, TEXT_QUERY_METHOD_STARTS_WITH, TEXT_QUERY_METHOD_STARTS_WITH_IGNORE_CASE, TEXT_QUERY_METHOD_CONTAINS, TEXT_QUERY_METHOD_CONTAINS_IGNORE_CASE, TEXT_QUERY_METHOD_ENDS_WITH, TEXT_QUERY_METHOD_ENDS_WITH_IGNORE_CASE]

    Default value: TEXT_QUERY_METHOD_EQUALS

    Defines which text comparison method used for the phone query.

    stateQuery

    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.

    schemaIDQuery

    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.

    schemaTypeQuery

    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_QUERY_METHOD_EQUALS, TEXT_QUERY_METHOD_EQUALS_IGNORE_CASE, TEXT_QUERY_METHOD_STARTS_WITH, TEXT_QUERY_METHOD_STARTS_WITH_IGNORE_CASE, TEXT_QUERY_METHOD_CONTAINS, TEXT_QUERY_METHOD_CONTAINS_IGNORE_CASE, TEXT_QUERY_METHOD_ENDS_WITH, TEXT_QUERY_METHOD_ENDS_WITH_IGNORE_CASE]

    Default value: TEXT_QUERY_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.

    totalResult uint64
    processedSequence uint64
    timestamp date-time

    the last time the projection got updated

    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

    States by which field the results are sorted.

    result

    object[]

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

  • Array [

    • userId string

    ID is the read-only unique identifier of the user.

    details

    object

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

    sequence uint64

    on read: the sequence of the last event reduced by the projection

    on manipulation: the timestamp of the event(s) added by the manipulation

    changeDate date-time

    on read: the timestamp of the last event reduced by the projection

    on manipulation: the timestamp of the event(s) added by the manipulation

    resourceOwner resource_owner is the organization or instance_id an object belongs to (string)

    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

    sequence uint64

    on read: the sequence of the last event reduced by the projection

    on manipulation: the timestamp of the event(s) added by the manipulation

    changeDate date-time

    on read: the timestamp of the last event reduced by the projection

    on manipulation: the timestamp of the event(s) added by the manipulation

    resourceOwner resource_owner is the organization or instance_id an object belongs to (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.

  • ]

    • 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.

    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.

    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

    The user's data based on the provided schema.

  • ]

Loading...