Skip to main content

Identity schema selection for self-service registration and login flows

Ory Kratos now supports selecting an identity schema during registration and login self-service flows by specifying a query parameter. This gives administrators more control over which schemas are used and allows multi-tenant or multi-profile setups with distinct identity models.

This feature is available in Ory Kratos OEL for now and will be available in Ory Network soon.

Overview​

  • Users or integrators can choose which schema to use by appending the identity_schema query parameter when initiating registration or login flows.
  • Only schemas explicitly marked as selectable via selfservice_selectable: true in the configuration will be accepted.
  • If no schema is selected, the default schema is used (this is the existing behavior).

How to Use​

Registration Example​

Browser flow:

GET /self-service/registration/browser?identity_schema=schema-a

API flow:

GET /self-service/registration/api?identity_schema=schema-a

Login Example​

Browser flow:

GET /self-service/login/browser?identity_schema=schema-a

API flow:

GET /self-service/login/api?identity_schema=schema-a

Configuration​

You must define which schemas are available for self-service selection by using the selfservice_selectable flag in your identity schema configuration.

Example Configuration​

identity:
  default_schema_id: default
  schemas:
    - id: default
      url: file://./schemas/default.schema.json
      selfservice_selectable: true

    - id: schema-a
      url: file://./schemas/schema-a.schema.json
      selfservice_selectable: true

    - id: schema-internal
      url: file://./schemas/internal.schema.json
      selfservice_selectable: false # This one cannot be selected by end users

Only schemas where selfservice_selectable: true will be selectable via the identity_schema parameter.

Behavior Summary​

  • If a schema is listed and marked as selectable, it can be used in registration/login.
  • If a schema is not listed or not marked as selectable, it cannot be used via query param.
  • If no identity_schema is passed, the default schema (default_schema_id) is used.

Migration Notes​

  • This feature is non-breaking. Existing flows using the default schema are unaffected.
  • You only need to update configuration if you want to expose multiple schemas for selection.
  • Schemas used internally (e.g., for admins or machine users) can remain non-selectable.