Hanko Passcode API
The Passcode API from Hanko — 2 operation(s) for passcode.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/hanko-passcode-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
version: 1.2.0
title: Hanko Public Passcode API
description: '## Introduction
This is the OpenAPI specification for the [Hanko Public API](https://github.com/teamhanko/hanko/blob/main/backend/README.md#basic-usage).
## Authentication
The API uses [JSON Web Tokens](https://www.rfc-editor.org/rfc/rfc7519.html) (JWTs) for authentication.
JWTs are verified using [JSON Web Keys](https://www.rfc-editor.org/rfc/rfc7517) (JWK).
JWKs can be [configured](https://github.com/teamhanko/hanko/blob/main/backend/docs/Config.md#all-available-config-options)
through the `secrets.keys` options. The API also publishes public cryptographic keys as a
[JWK set](https://www.rfc-editor.org/rfc/rfc7517#section-2) 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](https://github.com/teamhanko/hanko/blob/main/backend/docs/Config.md#all-available-config-options)
for public endpoints via the `server.public.cors` options.
---
'
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
variables:
tenant_id:
default: ''
description: The (UU)ID of a tenant. Replace the default value with your tenant ID.
tags:
- name: Passcode
paths:
/passcode/login/initialize:
post:
summary: Initialize passcode login
description: '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.
'
operationId: passcodeInit
tags:
- Passcode
deprecated: true
requestBody:
content:
application/json:
schema:
type: object
properties:
user_id:
description: The ID of the user
allOf:
- $ref: '#/components/schemas/UUID4'
email_id:
description: The ID of the email address
allOf:
- $ref: '#/components/schemas/UUID4'
required:
- user_id
responses:
'200':
description: Successful passcode login initialization
content:
application/json:
schema:
$ref: '#/components/schemas/Passcode'
'400':
$ref: '#/components/responses/BadRequest'
'500':
$ref: '#/components/responses/InternalServerError'
/passcode/login/finalize:
post:
summary: Finalize passcode login
description: '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`.
'
operationId: passcodeFinal
tags:
- Passcode
deprecated: true
requestBody:
content:
application/json:
schema:
type: object
properties:
id:
description: The ID of the passcode
allOf:
- $ref: '#/components/schemas/UUID4'
code:
type: string
minLength: 6
maxLength: 6
description: 'The actual passcode from the email sent to the user during initialization,
a string of 6 decimal digits
'
example: '897481'
responses:
'200':
description: Successful passcode login finalization
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/Passcode'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'408':
$ref: '#/components/responses/RequestTimeOut'
'410':
$ref: '#/components/responses/Gone'
'500':
$ref: '#/components/responses/InternalServerError'
components:
responses:
RequestTimeOut:
description: Request Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 408
message: Request Timeout
BadRequest:
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 400
message: Bad Request
Gone:
description: Gone
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 410
message: Gone
Forbidden:
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 403
message: Forbidden
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
schemas:
Error:
type: object
required:
- code
- message
properties:
code:
type: integer
format: int32
message:
type: string
Passcode:
description: Representation of a passcode
type: object
properties:
id:
description: The ID of the passcode
allOf:
- $ref: '#/components/schemas/UUID4'
ttl:
type: integer
description: Lifespan of a passcode in seconds
example: 300
created_at:
description: Time of creation of the passcode
type: string
format: date-time
UUID4:
type: string
format: uuid4
example: c339547d-e17d-4ba7-8a1d-b3d5a4d17c1c
CookieSession:
type: string
description: Value `<JWT>` is a [JSON Web Token](https://www.rfc-editor.org/rfc/rfc7519.html)
example: hanko=<JWT>; Path=/; HttpOnly
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
securitySchemes:
CookieAuth:
type: apiKey
in: cookie
name: hanko
BearerTokenAuth:
type: http
scheme: bearer
bearerFormat: JWT
externalDocs:
description: More about Hanko
url: https://github.com/teamhanko/hanko