Migration Guide

​

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.

​

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

​

Migration Path

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 or hanko-elements versions older than 1.0.0.
2. When using any of the deprecated endpoints, migrate to the Flow API before the May 26, 2026 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 May 26, 2026 release date.
4. Test your integration thoroughly in a development environment.