Skip to main content

List user schemas​

List all matching user schemas. By default, we will return all user schema 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_TYPE, FIELD_NAME_STATE, FIELD_NAME_REVISION, FIELD_NAME_CHANGE_DATE]

    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
    typeQuery object

    Limit the result to a specific schema type.

    type string required

    Possible values: <= 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.

    stateQuery object

    Limit the result to a specific state of the schema.

    state string required

    Possible values: [STATE_UNSPECIFIED, STATE_ACTIVE, STATE_INACTIVE]

    Default value: STATE_UNSPECIFIED

    Defines the state to query for.

    idQuery object

    Limit the result to a specific schema ID.

    id string required

    Possible values: non-empty and <= 200 characters

    Defines the ID of the user schema 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.

  • ]
Responses

A list of all user schema 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_TYPE, FIELD_NAME_STATE, FIELD_NAME_REVISION, FIELD_NAME_CHANGE_DATE]

    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 [
    • id string

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

    details object

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

    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 string

    Type is a human readable text describing the schema.

    state string

    Possible values: [STATE_UNSPECIFIED, STATE_ACTIVE, STATE_INACTIVE]

    Default value: STATE_UNSPECIFIED

    Current state of the schema.

    revision int64

    Revision is a read only version of the schema, each update of the schema-field increases the revision.

    schema object

    JSON schema representation defining the user.

    possibleAuthenticators string[]

    Possible values: [AUTHENTICATOR_TYPE_UNSPECIFIED, AUTHENTICATOR_TYPE_USERNAME, AUTHENTICATOR_TYPE_PASSWORD, AUTHENTICATOR_TYPE_WEBAUTHN, AUTHENTICATOR_TYPE_TOTP, AUTHENTICATOR_TYPE_OTP_EMAIL, AUTHENTICATOR_TYPE_OTP_SMS, AUTHENTICATOR_TYPE_AUTHENTICATION_KEY, AUTHENTICATOR_TYPE_IDENTITY_PROVIDER]

    Defines the possible types of authenticators. This allows creating different user types like human/machine without usage of actions to validate possible authenticators. Removal of an authenticator does not remove the authenticator on a user.

  • ]
POST /v3alpha/user_schemas/search

Authorization

name: OAuth2type: oauth2scopes: openid,urn:zitadel:iam:org:project:id:zitadel:audflows: {
  "authorizationCode": {
    "authorizationUrl": "$CUSTOM-DOMAIN/oauth/v2/authorize",
    "tokenUrl": "$CUSTOM-DOMAIN/oauth/v2/token",
    "scopes": {
      "openid": "openid",
      "urn:zitadel:iam:org:project:id:zitadel:aud": "urn:zitadel:iam:org:project:id:zitadel:aud"
    }
  }
}

Request

Base URL
https://$CUSTOM-DOMAIN
Bearer Token
Content-Type
Body required
{

  "query": {

    "offset": "0",

    "limit": 100,

    "asc": true

  },

  "sortingColumn": "FIELD_NAME_TYPE",

  "queries": [

    {

      "orQuery": {

        "queries": [

          {

            "idQuery": {

              "id": "163840776835432705",

              "method": "TEXT_QUERY_METHOD_EQUALS"

            }

          },

          {

            "idQuery": {

              "id": "163840776835943483",

              "method": "TEXT_QUERY_METHOD_EQUALS"

            }

          }

        ]

      },

      "andQuery": {

        "queries": [

          {

            "typeQuery": {

              "id": "employees",

              "method": "TEXT_QUERY_METHOD_STARTS_WITH"

            }

          },

          {

            "stateQuery": {

              "state": "STATE_ACTIVE"

            }

          }

        ]

      },

      "notQuery": {

        "query": {

          "stateQuery": {

            "state": "STATE_ACTIVE"

          }

        }

      },

      "typeQuery": {

        "type": "employees",

        "method": "TEXT_QUERY_METHOD_EQUALS"

      },

      "stateQuery": {

        "state": "STATE_ACTIVE"

      },

      "idQuery": {

        "id": "163840776835432705",

        "method": "TEXT_QUERY_METHOD_EQUALS"

      }

    }

  ]

}
Accept
curl / cURL
curl -L -X POST 'https://$CUSTOM-DOMAIN/v3alpha/user_schemas/search' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <TOKEN>' \
--data-raw '{
  "query": {
    "offset": "0",
    "limit": 100,
    "asc": true
  },
  "sortingColumn": "FIELD_NAME_TYPE",
  "queries": [
    {
      "orQuery": {
        "queries": [
          {
            "idQuery": {
              "id": "163840776835432705",
              "method": "TEXT_QUERY_METHOD_EQUALS"
            }
          },
          {
            "idQuery": {
              "id": "163840776835943483",
              "method": "TEXT_QUERY_METHOD_EQUALS"
            }
          }
        ]
      },
      "andQuery": {
        "queries": [
          {
            "typeQuery": {
              "id": "employees",
              "method": "TEXT_QUERY_METHOD_STARTS_WITH"
            }
          },
          {
            "stateQuery": {
              "state": "STATE_ACTIVE"
            }
          }
        ]
      },
      "notQuery": {
        "query": {
          "stateQuery": {
            "state": "STATE_ACTIVE"
          }
        }
      },
      "typeQuery": {
        "type": "employees",
        "method": "TEXT_QUERY_METHOD_EQUALS"
      },
      "stateQuery": {
        "state": "STATE_ACTIVE"
      },
      "idQuery": {
        "id": "163840776835432705",
        "method": "TEXT_QUERY_METHOD_EQUALS"
      }
    }
  ]
}'