In this guide you will learn how to create a credential with the Hanko API in just three simple steps.
We assume that a user has already created an account with your service (the relying party).
- When a user requests registration of a credential, your relying party application communicates basic user info to the Hanko Authentication API.
- The API generates credential creation options, including a challenge to which the user must respond using a cryptographically signed statement identifying the user.
- For this purpose, the user provides consent to generate a public/private credential key pair on the authenticator device using a local authorization gesture (e.g. through a PIN or biometrics).
- The private key is associated with the relying party and stored on a secure hardware element on the authenticator device. Unlike a password, the private key is never transmitted over the network. The public key is sent to the Hanko Authentication API along with the signed statement.
- The Hanko Authentication API validates the statement and stores the public key, associating it with a user ID.
The first step to registering a credential is to initialize the registration ceremony. Initialization consists of retrieving credential creation options from the Hanko API in order to trigger credential creation on an authenticator through the Web Authentication API.
In your frontend, trigger registration initialization by first making a request to your application backend. To process
the request you will need to implement a handler. In this case, we assume your backend handler responds to requests
issued to the
Your backend handler must then issue a
POST request to the registration initialization endpoint of the Hanko API
/v1/webauthn/registration/initialize- see also the API reference). The request body must include data about the user entity
on whose behalf registration is performed. The Hanko API does not manage user entities so user data must originate from
an existing relying party user store. In this guide we assume a user already has an existing account and valid session
with your application such that your backend is able to retrieve data from the user store and can construct an
appropriate request body. The user data object used as a request body must include:
id: this is used to map a credential to a specific user account. The user
idmust not contain personally identifying information.
displayName: these are human-readable descriptions of the user that are used for display purposes only
During registration initialization you can also specify additional options for the registration operation. For simplicity, this guide will not make use of these options and use only parameters that are required for creating a credential. In a more advanced implementation relying parties can
- require a specific type of authenticator device (see also Platform vs. Roaming authenticators)
- require user verification (see also User verification vs. user presence)
- require attestation of the device (see also Authenticator trust model)
- require credentials to be created as resident keys to enable usernameless authentication flows (see also Resident Keys )
On successful initialization the Hanko API will respond with the generated credential creation options. You will use these in the next step to trigger credential creation through the Web Authentication API.
Example JSON response: credential creation options
In order to create a new credential, your application frontend must pass the
credentialCreationOptions obtained in the
previous step to the browser through the Web Authentication API. To make things as convenient as possible, you can use
This will trigger a native browser dialog prompting the user to perform an authorization gesture. The dialog prompts differ depending on the available and connected authenticators. Once a user has given consent by performing the gesture, the authenticator generates a public/private credential key pair and returns the public key as part of the response.
The last step is to finalize the registration with the Hanko API.
webAuthnResponse from the previous step to your application backend. Again, you will need a corresponding
backend handler. Implement a handler that processes requests issued to the
Finalize the registration by forwarding the response sent by your frontend to the Hanko API using a
POST request to
the registration finalization endpoint (
/v1/webauthn/registration/finalize, see also the API
On successful finalization, the Hanko API returns a representation of the registered credential. This credential data can be used, for example, for display and management of credentials in a user profile. Congratulations, you have registered your first credential with the Hanko API!
Example JSON response: created credential
Are you looking for a more immersive learning experience? See how it all works by trying out our example application.