Home

hanko-frontend-sdk

This package utilizes the Hanko API to provide functionality that allows an easier UI integration. It is meant for use in browsers only.

Installation

# npm
npm install @teamhanko/hanko-frontend-sdk

# yarn
yarn add @teamhanko/hanko-frontend-sdk

# pnpm
pnpm install @teamhanko/hanko-frontend-sdk

Usage

Import as a module:

import { Hanko } from "@teamhanko/hanko-frontend-sdk"

const hanko = new Hanko("http://localhost:3000")

With a script tag via CDN:

<script src="https://cdn.jsdelivr.net/npm/@teamhanko/hanko-frontend-sdk/dist/sdk.umd.js"></script>

<script>
    const hanko = new hankoFrontendSdk.Hanko("http://localhost:3000")
    ...
</script>

Documentation

To see the latest documentation, please click here.

Exports

SDK

  • Hanko - A class that bundles all functionalities.

Clients

  • ConfigClient - A class to fetch configurations.
  • UserClient - A class to manage users.
  • WebauthnClient - A class to handle WebAuthn-related functionalities.
  • PasswordClient - A class to manage passwords and password logins.
  • PasscodeClient - A class to handle passcode logins.

Utilities

  • WebauthnSupport - A class to check the browser's WebAuthn support.

DTOs

  • Config
  • PasswordConfig
  • WebauthnFinalized
  • Credential
  • UserInfo
  • User
  • Email
  • Emails
  • Passcode

Errors

  • HankoError
  • TechnicalError
  • ConflictError
  • RequestTimeoutError
  • WebauthnRequestCancelledError
  • InvalidPasswordError
  • InvalidPasscodeError
  • InvalidWebauthnCredentialError
  • PasscodeExpiredError
  • MaxNumOfPasscodeAttemptsReachedError
  • NotFoundError
  • TooManyRequestsError
  • UnauthorizedError

Examples

Get the current user / Validate the JWT against the Hanko API

The Hanko API issues a JWT when a user logs in. For certain actions, like obtaining the user object, a valid JWT is required. The following example shows how to get the user object of the current user, or to identify that the user is not logged in:

import { Hanko, UnauthorizedError } from "@teamhanko/hanko-frontend-sdk"

const hanko = new Hanko("http://localhost:3000")

try {
    const user = await hanko.user.getCurrent()

    // A valid JWT is in place so that the user object was able to be fetched.
} catch (e) {
    if (e instanceof UnauthorizedError) {
        // Display an error or prompt the user to login again. After a successful call to `hanko.webauthn.login()`,
        // `hanko.password.login()` or `hanko.passcode.finalize()` a JWT will be issued and `hanko.user.getCurrent()`
        // would succeed.
    }
}

Register a WebAuthn credential

There are a number of situations where you may want the user to register a WebAuthn credential. For example, after user creation, when a user logs in to a new browser/device, or to take advantage of the "caBLE" support and pair a smartphone with a desktop computer:

import { Hanko, UnauthorizedError, WebauthnRequestCancelledError } from "@teamhanko/hanko-frontend-sdk"

const hanko = new Hanko("http://localhost:3000")

// By passing the user object (see example above) to `hanko.webauthn.shouldRegister(user)` you get an indication of
// whether a WebAuthn credential registration should be performed on the current browser. This is useful if the user has
// logged in using a method other than WebAuthn, and you then want to display a UI that allows the user to register a
// credential when possibly none exists.

try {
    // Will cause the browser to present a dialog with various options depending on the WebAuthn implemention.
    await hanko.webauthn.register()

    // Credential has been registered.
} catch(e) {
    if (e instanceof WebauthnRequestCancelledError) {
        // The WebAuthn API failed. Usually in this case the user cancelled the WebAuthn dialog.
    } else if (e instanceof UnauthorizedError) {
        // The user needs to login to perform this action.
    }
}

Bugs

Found a bug? Please report on our GitHub page.

License

The hanko-frontend-sdk project is licensed under the MIT License.