List users

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

application/json

application/grpc

application/grpc-web+proto

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 string required
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 string required
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 string required
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 string required
Possible values: non-empty and <= 200 characters
Defines the email 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 email query.
phoneQuery object
Limit the result to a specific contact phone.
number string required
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 string required
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 string required
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.
]

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 string required
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 string required
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 string required
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 string required
Possible values: non-empty and <= 200 characters
Defines the email 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 email query.
phoneQuery object
Limit the result to a specific contact phone.
number string required
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 string required
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 string required
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.
]

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 string required
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 string required
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 string required
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 string required
Possible values: non-empty and <= 200 characters
Defines the email 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 email query.
phoneQuery object
Limit the result to a specific contact phone.
number string required
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 string required
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 string required
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

• 200
• 400
• 403
• 404
• default

---

A list of all users matching the query

application/json

application/grpc

application/grpc-web+proto

Schema

Example (from schema)

---

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
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
type the file type of the key
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.
]

{
  "details": {
    "totalResult": "2",
    "processedSequence": "267831",
    "timestamp": "2024-03-27T10:05:49.730Z"
  },
  "sortingColumn": "FIELD_NAME_UNSPECIFIED",
  "result": [
    {
      "userId": "69629012906488334",
      "details": {
        "sequence": "2",
        "changeDate": "2024-03-27T10:05:49.730Z",
        "resourceOwner": "69629023906488334"
      },
      "authenticators": {
        "usernames": [
          {
            "usernameId": "string",
            "username": "gigi-giraffe",
            "isOrganizationSpecific": true
          }
        ],
        "password": {
          "lastChanged": "2019-04-01T08:45:00.000000Z"
        },
        "webAuthN": [
          {
            "webAuthNId": "69629023906488334",
            "name": "fido key",
            "isVerified": true,
            "userVerified": true
          }
        ],
        "totps": [
          {
            "totpId": "69629023906488334",
            "name": "Google Authenticator",
            "isVerified": true
          }
        ],
        "otpSms": [
          {
            "otpSmsId": "69629023906488334",
            "phone": "+41791234567",
            "isVerified": true
          }
        ],
        "otpEmail": [
          {
            "otpEmailId": "69629023906488334",
            "address": "mini@mouse.com",
            "isVerified": true
          }
        ],
        "authenticationKeys": [
          {
            "authenticationKeyId": "69629023906488334",
            "details": {
              "sequence": "2",
              "changeDate": "2024-03-27T10:05:49.731Z",
              "resourceOwner": "69629023906488334"
            },
            "type": "KEY_TYPE_JSON",
            "expirationDate": "3019-04-01T08:45:00.000000Z"
          }
        ],
        "identityProviders": [
          {
            "idpId": "69629023906488334",
            "idpName": "google",
            "userId": "as-12-df-89",
            "username": "gigi.long-neck@gmail.com"
          }
        ]
      },
      "contact": {
        "email": {
          "address": "mini@mouse.com",
          "isVerified": true
        },
        "phone": {
          "number": "+41791234567",
          "isVerified": true
        }
      },
      "state": "USER_STATE_UNSPECIFIED",
      "schema": {
        "id": "69629026806489455",
        "type": "employees",
        "revision": 7
      },
      "data": {}
    }
  ]
}

Schema

Example (from schema)

---

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
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
type the file type of the key
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.
]

{
  "details": {
    "totalResult": "2",
    "processedSequence": "267831",
    "timestamp": "2024-03-27T10:05:49.732Z"
  },
  "sortingColumn": "FIELD_NAME_UNSPECIFIED",
  "result": [
    {
      "userId": "69629012906488334",
      "details": {
        "sequence": "2",
        "changeDate": "2024-03-27T10:05:49.732Z",
        "resourceOwner": "69629023906488334"
      },
      "authenticators": {
        "usernames": [
          {
            "usernameId": "string",
            "username": "gigi-giraffe",
            "isOrganizationSpecific": true
          }
        ],
        "password": {
          "lastChanged": "2019-04-01T08:45:00.000000Z"
        },
        "webAuthN": [
          {
            "webAuthNId": "69629023906488334",
            "name": "fido key",
            "isVerified": true,
            "userVerified": true
          }
        ],
        "totps": [
          {
            "totpId": "69629023906488334",
            "name": "Google Authenticator",
            "isVerified": true
          }
        ],
        "otpSms": [
          {
            "otpSmsId": "69629023906488334",
            "phone": "+41791234567",
            "isVerified": true
          }
        ],
        "otpEmail": [
          {
            "otpEmailId": "69629023906488334",
            "address": "mini@mouse.com",
            "isVerified": true
          }
        ],
        "authenticationKeys": [
          {
            "authenticationKeyId": "69629023906488334",
            "details": {
              "sequence": "2",
              "changeDate": "2024-03-27T10:05:49.732Z",
              "resourceOwner": "69629023906488334"
            },
            "type": "KEY_TYPE_JSON",
            "expirationDate": "3019-04-01T08:45:00.000000Z"
          }
        ],
        "identityProviders": [
          {
            "idpId": "69629023906488334",
            "idpName": "google",
            "userId": "as-12-df-89",
            "username": "gigi.long-neck@gmail.com"
          }
        ]
      },
      "contact": {
        "email": {
          "address": "mini@mouse.com",
          "isVerified": true
        },
        "phone": {
          "number": "+41791234567",
          "isVerified": true
        }
      },
      "state": "USER_STATE_UNSPECIFIED",
      "schema": {
        "id": "69629026806489455",
        "type": "employees",
        "revision": 7
      },
      "data": {}
    }
  ]
}

Schema

Example (from schema)

---

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
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
type the file type of the key
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.
]

{
  "details": {
    "totalResult": "2",
    "processedSequence": "267831",
    "timestamp": "2024-03-27T10:05:49.733Z"
  },
  "sortingColumn": "FIELD_NAME_UNSPECIFIED",
  "result": [
    {
      "userId": "69629012906488334",
      "details": {
        "sequence": "2",
        "changeDate": "2024-03-27T10:05:49.733Z",
        "resourceOwner": "69629023906488334"
      },
      "authenticators": {
        "usernames": [
          {
            "usernameId": "string",
            "username": "gigi-giraffe",
            "isOrganizationSpecific": true
          }
        ],
        "password": {
          "lastChanged": "2019-04-01T08:45:00.000000Z"
        },
        "webAuthN": [
          {
            "webAuthNId": "69629023906488334",
            "name": "fido key",
            "isVerified": true,
            "userVerified": true
          }
        ],
        "totps": [
          {
            "totpId": "69629023906488334",
            "name": "Google Authenticator",
            "isVerified": true
          }
        ],
        "otpSms": [
          {
            "otpSmsId": "69629023906488334",
            "phone": "+41791234567",
            "isVerified": true
          }
        ],
        "otpEmail": [
          {
            "otpEmailId": "69629023906488334",
            "address": "mini@mouse.com",
            "isVerified": true
          }
        ],
        "authenticationKeys": [
          {
            "authenticationKeyId": "69629023906488334",
            "details": {
              "sequence": "2",
              "changeDate": "2024-03-27T10:05:49.734Z",
              "resourceOwner": "69629023906488334"
            },
            "type": "KEY_TYPE_JSON",
            "expirationDate": "3019-04-01T08:45:00.000000Z"
          }
        ],
        "identityProviders": [
          {
            "idpId": "69629023906488334",
            "idpName": "google",
            "userId": "as-12-df-89",
            "username": "gigi.long-neck@gmail.com"
          }
        ]
      },
      "contact": {
        "email": {
          "address": "mini@mouse.com",
          "isVerified": true
        },
        "phone": {
          "number": "+41791234567",
          "isVerified": true
        }
      },
      "state": "USER_STATE_UNSPECIFIED",
      "schema": {
        "id": "69629026806489455",
        "type": "employees",
        "revision": 7
      },
      "data": {}
    }
  ]
}

invalid list query

application/json

application/grpc

application/grpc-web+proto

Schema

Example (from schema)

---

Schema

code int32
message string
details object[]
Array [
@type string
]

{
  "code": 0,
  "message": "string",
  "details": [
    {
      "@type": "string"
    }
  ]
}

Schema

Example (from schema)

---

Schema

code int32
message string
details object[]
Array [
@type string
]

{
  "code": 0,
  "message": "string",
  "details": [
    {
      "@type": "string"
    }
  ]
}

Schema

Example (from schema)

---

Schema

code int32
message string
details object[]
Array [
@type string
]

{
  "code": 0,
  "message": "string",
  "details": [
    {
      "@type": "string"
    }
  ]
}

Returned when the user does not have permission to access the resource.

application/json

application/grpc

application/grpc-web+proto

Schema

Example (from schema)

---

Schema

code int32
message string
details object[]
Array [
@type string
]

{
  "code": 0,
  "message": "string",
  "details": [
    {
      "@type": "string"
    }
  ]
}

Schema

Example (from schema)

---

Schema

code int32
message string
details object[]
Array [
@type string
]

{
  "code": 0,
  "message": "string",
  "details": [
    {
      "@type": "string"
    }
  ]
}

Schema

Example (from schema)

---

Schema

code int32
message string
details object[]
Array [
@type string
]

{
  "code": 0,
  "message": "string",
  "details": [
    {
      "@type": "string"
    }
  ]
}

Returned when the resource does not exist.

application/json

application/grpc

application/grpc-web+proto

Schema

Example (from schema)

---

Schema

code int32
message string
details object[]
Array [
@type string
]

{
  "code": 0,
  "message": "string",
  "details": [
    {
      "@type": "string"
    }
  ]
}

Schema

Example (from schema)

---

Schema

code int32
message string
details object[]
Array [
@type string
]

{
  "code": 0,
  "message": "string",
  "details": [
    {
      "@type": "string"
    }
  ]
}

Schema

Example (from schema)

---

Schema

code int32
message string
details object[]
Array [
@type string
]

{
  "code": 0,
  "message": "string",
  "details": [
    {
      "@type": "string"
    }
  ]
}

An unexpected error response.

application/json

application/grpc

application/grpc-web+proto

Schema

Example (from schema)

---

Schema

code int32
message string
details object[]
Array [
@type string
]

{
  "code": 0,
  "message": "string",
  "details": [
    {
      "@type": "string"
    }
  ]
}

Schema

Example (from schema)

---

Schema

code int32
message string
details object[]
Array [
@type string
]

{
  "code": 0,
  "message": "string",
  "details": [
    {
      "@type": "string"
    }
  ]
}

Schema

Example (from schema)

---

Schema

code int32
message string
details object[]
Array [
@type string
]

{
  "code": 0,
  "message": "string",
  "details": [
    {
      "@type": "string"
    }
  ]
}

Loading...