Skip to main content

Hanko Public API (0.2.0)

Introduction

This is the OpenAPI specification for the Hanko Public API.

Authentication

The API uses JSON Web Tokens (JWTs) for authentication. JWTs are verified using JSON Web Keys (JWK). JWKs can be configured through the secrets.keys options. The API also publishes public cryptographic keys as a JWK set through the .well-known/jwks.json endpoint to enable clients to verify token signatures. JWTs must be provided on requests to protected endpoints using one of the following schemes:

CookieAuth

Security Scheme Type: API Key

Cookie parameter name: hanko

The JWT must be provided in a Cookie with the name hanko.

BearerTokenAuth

Security Scheme Type: http

HTTP Authorization Scheme: Bearer

Bearer format: JWT

The JWT must be provided in an HTTP Authorization header with bearer type: Authorization: Bearer <JWT>.

Cross-Origin Resource Sharing

Cross-Origin Resource Sharing (CORS) can be currently configured for public endpoints via the server.public.cors options.


Passcode

Initialize passcode login

Initialize a passcode login for the user identified by user_id. Sends an email containing the actual passcode to the user. Returns a representation of the passcode.

Request Body schema: application/json
user_id
string <uuid4>

The ID of the user

Responses

Response Schema: application/json
id
string <uuid4>

The ID of the passcode

ttl
integer

Lifespan of a passcode in seconds

created_at
string <date-time>

Time of creation of the passcode

Request samples

Content type
application/json
{
  • "user_id": "c339547d-e17d-4ba7-8a1d-b3d5a4d17c1c"
}

Response samples

Content type
application/json
{
  • "id": "c339547d-e17d-4ba7-8a1d-b3d5a4d17c1c",
  • "ttl": 300,
  • "created_at": "2019-08-24T14:15:22Z"
}

Finalize 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.

Request Body schema: application/json
id
string <uuid4>

The ID of the passcode

code
string = 6 characters

The actual passcode from the email sent to the user during initialization, a string of 6 decimal digits

Responses

Response Headers
X-Auth-Token
string <JWT> (X-Auth-Token)

Present only when enabled via configuration option session.enable_auth_token_header for purposes of cross-domain communication between client and Hanko API.

Set-Cookie
string (CookieSession)
Example: "hanko=<JWT>; Path=/; HttpOnly"

Contains the JSON Web Token (JWT) that must be provided to protected endpoints. Cookie attributes (e.g. domain) can be set via configuration option session.cookie.

Response Schema: application/json
id
string <uuid4>

The ID of the passcode

ttl
integer

Lifespan of a passcode in seconds

created_at
string <date-time>

Time of creation of the passcode

Request samples

Content type
application/json
{
  • "id": "c339547d-e17d-4ba7-8a1d-b3d5a4d17c1c",
  • "code": "897481"
}

Response samples

Content type
application/json
{
  • "id": "c339547d-e17d-4ba7-8a1d-b3d5a4d17c1c",
  • "ttl": 300,
  • "created_at": "2019-08-24T14:15:22Z"
}

Password

Do password 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 option passwords.enabled.

Request Body schema: application/json
user_id
required
string <uuid4>

The ID of the user to perform a password login for

password
required
string (Password) [ determined by configuration .. 72 ] characters

The actual password, its minLength is determined by configuration option password.min_password_length.

Responses

Response Headers
X-Auth-Token
string <JWT> (X-Auth-Token)

Present only when enabled via configuration option session.enable_auth_token_header for purposes of cross-domain communication between client and Hanko API.

Set-Cookie
string (CookieSession)
Example: "hanko=<JWT>; Path=/; HttpOnly"

Contains the JSON Web Token (JWT) that must be provided to protected endpoints. Cookie attributes (e.g. domain) can be set via configuration option session.cookie.

Response Schema: application/json
id
string <uuid4>

The ID of the passcode

ttl
integer

Lifespan of a passcode in seconds

created_at
string <date-time>

Time of creation of the passcode

Request samples

Content type
application/json
{
  • "user_id": "c339547d-e17d-4ba7-8a1d-b3d5a4d17c1c",
  • "password": "9UnCBEx924a45P7p"
}

Response samples

Content type
application/json
{
  • "id": "c339547d-e17d-4ba7-8a1d-b3d5a4d17c1c",
  • "ttl": 300,
  • "created_at": "2019-08-24T14:15:22Z"
}

Create/Set a password

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 option passwords.enabled.

Authorizations:
CookieAuthBearerTokenAuth
Request Body schema: application/json
user_id
required
string <uuid4>

The ID of the user to create/set a password for

password
required
string (Password) [ determined by configuration .. 72 ] characters

The actual password, its minLength is determined by configuration option password.min_password_length.

Responses

Request samples

Content type
application/json
{
  • "user_id": "c339547d-e17d-4ba7-8a1d-b3d5a4d17c1c",
  • "password": "9UnCBEx924a45P7p"
}

Response samples

Content type
application/json
{
  • "code": 400,
  • "message": "Bad Request"
}

WebAuthn

Initialize WebAuthn login

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 results in generation of request options for a login using a discoverable credential (i.e. they will not contain 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 library).

Request Body schema: application/json
user_id
string <uuid4>

The ID of the user on whose behalf WebAuthn login should be performed

Responses

Response Schema: application/json
object
challenge
string <base64url>
timeout
number <int64>
rpId
string
Array of objects
userVerification
string
Enum: "required" "preferred" "discouraged"

Request samples

Content type
application/json
{
  • "user_id": "c339547d-e17d-4ba7-8a1d-b3d5a4d17c1c"
}

Response samples

Content type
application/json
{
  • "publicKey": {
    • "challenge": "qgOI+0KpGnl9NOqaT6dfsYvi96R87LgpErnvePeOgSU=",
    • "timeout": 60000,
    • "rpId": "localhost",
    • "allowCredentials": [
      ],
    • "userVerification": "required"
    }
}

Finalize 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 library).

Request Body schema: application/json
id
string
rawId
string
type
string
Value: "public-key"
object

Responses

Request samples

Content type
application/json
{
  • "id": "_18q6IjW09tiM4NSbsZjocUtGx00Muv5mN6LZCelCMDD...",
  • "rawId": "_18q6IjW09tiM4NSbsZjocUtGx00Muv5mN6LZCelCMDD...",
  • "type": "public-key",
  • "response": {
    • "clientDataJson": "eyJ0eXBlIjoid2ViYXV0aG4uZ2V0IiwiY2hhbGxlbmdl...",
    • "authenticatorData": "SZYN5YgOjGh0NBcPZHZgW4_krrmihjLHmVzzuoMdl2MF...",
    • "signature": "MEQCIHe2RXqh6dyZw1LNXgeTTxljCV_qK2ydQjp02CiF...",
    • "userHandle": "rpe_EkgaSEeZG0TwzZyZJw"
    }
}

Response samples

Content type
application/json
{
  • "credential_id": "string",
  • "user_id": "string"
}

Initialize WebAuthn registration

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 library).

Authorizations:
CookieAuthBearerTokenAuth

Responses

Response Schema: application/json
object
object
object
challenge
string <base64url>
Array of objects
timeout
number <int64>
object
attestation
string
Enum: "none" "indirect" "direct" "enterprise"

Response samples

Content type
application/json
{
  • "publicKey": {
    • "rp": {
      },
    • "user": {
      },
    • "challenge": "7qmkJUXR0dOFnsW48evX3qKdCzlGjvvqAAvMDN+KTN0=",
    • "pubKeyCredParams": [
      ],
    • "timeout": 60000,
    • "authenticatorSelection": {
      },
    • "attestation": "none"
    }
}

Finalize 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 library).

Authorizations:
CookieAuthBearerTokenAuth
Request Body schema: application/json

Challenge response

id
string
rawId
string
type
string
Value: "public-key"
object

Responses

Response Schema: application/json
credential_id
string <base64>

The ID of the created credential

user_id
string <uuid4>

The ID of the user on whose behalf a credential was created

Request samples

Content type
application/json
{
  • "id": "_18q6IjW09tiM4NSbsZjocUtGx00Muv5mN6LZCelCMDD...",
  • "rawId": "_18q6IjW09tiM4NSbsZjocUtGx00Muv5mN6LZCelCMDD...",
  • "type": "public-key",
  • "response": {
    • "clientDataJson": "eyJ0eXBlIjoid2ViYXV0aG4uZ2V0IiwiY2hhbGxlbmdl...",
    • "attestationObject": "o2NmbXRkbm9uZWdhdHRTdG10oGhhdXRoRGF0YVjfSZYN...",
    • "transports": "internal"
    }
}

Response samples

Content type
application/json
{
  • "credential_id": "string",
  • "user_id": "c339547d-e17d-4ba7-8a1d-b3d5a4d17c1c"
}

.well-known

Get JSON Web Key Set

Retrieve a JSON Web Key Set (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.

Response samples

Content type
application/json
{
  • "keys": [
    • {
      }
    ]
}

Get public Hanko configuration

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).

Responses

Response Schema: application/json
object

Configuration options concerning passwords

enabled
boolean

Indicates whether passwords are enabled or not

min_password_length
number

Describes the minimum password length

Response samples

Content type
application/json
{
  • "password": {
    • "enabled": true,
    • "min_password_length": 8
    }
}

User Management

Get user details by email

Retrieve details for user corresponding to the given email.

Request Body schema: application/json
email
string <email>

Responses

Response Schema: application/json
id
string <uuid4> (UUID4)
verified
boolean
has_webauthn_credential
boolean

Request samples

Content type
application/json
{
  • "email": "user@example.com"
}

Response samples

Content type
application/json
{
  • "id": "c339547d-e17d-4ba7-8a1d-b3d5a4d17c1c",
  • "verified": true,
  • "has_webauthn_credential": true
}

Get the current user ID

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

Authorizations:
CookieAuthBearerTokenAuth

Responses

Response Schema: application/json
id
string <uuid4>

The id of the current user

Response samples

Content type
application/json
{
  • "id": "c339547d-e17d-4ba7-8a1d-b3d5a4d17c1c"
}

Create a user

Request Body schema: application/json
email
required
string <email>

Responses

Response Schema: application/json
id
string <uuid4>

The ID of the user

email
string <email>

The email address of the user

created_at
string <date-time>

Time of creation of the the user

updated_at
string <date-time>

Time of last update of the user

verified
boolean

Indicates whether the user's email address was verified

Array of objects

List of registered Webauthn credentials

Request samples

Content type
application/json
{
  • "email": "user@example.com"
}

Response samples

Content type
application/json
{
  • "id": "c339547d-e17d-4ba7-8a1d-b3d5a4d17c1c",
  • "email": "user@example.com",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "verified": true,
  • "webauthn_credentials": [
    • {
      }
    ]
}

Get a user by ID

path Parameters
id
required
string <uuid4> (UUID4)
Example: c339547d-e17d-4ba7-8a1d-b3d5a4d17c1c

ID of the user

Responses

Response Schema: application/json
id
string <uuid4>

The ID of the user

email
string <email>

The email address of the user

created_at
string <date-time>

Time of creation of the the user

updated_at
string <date-time>

Time of last update of the user

verified
boolean

Indicates whether the user's email address was verified

Array of objects

List of registered Webauthn credentials

Response samples

Content type
application/json
{
  • "id": "c339547d-e17d-4ba7-8a1d-b3d5a4d17c1c",
  • "email": "user@example.com",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "verified": true,
  • "webauthn_credentials": [
    • {
      }
    ]
}