April 3, 2025

Hanko v2.0: Introducing the New Hanko JavaScript SDK

We’re thrilled to announce the release of Hanko v2.0!
This major update introduces a completely redesigned JavaScript/TypeScript SDK built to work hand-in-hand with our Flow API. It gives developers everything they need to build custom authentication experiences—backed by passkeys and all of Hanko’s powerful features.

When we launched Hanko v1.0 a few months ago, we introduced the Flow API to make our authentication logic more flexible, testable, and robust. While the primary driver for Flow API at the time was to improve the internals of Hanko itself, it quickly drew attention from developer teams wanting to build custom frontends and mobile apps using the raw API.

At the time, our main recommendation for most projects was to use Hanko Elements — a set of Web Components that deliver complete, drop-in authentication flows out of the box. Hanko Elements is built on top of the Flow API and gives teams a fast, no-code path to passkey-first login and account management, with deep configurability.

Under the hood, Hanko Elements has always used an internal SDK to interact with the Flow API. But while that internal SDK helped us ship our own UI fast, it wasn’t yet ready for the outside world. It lacked the simplicity, type safety, and developer experience we wanted to provide to teams building their own UIs.

Over the past several weeks, we’ve focused heavily on rebuilding this SDK from the ground up — and today, we’re excited to make it available to everyone.

A New SDK for Custom Frontends

The new JavaScript/TypeScript SDK introduced in Hanko v2.0 is designed for developers who want full control over their frontend, while still taking advantage of everything the Flow API has to offer — from passkeys, multi-factor authentication, and optional passwords to social logins, SSO, and more.

It offers a clean, typed interface for managing authentication flows via the Flow API, while taking care of things like:

  • state transitions
  • CSRF token handling
  • client-side session management
  • passkey autofill activation
  • action execution and error handling

Example usage:

const hanko = new Hanko({ apiUrl: "https://auth.example.com" });

const state = await hanko.createState("login");

await state.actions.continue_with_login_identifier.run({
  username: "maria@example.com",
});

hanko.onBeforeStateChange(({ state }) => {
  console.log(`Action invoked: ${state.invokedAction?.name}`);
});

hanko.onAfterStateChange(({ state }) => {
  console.log(`Transitioned to: ${state.name}`);

  if (state.name === "login_init") {
    state.passkeyAutofillActivation();
  }
});

This new SDK gives developers full flexibility to design their own user onboarding, login, and account management interfaces — using whatever UI framework they prefer.

Type-Safe Flows with Local State Management

One of the standout features of the new SDK is its local State object. Each flow state is modeled as a structured, serializable object that gives developers everything they need to render the UI for that step and trigger the correct actions.

  • All action calls are type-safe.
  • State changes can be handled using optional hooks (onBeforeStateChange, onAfterStateChange).
  • Session tokens can now be stored either in cookies or in sessionStorage, making it easy to define the right session lifetime for your use case.

Example configuration:

const hanko = new Hanko({
  apiUrl: "...",
  sessionTokenLocation: "sessionStorage", // ends session when tab closes
});

This makes it easy to create predictable, testable user flows — and integrate authentication deeply into your app’s own state management and UX logic.

When Should You Use the SDK?

If you’re looking to get started quickly with passkey-based authentication, Hanko Elements is still the fastest way. It gives you a fully working, themeable auth UI in minutes.

But if you're building a custom user experience — or you’re working on a mobile app or design system where Web Components don’t fit — the new SDK is for you.

It’s especially helpful if you:

  • need to customize copy, layout, or transitions in your auth UI
  • want to embed Hanko flows into a larger onboarding process
  • are building mobile-native apps that communicate with the Hanko backend
  • want more direct control over session lifetimes and UI rendering

What’s Next?

We’ll continue to expand the SDK with more features, helper functions, and tighter integrations with frontend frameworks like React, Vue, and Svelte. We’re also working on updated examples and documentation to help teams get started even faster.

Try It Out

Check out the updated documentation for implementation guides and the complete Flow API reference.

Got Feedback?

We’d love to hear what you’re building with the new SDK!
Feel free to open an issue, start a discussion on GitHub, or reach out to us on Discord.

Happy building! 🚀