kratos

Breaking changes

What to check before upgrading, taken from the notes of the last 30 releases.

• v25.4.0Nov 7, 2025

  Breaking changes

  • Sessions API: The x-total-count header has been removed from GET /admin/sessions.

  Commit: e24f993ea

  • Account linking: Failed OIDC account linking flows now return HTTP 400 instead of 200 OK.

  Commit: ed4fba3ef

  • Verification flow: The show_verification_ui element is only included if the hook is explicitly configured.

  Commit: 5b00fe15d

  • OIDC registration: Failing fields are now placed in the default node group instead of oidc. Legacy behavior can be restored with feature_flags.legacy_oidc_registration_node_group=true.

  Commit: dc8b32e00

• v1.3.0Sep 26, 2024

  Breaking Changes

  When using two-step registration, it was previously possible to send method=profile:back to get to the previous screen. This feature was not documented in the SDK API yet. Going forward, please instead use screen=previous.

  Please note that the via parameter is deprecated when performing SMS 2FA. It will be removed in a future version. If the parameter is not included in the request, the user will see all their phone/email addresses from which to perform the flow.

  Before upgrading, ensure that your identity schema has the appropriate code configuration when using the code method for passwordless or 2fa login.

  If you are using the code method for 2FA login already, or you are using it for 1FA login but have not yet configured the code identifier, set selfservice.methods.code.config.missing_credential_fallback_enabled to true to prevent users from being locked out.

  Please note that the via parameter is deprecated when performing SMS 2FA. It will be removed in a future version. If the parameter is not included in the request, the user will see all their phone/email addresses from which to perform the flow.

  Before upgrading, ensure that your identity schema has the appropriate code configuration when using the code method for passwordless or 2fa login.

  If you are using the code method for 2FA login already, or you are using it for 1FA login but have not yet configured the code identifier, set selfservice.methods.code.config.missing_credential_fallback_enabled to true to prevent users from being locked out.

  Going forward, the /admin/session/.../extend endpoint will return 204 no content for new Ory Network projects. We will deprecate returning 200 + session body in the future.

  Bug Fixes

  • Add continue with only for json browser requests (#4002) (e0a4010)
  • Add fallback to providerLabel (#3999) (d26f204):

  This adds a fallback to the provider label when trying to register a duplicate identifier with an oidc.

  Current error message:

  Signing in will link your account to "test@test.com" at provider "". If you do not wish to link that account, please start a new login flow.

  The label represents an optional label for the UI, but in my case it's always empty. I suggest we fallback to the provider when the label is not present. In case the label is present, the behaviour won't change.

  Fallback to provider:

  Signing in will link your account to "test@test.com" at provider "google". If you do not wish to link that account, please start a new login flow.

  • Add missing JS triggers (7597bc6)
  • Add PKCE config key to config schema (#4098) (2c7ff3c)
  • Batch identity created event (#4111) (340f698)
  • Concurrent map update for webhook header (#4055) (6ceb2f1)
  • Do not populate id_first first step for account linking flows (#4074) (6ab2637)
  • Downgrade go-webauthn (#4035) (4d1954a)
• v1.2.0Jun 5, 2024

  Breaking Changes

  This feature enables two-step registration per default. Two-step registration is a significantly improved sign up flow and recommended when using more than one sign up methods. To disable two-step registration, set selfservice.flows.registration.enable_legacy_one_step to true. This value defaults to false.

  Bug Fixes

  • Add login succeeded event to post registration hook (#3739) (b685fa5)
  • Add missing env vars to set up guide (#3855) (da90502):

  Closes https://github.com/ory/kratos/issues/3828

  • Add missing indexes and remove unused index (6d7372e)
  • Add missing indexes and remove unused index (#3756) (c905f02)
  • Add sms mfa via parameter to spec (#3766) (b291c95)
  • Allow updating just the verified_at timestamp of addresses (#3880) (696cc1b)
  • Always issue session last (#3876) (e942507):

  In post persist hooks, the session issuance hook always needs

  to come last. This fixes the getHooks function to ensure this.

  • Audit issues (#3797) (7017490)
  • Change return urls in quickstarts (#3928) (9730e09)
  • Close res body (#3870) (cc39f8d)
  • CVEs in dependencies (#3902) (e5d3b0a)
  • Db index and duplicate credentials error (#3896) (9f34a21):

  • fix: don't return password cred type if empty
  • fix: better index for config.user_handle on identity_credentials

  • Do not require method to be passkey in settings schema (#3862) (660f330)
  • Don't require connection_uri in SMTP (#3861) (800f8f1)
  • Don't treat passkeys as AAL2 (#3853) (8eee972)
  • Drop index if exists (#3846) (ad0619d)
• v1.1.0Feb 20, 2024

  Breaking Changes

  Pagination parameters for the list identities CLI command have changed from arguments to flags --page-token and page-size:

  - kratos list identities 1 100
  + kratos list identities --page-size 100 --page-token ...
  

  Furthermore, the JSON / JSON pretty output of list identities has changed:

  -[
  -  { "id": "..." },
  -  { /* ... */ },
  -  // ...
  -]
  +{
  +  "identities": [
  +    {"id": "..."},
  +    { /* ... */ },
  +    // ...
  +  ],
  +  "next_page_token": "..."
  +}
  

  Closes https://github.com/ory/sdk/issues/284

  Closes https://github.com/ory/kratos/pull/3480

  Bug Fixes

  • oidc does not require a method in the payload (#3564) (b299abc):

  • fix: oidc does not require a method in the payload

  • refactor: only update strategies order in test
• v0.13.0Apr 18, 2023

  Breaking Changes

  By default, Kratos no longer sends out these Emails. If you want to keep notifying unknown addresses (keep the current behavior), set selfservice.flows.recovery.notify_unknown_recipients to true for recovery, or selfservice.flows.verification.notify_unknown_recipients for verification flows.

  Bug Fixes

  • Access rules example (#3178) (a206772)
  • Account experience redirects to verification page (#3195) (2e96d75)
  • Account settings broken on OIDC removal (#3185) (61ae531), closes ory-corp/cloud#3514
  • Add after_verification_return_to to sdk and api docs (#3097) (c70704c), closes #3096
  • Add HydraLoginRequest on flow creation (#3152) (09312dd), closes #3108:

  The oauth2_login_request field was missing when initially creating the login flow.

  • Add missing code discriminator in updateVerificationFlow (#3213) (21576be)
  • Add missing index (#3181) (756bed4)
  • Add mutex to test SMTP server setup/teardown (20c2359)
  • Avoid unchecked casts from IdentityPool to PrivilegedIdentityPool (71d35dd)
  • Correctly apply patches to identity metadata (#3103) (1193a56), closes #2950
  • Do not omit last page on identity list (#3169) (f95f48a)
  • Don't return 500 if active strategy is disabled (#3197) (3a734c2)
  • Don't reuse ports in courier/SMTP tests (#3156) (e260fcf)
  • Don't treat missing session as error in tracing (290d28a)
  • Error messages in OpenAPI/Swagger / improve error messages from failed webhooks and client timeouts (#3218) (b1bdcd3)
  • Handle upstream errors in patreon provider (#3032) (39fa31f)
  • Identity.CopyWithoutCredentials (989c99d)
  • Implement offline scope in the way google expects (#3088) (39043d4)
  • Improve webhook resilience (#3200) (0a05d99):

  • fix: improve webhook logging
• v0.11.1Jan 14, 2023

  Breaking Changes

  The /admin/courier/messages endpoint now uses keysetpagination instead.

  Bug Fixes

  • Add missing indexes (#2973) (bbb3995)
  • Add missing indexes for identity delete (#2952) (dc311f9):

  This significantly improves the performance of identity deletes.

  • Cors headers not added to the response #2922 (#2934) (1ed6839)
  • Dont reset to false (#2965) (ae8ad7b)
  • Flaky test now stable (4e5dcd0)
  • Listing sessions query (#2958) (3e06c99), closes #2930
  • Missing index on courier list count (#3002) (3b50711)
  • Pin geckodriver version to bypass GitHub API quota (#2972) (585cb9e)
  • Quickstart demos (#2940) (a7720b2)
  • Remove duplicate query in GetIdentity (#2987) (33b01bb)
  • Remove unused x-session-cookie parameter (#2983) (56b5c26):

  This patch removes the undocumented and experimental X-Session-Cookie header from the /sessions/whoami endpoint.

  • Resilient social sign in (#3011) (ca35b45)
  • Respect return_to URL parameter in registration flow when the user is already registered (#2957) (3462ce1)
  • Set accept header for GitLab (#2998) (e892113)
  • Set config at the start (e58bc6e)
  • Spurious cancelation of async webhooks, better tracing (#2969) (72de640):

  Previously, async webhooks (response.ignore=true) would be canceled

  early once the incoming Kratos request was served and it's associated

  context released. We now dissociate the cancellation of async hooks

• v0.11.0Dec 2, 2022

  Breaking Changes

  This patch changes the behavior of the recovery flow. It introduces a new strategy for account recovery that sends out short "one-time passwords" (code) that a user can use to prove ownership of their account and recovery access to it. This PR also updates the default recovery strategy to code.

  This patch invalidates recovery flows initiated using the Admin API. Please re-generate any admin-generated recovery flows and tokens.

  This is a breaking change, as it removes the courier.message_ttl config key and replaces it with a counter courier.message_retries.

  Closes https://github.com/ory/kratos/issues/402

  Closes https://github.com/ory/kratos/issues/1598

  SDK Method getJsonSchema was renamed to getIdentitySchema.

  Bug Fixes

  • Active attribute based off IsActive checks (#2901) (bcbf68e)
  • Add issuerURL for apple id (#2565) (2aeb0a2):

  No issuer url was specified when using the Apple ID provider,

  this forced usersers to manually enter it in the provider config.

  This PR adds the Apple ID issuer url to the provider simplifying the setup.

  • Add missing go.mod to docker build (7c4964e)
  • Add support for verified Graph API calls for facebook oidc provider (#2547) (1ba7c66)
  • Admin recovery CSRF & duplicate form elements (#2846) (de80b7f)
  • Bump docker image (#2594) (071c885)
  • Bump graceful to deal with http header timeouts (9ce2d26)
  • Cache migration status (#2631) (9020738):

  See https://github.com/ory-corp/cloud/issues/2691

  • Check return code of ms graphapi /me request. (#2647) (3f490a3)
  • cli: Dry up code (#2572) (d1b6b40)
  • Codecov (#2879) (e446c5a)
  • Correct name of span on recovery code deletion (#2823) (44f775f)
• v0.10.0May 30, 2022

  Breaking Changes

  Please be aware that the SDK method signatures for submitSelfServiceRecoveryFlow, submitSelfServiceRegistrationFlow, submitSelfServiceLoginFlow, submitSelfServiceSettingsFlow, submitSelfServiceVerificationFlow might have changed in your SDK.

  This patch moves several CLI command to comply with the Ory CLI command structure:

  - ory identities get ...
  + ory get identity ...
  
  - ory identities delete ...
  + ory delete identity ...
  
  - ory identities import ...
  + ory import identity ...
  
  - ory identities list ...
  + ory list identities ...
  
  - ory identities validate ...
  + ory validate identity ...
  
  - ory jsonnet format ...
  + ory format jsonnet ...
  
  - ory jsonnet lint ...
  + ory lint jsonnet ...
  

  This patch moves several CLI command to comply with the Ory CLI command structure: