Hanko webauthn API
Represents all objects which are related to WebAuthn in common
OpenAPI Specification
openapi: 3.0.3
info:
version: 1.2.0
title: Hanko Admin Audit Logs webauthn API
description: '## Introduction
This is the OpenAPI specification for the [Hanko Admin API](https://github.com/teamhanko/hanko/blob/main/backend/README.md#start-private-api).
## Authentication
The Admin API must be protected by an access management system.
---
'
contact:
email: developers@hanko.io
license:
name: AGPL-3.0-or-later
url: https://www.gnu.org/licenses/agpl-3.0.txt
servers:
- url: https://{tenant_id}.hanko.io/admin
variables:
tenant_id:
default: ''
description: The (UU)ID of a tenant. Replace the default value with your tenant ID.
tags:
- name: webauthn
description: Represents all objects which are related to WebAuthn in common
paths:
/{tenant_id}/.well-known/jwks.json:
get:
tags:
- webauthn
summary: Well-known JWKS
description: Endpoint for fetching JWKS
operationId: get-.well-known-jwks.json
parameters:
- $ref: '#/components/parameters/tenant_id'
responses:
'200':
$ref: '#/components/responses/jwks'
servers:
- url: https://passkeys.hanko.io
/webauthn/login/initialize:
post:
summary: Initialize WebAuthn login
description: '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](https://www.w3.org/TR/webauthn-2/#client-side-discoverable-public-key-credential-source)
(i.e. they will not contain
[allowCredentials](https://www.w3.org/TR/webauthn-2/#dom-publickeycredentialrequestoptions-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](https://github.com/github/webauthn-json) library).
'
operationId: webauthnLoginInit
tags:
- webauthn
deprecated: true
requestBody:
content:
application/json:
schema:
type: object
properties:
user_id:
description: The ID of the user on whose behalf WebAuthn login should be performed
allOf:
- $ref: '#/components/schemas/UUID4'
responses:
'200':
description: Successful initialization
content:
application/json:
schema:
$ref: '#/components/schemas/CredentialRequestOptions'
examples:
non-disco:
summary: Non-Discoverable credentials
value:
publicKey:
challenge: qgOI+0KpGnl9NOqaT6dfsYvi96R87LgpErnvePeOgSU=
timeout: 60000
rpId: localhost
allowCredentials:
- type: public-key
id: Mepptysj5ZZrTlg0qiLbsZ068OtQMeGVAikVy2n1hvvG...
userVerification: required
disco:
summary: Discoverable credentials
value:
challenge: qgOI+0KpGnl9NOqaT6dfsYvi96R87LgpErnvePeOgSU=
timeout: 60000
rpId: localhost
userVerification: required
'400':
$ref: '#/components/responses/BadRequest'
'500':
$ref: '#/components/responses/InternalServerError'
/webauthn/login/finalize:
post:
summary: Finalize WebAuthn login
description: '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](https://github.com/github/webauthn-json) library).
'
operationId: webauthnLoginFinal
tags:
- webauthn
deprecated: true
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PublicKeyCredentialAssertionResponse'
responses:
'200':
description: Successful login
headers:
X-Auth-Token:
description: 'Present only when enabled via [configuration](https://github.com/teamhanko/hanko/blob/main/backend/docs/Config.md#hanko-backend-config) option `session.enable_auth_token_header`
for purposes of cross-domain communication between client and Hanko API.
'
schema:
$ref: '#/components/schemas/X-Auth-Token'
X-Session-Lifetime:
description: 'Contains the seconds until the session expires.
'
schema:
$ref: '#/components/schemas/X-Session-Lifetime'
Set-Cookie:
description: 'Contains the JSON Web Token (JWT) that must be provided to protected endpoints.
Cookie attributes (e.g. domain) can be set via [configuration](https://github.com/teamhanko/hanko/blob/main/backend/docs/Config.md#hanko-backend-config) option `session.cookie`.
'
schema:
$ref: '#/components/schemas/CookieSession'
content:
application/json:
schema:
$ref: '#/components/schemas/WebauthnLoginResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/InternalServerError'
/webauthn/registration/initialize:
post:
summary: Initialize WebAuthn registration
description: '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](https://github.com/github/webauthn-json) library).
'
operationId: webauthnRegInit
tags:
- webauthn
deprecated: true
security:
- CookieAuth: []
- BearerTokenAuth: []
responses:
'200':
description: Challenge
content:
application/json:
schema:
$ref: '#/components/schemas/CredentialCreationOptions'
'400':
$ref: '#/components/responses/BadRequest'
'422':
$ref: '#/components/responses/unprocessableEntity'
'500':
$ref: '#/components/responses/InternalServerError'
/webauthn/registration/finalize:
post:
summary: Finalize WebAuthn registration
description: '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](https://github.com/github/webauthn-json) library).
'
operationId: webauthnRegFinal
tags:
- webauthn
deprecated: true
security:
- CookieAuth: []
- BearerTokenAuth: []
requestBody:
description: Challenge response
content:
application/json:
schema:
$ref: '#/components/schemas/PublicKeyCredentialAttestationResponse'
responses:
'200':
description: Successful registration
content:
application/json:
schema:
type: object
properties:
credential_id:
description: The ID of the created credential
type: string
format: base64
user_id:
description: The ID of the user on whose behalf a credential was created
allOf:
- $ref: '#/components/schemas/UUID4'
'400':
$ref: '#/components/responses/BadRequest'
'500':
$ref: '#/components/responses/InternalServerError'
/webauthn/credentials:
get:
summary: Get a list of WebAuthn credentials
description: 'Returns a list of WebAuthn credentials assigned to the current user.
'
operationId: listCredentials
tags:
- webauthn
deprecated: true
security:
- CookieAuth: []
- BearerTokenAuth: []
responses:
'200':
description: A list of WebAuthn credentials assigned to the current user
content:
application/json:
schema:
$ref: '#/components/schemas/WebauthnCredentials'
'401':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/InternalServerError'
/webauthn/credentials/{id}:
patch:
summary: Updates a WebAuthn credential
description: 'Updates the specified WebAuthn credential. Only credentials assigned to the current user can be updated.
'
operationId: updateCredential
tags:
- webauthn
deprecated: true
security:
- CookieAuth: []
- BearerTokenAuth: []
parameters:
- name: id
in: path
description: ID of the WebAuthn credential
required: true
schema:
$ref: '#/components/schemas/UUID4'
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
description: A new credential name. Has no technical meaning, only serves as an identification aid for the user.
type: string
responses:
'200':
description: Credential updated successfully
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalServerError'
delete:
summary: Deletes a WebAuthn credential
description: 'Deletes the specified WebAuthn credential.
'
operationId: deleteCredential
tags:
- webauthn
deprecated: true
security:
- CookieAuth: []
- BearerTokenAuth: []
parameters:
- name: id
in: path
description: ID of the WebAuthn credential
required: true
schema:
$ref: '#/components/schemas/UUID4'
responses:
'201':
description: Credential updated successfully
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalServerError'
components:
schemas:
CookieSession:
type: string
description: Value `<JWT>` is a [JSON Web Token](https://www.rfc-editor.org/rfc/rfc7519.html)
example: hanko=<JWT>; Path=/; HttpOnly
PublicKeyCredentialAssertionResponse:
description: WebAuthn API response to a navigator.credentials.get() call
type: object
properties:
id:
type: string
example: _18q6IjW09tiM4NSbsZjocUtGx00Muv5mN6LZCelCMDD...
rawId:
type: string
example: _18q6IjW09tiM4NSbsZjocUtGx00Muv5mN6LZCelCMDD...
type:
type: string
enum:
- public-key
example: public-key
response:
type: object
properties:
clientDataJson:
type: string
format: base64url
example: eyJ0eXBlIjoid2ViYXV0aG4uZ2V0IiwiY2hhbGxlbmdl...
authenticatorData:
type: string
format: base64url
example: SZYN5YgOjGh0NBcPZHZgW4_krrmihjLHmVzzuoMdl2MF...
signature:
type: string
format: base64url
example: MEQCIHe2RXqh6dyZw1LNXgeTTxljCV_qK2ydQjp02CiF...
userHandle:
type: string
format: base64url
example: rpe_EkgaSEeZG0TwzZyZJw
CredentialCreationOptions:
description: Options for credential creation with the WebAuthn API
externalDocs:
url: https://www.w3.org/TR/webauthn-2/#dictionary-makecredentialoptions
type: object
properties:
publicKey:
type: object
properties:
rp:
type: object
properties:
name:
type: string
example: Hanko Authentication Service
id:
type: string
example: localhost
user:
type: object
properties:
id:
type: string
example: pPQT9rwJRD7gVncsnCDNyN
name:
type: string
example: user@example.com
displayName:
type: string
example: user@example.com
challenge:
type: string
format: base64url
example: 7qmkJUXR0dOFnsW48evX3qKdCzlGjvvqAAvMDN+KTN0=
pubKeyCredParams:
type: array
items:
type: object
properties:
type:
type: string
enum:
- public-key
alg:
type: number
example:
- type: public-key
alg: -7
timeout:
type: integer
format: int64
example: 60000
authenticatorSelection:
type: object
properties:
authenticatorAttachment:
type: string
enum:
- platform
- cross-platform
example: platform
requireResidentKey:
type: boolean
example: true
residentKey:
type: string
enum:
- discouraged
- preferred
- required
example: preferred
userVerification:
type: string
enum:
- discouraged
- preferred
- required
example: required
attestation:
type: string
enum:
- none
- indirect
- direct
- enterprise
example: none
PublicKeyCredentialAttestationResponse:
description: WebAuthn API response to a navigator.credentials.create() call
type: object
properties:
id:
type: string
example: _18q6IjW09tiM4NSbsZjocUtGx00Muv5mN6LZCelCMDD...
rawId:
type: string
example: _18q6IjW09tiM4NSbsZjocUtGx00Muv5mN6LZCelCMDD...
type:
type: string
enum:
- public-key
example: public-key
response:
type: object
properties:
clientDataJson:
type: string
format: base64url
example: eyJ0eXBlIjoid2ViYXV0aG4uZ2V0IiwiY2hhbGxlbmdl...
attestationObject:
type: string
format: base64url
example: o2NmbXRkbm9uZWdhdHRTdG10oGhhdXRoRGF0YVjfSZYN...
transports:
type: array
items:
type: string
enum:
- usb
- nfc
- ble
- internal
example: internal
X-Auth-Token:
description: 'Enable via [configuration](https://github.com/teamhanko/hanko/blob/main/backend/docs/Config.md#hanko-backend-config) option `session.enable_auth_token_header`
for purposes of cross-domain communication between client and Hanko API.
'
type: string
format: JWT
externalDocs:
url: https://github.com/teamhanko/hanko/blob/main/backend/docs/Config.md#hanko-backend-config
X-Session-Lifetime:
description: 'Contains the seconds until the session expires.
'
type: number
CredentialRequestOptions:
description: Options for assertion generation with the WebAuthn API
externalDocs:
url: https://www.w3.org/TR/webauthn-2/#dictionary-assertion-options
type: object
properties:
publicKey:
type: object
properties:
challenge:
type: string
format: base64url
example: qgOI+0KpGnl9NOqaT6dfsYvi96R87LgpErnvePeOgSU=
timeout:
type: integer
format: int64
example: 60000
rpId:
type: string
example: localhost
allowCredentials:
type: array
items:
type: object
properties:
type:
type: string
enum:
- public-key
example: public-key
id:
type: string
format: base64url
example: Mepptysj5ZZrTlg0qiLbsZ068OtQMeGVAikVy2n1hvvG...
userVerification:
type: string
enum:
- required
- preferred
- discouraged
example: required
Error:
type: object
required:
- code
- message
properties:
code:
type: integer
format: int32
message:
type: string
WebauthnLoginResponse:
description: Response after a successful login with webauthn
type: object
properties:
credential_id:
type: string
format: base64url
user_id:
type: string
format: uuid4
WebauthnCredential:
type: object
properties:
aaguid:
type: string
format: uuid
attestation_type:
type: string
enum:
- none
- packed
- tpm
- android-key
- android-safetynet
- fido-u2f
- apple
backup_eligible:
type: boolean
backup_state:
type: boolean
created_at:
type: string
format: date-time
id:
type: string
format: uuid
last_used_at:
type: string
format: date-time
mfa_only:
type: boolean
name:
type: string
public-key:
type: string
transports:
type: array
items:
type: string
enum:
- ble
- internal
- nfc
- usb
UUID4:
type: string
format: uuid4
example: c339547d-e17d-4ba7-8a1d-b3d5a4d17c1c
WebauthnCredentials:
description: A list of WebAuthn credentials
type: array
items:
$ref: '#/components/schemas/WebauthnCredential'
example:
- id: 5333cc5b-c7c4-48cf-8248-9c184ac72b65
name: iCloud
public_key: pQECYyagASFYIBblARCP_at3cmprjzQN1lJ...
attestation_type: packed
aaguid: 01020304-0506-0708-0102-030405060708
last_used_at: '2026-02-24T21:40:36.26936Z'
created_at: '2026-02-24T21:40:36.26936Z'
transports:
- internal
backup_eligible: true
backup_state: true
mfa_only: false
- id: f826013e-e7e3-4366-a6d8-9359effc8cdd
name: Yubikey Bio
public_key: aNMEEyadASFYIBblARCP_at3cmp4gg3zQN1lJ...
attestation_type: packed
aaguid: 90636e1f-ef82-43bf-bdcf-5255f139d12f
last_used_at: '2026-02-24T21:40:36.26936Z'
created_at: '2026-02-24T21:40:36.26936Z'
transports:
- usb
backup_eligible: true
backup_state: false
mfa_only: true
responses:
BadRequest:
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 400
message: Bad Request
NotFound:
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 404
message: Not found
unprocessableEntity:
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 422
message: Unprocessable Entity
jwks:
description: Example response
content:
application/json:
schema:
type: object
properties:
keys:
type: array
minItems: 1
uniqueItems: true
items:
type: object
additionalProperties: false
properties:
alg:
type: string
readOnly: true
example:
- RS256
e:
type: string
readOnly: true
example:
- AAAA
kid:
type: string
format: uuid
readOnly: true
example:
- 483b2499-1ed7-4325-94e3-97e8118ceee9
kty:
type: string
readOnly: true
example:
- RSA
n:
type: string
readOnly: true
use:
type: string
readOnly: true
example:
- sig
minProperties: 6
minProperties: 1
Unauthorized:
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 401
message: Unauthorized
InternalServerError:
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 500
message: Internal Server Error
parameters:
tenant_id:
name: tenant_id
in: path
description: UUID of the tenant
required: true
schema:
type: string
format: uuid
minLength: 36
maxLength: 36
example:
- 1f496bcd-49da-4839-a02f-7ce681ccb488
securitySchemes:
BearerApiKeyAuth:
description: Bearer authentication header of the form `Bearer <token>`, where `<token>` is your API key. Must only be used when using Hanko Cloud.
type: http
scheme: bearer
bearerFormat: API Key
externalDocs:
description: More about Hanko
url: https://github.com/teamhanko/hanko