Using the Hanko Frontend SDK

The following examples will cover some common use-cases for the hanko-frontend-sdk instance returned by the register() function, but please take a look into the frontend-sdk docs for details.

Hanko Elements Frontend SDK Guide:

About Hanko:

Hanko is a modern open source authentication solution and the fastest way you integrate passkeys, 2FA, SSO, and more—with full control over your data. Move between self-hosted and Hanko Cloud anytime. No lock-in. Just Auth how it should be: secure, user friendly, and fully yours.

What This Guide Covers: This guide demonstrates how to use the Hanko Frontend SDK directly for advanced authentication workflows and custom implementations. You’ll learn to handle authentication events, manage user sessions, and perform common operations without relying solely on web components.

Key Technologies:

• Hanko Frontend SDK
• JavaScript/TypeScript
• Authentication events
• Session management
• JWT handling
• User management
• Custom authentication flows

Prerequisites:

• Basic knowledge of JavaScript/TypeScript, authentication concepts, event handling, and Hanko Elements setup
• Understanding of JWT tokens and session management will be helpful

Tasks You’ll Complete:

• Create and configure a Hanko Frontend SDK instance
• Implement event listeners for authentication state changes
• Handle session creation, expiration, and user logout events
• Perform common operations like session validation and user data retrieval
• Manage authentication tokens and user sessions
• Build custom authentication flows using the SDK methods

You can create a hanko-frontend-sdk instance without registering the web components:

import { Hanko } from "@teamhanko/hanko-elements";
const hanko = new Hanko("YOUR_HANKO_API_URL");

Events

You can bind callbacks to different custom events using the SDK’s event listener functions. The callback function will be called when the event occurs, and an object containing event details will be passed to it.

Session created

Triggered after a session has been created and the user has completed any additional steps (e.g., passkey registration or password recovery). It will also be triggered when the user logs in via another browser window. You can use this event to obtain the JWT.

hanko.onSessionCreated(({ claims }) => {
  console.info("Session created with JWT claims:", claims);
    // Redirect to a protected page
});

Session expired

Triggered when the session has expired, or when the session has been removed in another browser window because the user has logged out or deleted their account.

hanko.onSessionExpired(() => {
  console.log("Session expired, redirecting to login");
  // Redirect to a login page or show the `<hanko-auth>` element.
});

User logged out

Triggered when the user actively logs out. In other browser windows, a “hanko-session-expired” event will be triggered at the same time.

hanko.onUserLoggedOut(() => {
  console.log("User logged out successfully");
  // Redirect to a login page or show the `<hanko-auth>` element.
});

User deleted

Triggered when the user has deleted their account. In other browser windows, a hanko-session-expired event will be triggered at the same time.

hanko.onUserDeleted(() => {
  console.log("User account deleted");
  // Redirect to a login page or show the `<hanko-auth>` element.
});

Common operations

The SDK provides functions that simplify interaction with the Hanko API. Here are some common operations:

Get the session validity and JWT claims:

const session = await hanko.validateSession();
console.log("Session valid:", session.is_valid, "Claims:", session.claims);

Retrieve the session token:

const token = hanko.getSessionToken();
console.log("Session token:", token);

Get the user data:

const user = await hanko.getUser();
console.log("User profile:", user.user_id, user.emails);

Log out the user:

await hanko.logout();
console.log("User logged out");

To learn about error handling and other SDK capabilities, check out the frontend-sdk docs.