Hanko Passcode API
The Passcode API from Hanko — 2 operation(s) for passcode.
OpenAPI Specification
openapi: 3.0.3
info:
version: 1.2.0
title: Hanko Admin Audit Logs Passcode 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: 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:
schemas:
X-Session-Lifetime:
description: 'Contains the seconds until the session expires.
'
type: number
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
Error:
type: object
required:
- code
- message
properties:
code:
type: integer
format: int32
message:
type: string
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
CookieSession:
type: string
description: Value `<JWT>` is a [JSON Web Token](https://www.rfc-editor.org/rfc/rfc7519.html)
example: hanko=<JWT>; Path=/; HttpOnly
responses:
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
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
RequestTimeOut:
description: Request Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 408
message: Request Timeout
InternalServerError:
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 500
message: Internal Server Error
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