Skip to main content

Getting started

In order to get started with Hanko, you must first create an account. Follow this link and select "Create account". After entering basic user information, you can select the type of authenticator you want to register an account with.

note

All accounts start on a free tier so you don't need to provide a credit card or any billing information to sign up. If you choose to upgrade to a paid plan, you can do so using organization management in the Hanko Console.

Create an organization and relying party#

After succesful account creation you will be redirected to the Hanko Console. The next step is to create an organization. Click on the "Create new organization"-panel and provide a name for the organization.

Once you have created an organization, select the organization and click the "Create new relying party"-panel to create a relying party. A relying party represents a web application that you wish to secure using WebAuthn in order to register and authenticate users. An organization can manage multiple relying parties.

When creating a relying party you must provide a relying party name of your choosing and your web application's Origin. Because WebAuthn must be run from a secure context, this 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.

Obtain API base URL#

Every relying party has its own API server URL which serves as the base URL for all Hanko Authentication API endpoints. You can view your server URL in your relying party 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 1: Relying party 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 a relying party you will be redirected to your relying party dashboard. On the dashboard, select "General Settings" and in the "API Keys" panel click "Add 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 2: 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.