Hanko

API Reference

Frontend SDK

Standalone Passkey API

Tutorials

Start for free

Community

Validate a session using a session token in a request body.

Validate a session

Hanko is a lightweight, open source user authentication solution that takes you on the journey beyond passwords.

Introduction

Welcome to Hanko Docs

This guide will walk you through the initial set up process so that you can easily integrate Hanko Cloud into your projects.

Set up Hanko Cloud

Getting Started with Hanko Cloud

Learn how to use the Hanko Backend with your mobile apps.

Mobile (Beta)

Mobile Guide

Each project presents unique requirements for user onboarding. In this guide you'll learn to get user data from Hanko.

Get User Data

Passkeys

Passcodes

Fido Security Keys

Mobile App Biometrics

Hanko Elements provide web components that add a modern login and registration experience for your users.

Hanko Elements

A web component that handles user login and user registration.

Auth Component

A web component that allows to manage emails, passwords and passkeys.

Profile Component

A web component that allows to bind event handler to certain events, without displaying UI elements.

Events Component

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](https://teamhanko.github.io/hanko/jsdoc/hanko-frontend-sdk/) for details.

Using Frontend SDK

Using the Frontend SDK

This guide will walk you through the UI customization of Hanko Auth and Profile components.

Customize Appearance

Translations

Learn how to set up a custom SMTP server to send Hanko emails through your own SMTP server.

Custom SMTP Server

Send Hanko Emails with your own SMTP Server

This guide showcases how to add new user info, like user ID and email to the Supabase database, when users sign up with Hanko. Jump to [Nextjs guide](/quickstarts/fullstack/next) to learn how to add Hanko Auth in your Next App.

Supabase

Using Hanko with Supabase

Learn how to import users from other platforms to Hanko, as well as how to export users from Hanko.

Import and export users

Sessions

Webhooks allow you to get notified on changes

Webhooks

Learn more about Webhooks

Send emails with your own text and style.

Custom Emails

Send Custom Emails

Example apps showcasing integration of Hanko with your favorite frameworks

Examples

SDKs

Get Help

A guide to help you with common issues faced when working with Hanko Cloud

Troubleshoot

Collection of common questions that Hanko users get.

Hanko APIs

Add passkey support to your existing auth system with Hanko Passkey API.

Introduction to Passkey API

This guide will walk you through the initial set up process of a passkey project on Hanko Cloud.

Set up a Passkey Project

Set up Passkey Project

Setting up a Passkey Project on Hanko Cloud

Learn how to utilize the Passkey API using raw HTTP requests without any SDK.

Example Implementation

Learn how to implement multi-factor authentication (MFA) with Passkey using Passkey SDK.

Passkey MFA

Learn how to use passkeys to secure a payment transaction.

Example Payment Transaction

Learn how to start the login flow from your frontend.

Client-First Login Flow

A lean, type-safe, `fetch`-based API client for the Hanko Passkey API

JavaScript/TypeScript SDK

Learn how to add passkeys to your Next.js app which already uses Auth.js for authentication.

Next.js with NextAuth

Next.js with NextAuth (now known as Auth.js)

Example apps showcasing integration of Hanko Passkey API with your favorite frameworks

Discover how to build real world apps using Hanko for secure and efficient authentication.

This guide will show you how to add an easily manageable authorization layer on top of your Hanko implementation, providing you with a simple way to determine what users can access within the application after logging in.

Authorization with Permit.io

Using Hanko with Permit.io

Using Hanko Auth for a Todo app with Next.js 13 and Prisma

Next.js Todo App

Build a Todo app with Next.js 13 and Prisma

Initialize a registration for webauthn credentials

Start Passkey Registration

Finish Passkey Registration

Start Login

Finish Login

Get a list of webauthn credentials for a user

List Credentials

Endpoint for updating a webauthn credential

Update Credential

Endpoint for removing a webauthn credential

Remove Credential

Initializes a new transaction for an existing user

Initialize a transaction

Finalize transaction

Start MFA Login

Finish MFA Login

Initialize a registration for mfa credentials

Start MFA Registration

Finish MFA Registration

Well-known JWKS

This minimal example showcases how you can get user data using Public API from the userID obtained from the JWT.

Learn how to use the Hanko Public API

Initialize or advance a registration flow.

Registration

Login

Profile

Return information about the API status. Returns a 500 if there are issues with database connectivity.

Status page

Initialize a passcode login for the user identified by `user_id`. Sends an email
containing the actual passcode to the user's primary email address or to the address specified
through `email_id`. Returns a representation of the passcode.


Initialize passcode login

Finalize a passcode login given the `id` of the passcode and the actual `code` provided in the the email sent
to the user during initialization.

On success, sets the User's `verified` status to `true`.


Finalize passcode login

Perform a password login for the user identified by `user_id` and a given `password`.

This endpoint is only available if passwords have been enabled via [configuration](https://github.com/teamhanko/hanko/blob/main/backend/docs/Config.md#hanko-backend-config) option `passwords.enabled`.


Do password login

Create a or update an existing `password` for the user identified by `user_id`.

This endpoint is only available if passwords have been enabled via [configuration](https://github.com/teamhanko/hanko/blob/main/backend/docs/Config.md#hanko-backend-config) option `passwords.enabled`.


Create/Set a password

Initialize a login with Webauthn. Returns a JSON representation of CredentialRequestOptions for use
with the Webauthn API's `navigator.credentials.get()`.

Omitting the optional request body or using an empty JSON object results in generation of request options for a
login using a [discoverable credential](https://www.w3.org/TR/webauthn-2/#client-side-discoverable-public-key-credential-source)
(i.e. they will not contain
[allowCredentials](https://www.w3.org/TR/webauthn-2/#dom-publickeycredentialrequestoptions-allowcredentials)).

*Note*: The Webauthn API uses binary data represented by ArrayBuffers for certain input/output values.
The Hanko API returns these values as base64url-encoded, so they must be converted to ArrayBuffers
when passed to the Webauthn API. Similarly, Webauthn API output must be converted to base64url-encoded values
when passed to the Hanko API (e.g. using the [webauthn-json](https://github.com/github/webauthn-json) library).


Initialize WebAuthn login

Finalize a login with Webauthn using the WebAuthn API response to a `navigator.credentials.get()` call.

*Note*: The Webauthn API uses binary data represented by ArrayBuffers for certain input/output values.
The Hanko API returns these values as base64url-encoded, so they must be converted to ArrayBuffers
when passed to the Webauthn API. Similarly, Webauthn API output must be converted to base64url-encoded values
when passed to the Hanko API (e.g. using the [webauthn-json](https://github.com/github/webauthn-json) library).


Finalize WebAuthn login

Initialize a registration with Webauthn. Returns a JSON representation of CredentialCreationOptions for use
with the Webauthn API's `navigator.credentials.create()`.

*Note*: The Webauthn API uses binary data represented by ArrayBuffers for certain input/output values.
The Hanko API returns these values as base64url-encoded, so they must be converted to ArrayBuffers
when passed to the Webauthn API. Similarly, Webauthn API output must be converted to base64url-encoded values
when passed to the Hanko API (e.g. using the [webauthn-json](https://github.com/github/webauthn-json) library).


Initialize WebAuthn registration

Finalize a registration with Webauthn using the WebAuthn API response to a `navigator.credentials.create()` call.

*Note*: The Webauthn API uses binary data represented by ArrayBuffers for certain input/output values.
The Hanko API returns these values as base64url-encoded, so they must be converted to ArrayBuffers
when passed to the Webauthn API. Similarly, Webauthn API output must be converted to base64url-encoded values
when passed to the Hanko API (e.g. using the [webauthn-json](https://github.com/github/webauthn-json) library).


Finalize WebAuthn registration

Returns a list of WebAuthn credentials assigned to the current user.


Get a list of WebAuthn credentials

Deletes the specified WebAuthn credential.


Deletes a WebAuthn credential

Updates the specified WebAuthn credential. Only credentials assigned to the current user can be updated.


Updates a WebAuthn credential

Retrieve a [JSON Web Key Set](https://www.rfc-editor.org/rfc/rfc7517#section-5) (JWKS) object containing the public `keys` used to verify
JSON Web Tokens (JWT) issued by the Hanko API and signed using the RS256 signing algorithm.


Get JSON Web Key Set

Retrieve public backend configuration options.

Useful for example for conditionally constructing a UI based on the options (e.g. don't show password
inputs when they are disabled).


Get public Hanko configuration

Initialize an OAuth-backed (authorization code grant type) login with a third party provider by redirecting to
the specified provider login URL to retrieve an authorization code.


Initialize third party login

Callback endpoint called by the third party provider after successful login.

Third party provider callback

Provide a one time token (e.g. obtained through the [thirdparty callback](#tag/Third-Party/operation/thirdPartyCallback)) to retrieve a session JWT as cookie
and/or via `X-Auth-Token` header.


Exchange one time token for session

Retrieve details for user corresponding to the given `email`.

Get user details by email

Used to delete the current user. Note that `config.account.allow_deletion` must be set to true.

Deletes the current user

Retrieve the user ID for the current user (i.e. the subject of the JWT).

Get the current user ID

Logs out the user by removing the authorization cookie.

Log out the current user

Used to create a new user. To disable this endpoint, `config.account.allow_signup` must be set to false.

API Documentation

Public

Admin

Validate a session

Body

Response