Skip to main content
API docs by Redocly

Hanko Public API (0.4.0)

E-mail: developers@hanko.io License: AGPL-3.0-or-later
More about Hanko

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's primary email address or to the address specified through email_id. Returns a representation of the passcode.

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

The ID of the user

email_id
string <uuid4>

The ID of the email address

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",
  • "email_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.

https://github.com/teamhanko/hanko/blob/main/backend/docs/Config.md#hanko-backend-config
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) [ 8 .. 72 ] characters

The actual password, its minLength defaults to 8 but can be configured through the password.min_password_length option.

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.

https://github.com/teamhanko/hanko/blob/main/backend/docs/Config.md#hanko-backend-config
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.

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"
}

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) [ 8 .. 72 ] characters

The actual password, its minLength defaults to 8 but can be configured through the password.min_password_length option.

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 or using an empty JSON object 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
Example
{
  • "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

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.

https://github.com/teamhanko/hanko/blob/main/backend/docs/Config.md#hanko-backend-config
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
credential_id
string <base64url>
user_id
string <uuid4>

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"
}

Get a list of WebAuthn credentials

Returns a list of WebAuthn credentials assigned to the current user.

Authorizations:
CookieAuthBearerTokenAuth

Responses

Response Schema: application/json
Array
id
string <base64url>

The ID of the Webauthn credential

name
string

The name of the credential. Can be updated by the user.

public_key
boolean

The public key assigned to the credential.

aaguid
boolean

The AAGUID of the authenticator.

transports
Array of strings
Items Enum: "usb" "nfc" "ble" "internal"

Transports which may be used by the authenticator.

last_used_at
string <date-time>

The time when the credential was used last

created_at
string <date-time>

Time of creation of the credential

Response samples

Content type
application/json
[
  • {
    • "id": "5333cc5b-c7c4-48cf-8248-9c184ac72b65",
    • "name": "iCloud",
    • "public_key": "pQECYyagASFYIBblARCP_at3cmprjzQN1lJ...",
    • "aaguid": "adce0002-35bc-c60a-648b-0b25f1f05503",
    • "transports": [
      ],
    • "created_at": "022-12-06T21:26:06.535106Z"
    }
]

Updates a WebAuthn credential

Updates the specified WebAuthn credential. Only credentials assigned to the current user can be updated.

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

ID of the WebAuthn credential

Request Body schema: application/json
name
string

A new credential name. Has no technical meaning, only serves as an identification aid for the user.

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

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

Deletes a WebAuthn credential

Deletes the specified WebAuthn credential.

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

ID of the WebAuthn credential

Responses

Response samples

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

.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

Controls the behavior regarding email addresses.

object

Configuration options concerning passwords

object

Controls the behavior regarding user account.

Response samples

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

Third Party

Initialize third party login

Initialize an OAuth-backed (authorization code grant type) login with a third party provider by redirecting to the specified provider login URL to retrieve an authorization code.

query Parameters
provider
required
string
Enum: "google" "github"

The name of the third party provider to log in with. Only providers enabled in the configuration via the thirdparty.providers option can be used. Requesting an unsupported provider results in a redirect with error details in the location query.

redirect_to
required
string <base64url>

Base64url encoded string representing the URL the /callback eventually redirects to after successful login with the third party provider. It must match one of the allowed redirect URLs set in the backend configuration through the third_party.allowed_redirect_urls.

Responses

Third party provider callback

Callback endpoint called by the third party provider after successful login.

query Parameters
state
required
string

The state

code
string

The authorization code that can be exchanged for an access token and to retrieve user provider data

error
string

An error returned from the third party provider

error_description
string

The description of the error that occurred (if any)

Responses

Token

Exchange one time token for session

Provide a one time token (e.g. obtained through the thirdparty callback) to retrieve a session JWT as cookie and/or via X-Auth-Token header.

Request Body schema: application/json
value
string <base64url>

Responses

Request samples

Content type
application/json
{
  • "value": "string"
}

Response samples

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

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)
email_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",
  • "email_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"
}

Deletes the current user

Used to delete the current user. Note that config.account.allow_deletion must be set to true.

Authorizations:
CookieAuthBearerTokenAuth

Responses

Response samples

Content type
application/json
{
  • "code": 401,
  • "message": "Unauthorized"
}

Log out the current user

Logs out the user by removing the authorization cookie.

Authorizations:
CookieAuthBearerTokenAuth

Responses

Response samples

Content type
application/json
{
  • "code": 401,
  • "message": "Unauthorized"
}

Create a user

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

Responses

Response Schema: application/json
user_id
string <uuid4>

The ID of the newly created user

email_id
string <uuid4>

The ID of the newly created email address

Request samples

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

Response samples

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

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

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",
  • "webauthn_credentials": [
    • {
      }
    ]
}

Email Management

Get a list of emails of the current user.

Authorizations:
CookieAuthBearerTokenAuth

Responses

Response Schema: application/json
Array
id
string <uuid4>

The ID of the email address

address
string <email>

The email address

is_verified
boolean

Indicated the email has been verified.

is_primary
boolean

Indicates it's the primary email address.

Response samples

Content type
application/json
[
  • {
    • "id": "5333cc5b-c7c4-48cf-8248-9c184ac72b65",
    • "address": "john.doe@example.com",
    • "is_verified": true,
    • "is_primary": false
    }
]

Add a new email address to the current user.

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

Responses

Request samples

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

Response samples

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

Marks the email address as primary email

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

ID of the email address

Responses

Response samples

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

Delete an email address

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

ID of the email address

Responses

Response samples

Content type
application/json
{
  • "code": 401,
  • "message": "Unauthorized"
}