Skip to main content

Getting started

Set up your Hanko account

If you haven't done so already, first sign up for a Hanko account (it's free). After successful account creation you will be redirected to the Hanko Console. The Hanko Console is where you will manage your organizations, projects.

Create an organization

When you created an account with Hanko, a new organization was created for you - or you could have manually created one. An organization is the starting point for creating projects. An organization can have multiple projects associated with it.

When you create an organization you need to provide a name. The organization that was created for you has a default name. This name can always be changed through the organization dashboard.

Create a project

Click the "Create new project" panel. You will be asked to select the type of the project you want to create. Select "Authentication API" as your project type.

Create Authentication API project selection modal
Figure 1: Creating an "Authentication API" project - selecting your project type

When creating a Authentication API project party you must provide a name of your choosing and your web application's origin, i.e. the URL for the web application that you wish to secure using WebAuthn in order to register and authenticate users. In FIDO®/WebAuthn terms this application is called a relying party. Because WebAuthn must be run from a secure context, the origin has to be either

  • a local address (http://localhost) or
  • an https:// address (assuming that the application provides a valid SSL certificate)
note

This is a security property of WebAuthn API which ensures that all operations performed by authenticators are scoped to a particular origin, and cannot be replayed against a different origin.

Create Authentication API project initialization modal
Figure 2: Creating an "Authentication API" project - basic configuration

You can always switch between using an origin for local development & testing and a non-local origin in the "WebAutnn" settings for your Authentication API project.

Creating a new project results in creation of a Hanko Authentication API tenant. It may take a short moment for your tenant to be initialized. The project dashboard will provide you with a visual indicator of whether it is ready-to-use.

Obtain API base URL

Every Authentication API tenant has one base URL for all Hanko Authentication API endpoints. You can view your base URL in your Authentication API project dashboard in the Hanko Console (see also section "Server URL" in our API reference).

Display of API base URL in the Hanko Console relying party dashboard
Figure 3: Authentication API base URL in the Hanko Console

Generate an API Key

The last step before getting your hands dirty with the Hanko Authentication API is to create an API Key in order to be able to make authenticated calls to the API. Once you have created an Authentication API project you will be redirected to your project dashboard. In the left-hand side menu, select "API Keys". In the "API Keys" panel click "Create new" to generate an API Key (cf. Figure 2). The API Key consists of an ID and an API secret. Once you have generated an API Key, you can use it for authenticating with the Hanko Authentication API, see the API Reference for details.

Generate API Keys in the relying party general settings in the Hanko Console
Figure 4: Generate API Keys in the Hanko Console
Securing API Keys

API keys (both secrets and the Key ID) are sensitive information that must be kept secure during both storage and transmission to minimize exposure to attacks.

  • Do not embed API Keys directly in code to prevent accidental exposure in version control systems (especially when using a public one like GitHub). Instead, externalize configuration through environment variables or files outside your version control root.
  • Although you can generate as many API Keys as you need, it is recommended to keep track of and delete unneeded API Keys to minimize risk of attacks.