Migration Guide

Migration guide for upgrading from Hanko 2.x.x to 3.0.0

Overview

Hanko 3.0.0 removes previously deprecated API endpoints. This guide outlines the breaking changes and migration path for upgrading from version 2.x.x to 3.0.0.

Hanko 3.0.0 is scheduled for release on Hanko Cloud on May 26, 2026. Please plan your migration accordingly.

Breaking Changes

Deprecated API Endpoints

The following Public API endpoints have been deprecated and will be removed in version 3.0.0:

Authentication Endpoints:

• POST /passcode/login/initialize
• POST /passcode/login/finalize
• POST /password/login
• PUT /password

WebAuthn Endpoints:

• POST /webauthn/login/initialize
• POST /webauthn/login/finalize
• POST /webauthn/registration/initialize
• POST /webauthn/registration/finalize
• GET /webauthn/credentials
• DELETE /webauthn/credentials/{id}
• PATCH /webauthn/credentials/{id}

Configuration & Authentication:

• GET /.well-known/config
• GET /thirdparty/auth
• POST /token

User Management:

• POST /user
• DELETE /user
• POST /users
• GET /users/{id} (use GET /me instead)

Email Management:

• GET /emails
• POST /emails
• POST /emails/{id}/set_primary
• DELETE /emails/{id}

SAML:

• GET /saml/provider

Deprecated SDK functions

• getUser() (use getCurrentUser() instead)

Migration Path

Exception: If your integration only uses hanko-elements version 1.0.0 or later and does not use the Hanko API directly, you only need to check that you are using getCurrentUser() instead of getUser().

All deprecated endpoints have been replaced with the new Flow API, which provides a unified and streamlined authentication interface.

Check out the Understanding the Flow API guide and Build a custom login flow guide for more information about building your own custom UI.

Action Required

To ensure a smooth transition:

1. Review your current implementation and check for any usage of deprecated API endpoints, SDK functions, or hanko-elements versions older than 1.0.0.
2. When using any of the deprecated endpoints, migrate to the Flow API before the v3.0.0 release date. Refer to the Flow API documentation for implementation details.
3. When using hanko-elements versions older than 1.0.0, migrate to the latest version before the v3.0.0 release date.
4. Replace all usage of getUser() with getCurrentUser().
5. Test your integration thoroughly in a development environment.

Need assistance with your migration? Contact our support team or visit our community Discord for help.