Hanko User Management API
The User Management API from Hanko — 5 operation(s) for user management.
OpenAPI Specification
openapi: 3.0.3
info:
version: 1.2.0
title: Hanko Admin Audit Logs User Management 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: User Management
paths:
/users:
get:
summary: Get a list of users
security:
- BearerApiKeyAuth: []
operationId: listUsers
tags:
- User Management
parameters:
- in: query
name: page
schema:
type: integer
default: 1
description: The page which should be returned
- in: query
name: per_page
schema:
type: integer
default: 20
description: The number of returned items
- in: query
name: user_id
schema:
allOf:
- $ref: '#/components/schemas/UUID4'
example: c339547d-e17d-4ba7-8a1d-b3d5a4d17c1c
description: 'A single ID or a comma-separated list of IDs. Only users with the specified IDs are included in the result.
'
- in: query
name: email
schema:
type: string
format: email
example: example@example.com
description: Only users with the specified email are included
- in: query
name: sort_direction
schema:
type: string
enum:
- asc
- desc
description: The sort direction of the returned list (always sorted by created_at)
responses:
'200':
description: Details about users
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/UserBase'
headers:
X-Total-Count:
$ref: '#/components/headers/X-Total-Count'
Link:
$ref: '#/components/headers/Link'
'400':
$ref: '#/components/responses/BadRequest'
'500':
$ref: '#/components/responses/InternalServerError'
post:
summary: Create a new user
security:
- BearerApiKeyAuth: []
operationId: createUser
tags:
- User Management
requestBody:
content:
application/json:
schema:
type: object
properties:
id:
description: The ID of the new user
allOf:
- $ref: '#/components/schemas/UUID4'
emails:
description: The email addresses of the new user
type: array
items:
type: object
properties:
address:
type: string
is_primary:
type: boolean
is_verified:
type: boolean
required:
- address
- is_primary
username:
description: The username of the new user
type: string
created_at:
description: Time of creation of the user
type: string
format: date-time
required:
- emails
responses:
'200':
description: Details of the newly created user
content:
application/json:
schema:
$ref: '#/components/schemas/User'
'400':
$ref: '#/components/responses/BadRequest'
'409':
$ref: '#/components/responses/Conflict'
'500':
$ref: '#/components/responses/InternalServerError'
/users/{id}:
delete:
summary: Delete a user by ID
security:
- BearerApiKeyAuth: []
operationId: deleteUser
tags:
- User Management
parameters:
- name: id
in: path
description: ID of the user
required: true
schema:
$ref: '#/components/schemas/UUID4'
responses:
'204':
description: Deleted
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalServerError'
get:
summary: Get a user by ID
security:
- BearerApiKeyAuth: []
operationId: getUser
tags:
- User Management
parameters:
- name: id
in: path
description: ID of the user
required: true
schema:
$ref: '#/components/schemas/UUID4'
responses:
'200':
description: Details about the user
content:
application/json:
schema:
$ref: '#/components/schemas/User'
'400':
$ref: '#/components/responses/BadRequest'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalServerError'
patch:
summary: Update a user by ID
description: 'Updates a subset of user-level attributes.
Other sub-resources (e.g. emails, credentials) are managed via dedicated endpoints and are not updated via this endpoint.
'
security:
- BearerApiKeyAuth: []
operationId: patchUser
tags:
- User Management
parameters:
- name: id
in: path
description: ID of the user
required: true
schema:
$ref: '#/components/schemas/UUID4'
requestBody:
$ref: '#/components/requestBodies/PatchUser'
responses:
'200':
description: Details about the user
content:
application/json:
schema:
$ref: '#/components/schemas/User'
'400':
$ref: '#/components/responses/BadRequest'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalServerError'
/user:
post:
deprecated: true
summary: Get user details by email
description: Retrieve details for user corresponding to the given `email`.
operationId: getUserId
tags:
- User Management
requestBody:
content:
application/json:
schema:
type: object
properties:
email:
type: string
format: email
responses:
'200':
description: User
content:
application/json:
schema:
type: object
properties:
id:
$ref: '#/components/schemas/UUID4'
email_id:
$ref: '#/components/schemas/UUID4'
verified:
type: boolean
has_webauthn_credential:
type: boolean
'400':
$ref: '#/components/responses/BadRequest'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalServerError'
delete:
deprecated: true
summary: Deletes the current user
description: Used to delete the current user. Note that `config.account.allow_deletion` must be set to true.
operationId: deleteUser
tags:
- User Management
security:
- CookieAuth: []
- BearerTokenAuth: []
responses:
'204':
description: The user has been deleted
'401':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/InternalServerError'
/me:
get:
summary: Get the current user
description: Retrieve data for the current user (i.e. the subject of the JWT given in a cookie or as a bearer token).
operationId: IsUserAuthorized
tags:
- User Management
security:
- CookieAuth: []
- BearerTokenAuth: []
responses:
'200':
$ref: '#/components/responses/MeResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/InternalServerError'
/logout:
post:
summary: Log out the current user
description: Logs out the user by removing the authorization cookie.
operationId: logout
tags:
- User Management
security:
- CookieAuth: []
- BearerTokenAuth: []
responses:
'204':
description: The user has been logged out
'401':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/InternalServerError'
components:
headers:
Link:
schema:
type: string
description: Web Linking as described in RFC5988
example: <http://localhost:8001/resource?page=1&per_page=10>; rel="first",<http://localhost:8001/resource?page=16&per_page=10>; rel="last",<http://localhost:8001/resource?page=6&per_page=10>; rel="next",<http://localhost:8001/resource?page=4&per_page=10>; rel="prev"
X-Total-Count:
schema:
type: string
description: The total count of the requested resource considering query parameter
example: 1234
schemas:
Emails:
type: array
items:
type: object
properties:
id:
description: The ID of the email address
allOf:
- $ref: '#/components/schemas/UUID4'
address:
description: The email address
type: string
format: email
is_verified:
description: Indicated the email has been verified.
type: boolean
is_primary:
description: Indicates it's the primary email address.
type: boolean
identity:
allOf:
- $ref: '#/components/schemas/Identity_2'
- deprecated: true
- description: Deprecated, use `user.identities` instead.
identities:
allOf:
- $ref: '#/components/schemas/Identities_2'
- deprecated: true
- description: Deprecated, use `user.identities` instead.
example:
- id: 5333cc5b-c7c4-48cf-8248-9c184ac72b65
address: john.doe@example.com
is_verified: true
is_primary: false
OTP:
type: object
properties:
id:
type: string
format: uuid
created_at:
type: string
format: date-time
required:
- id
- created_at
Identity_2:
type: object
description: Representation of a user's third party connection/identity.
properties:
id:
type: string
description: The ID of the user at the provider
identity_id:
type: string
description: The identity's ID
format: uuid4
provider:
type: string
description: 'Contains the display name of the provider, if available. Otherwise contains the provider ID.
'
UserMetadata:
description: User metadata
type: object
properties:
public_metadata:
type: object
additionalProperties: {}
example:
role: admin
private_metadata:
type: object
additionalProperties: {}
example:
internal_id: e6c19cfb-09a2-41e5-a908-e33193b7ca0a
unsafe_metadata:
type: object
additionalProperties: {}
example:
birthday: '2025-05-12'
Identities:
description: A list of third party provider identities
type: array
items:
$ref: '#/components/schemas/Identity'
Identities_2:
description: The user's third party connections/identities.
type: array
items:
$ref: '#/components/schemas/Identity_2'
Username:
description: The username of the user
type: object
properties:
id:
allOf:
- $ref: '#/components/schemas/UUID4'
description: The ID of the username
example: 8cbed467-554b-4d17-b23f-bce1b4f1db92
created_at:
description: Time of creation of the username
type: string
format: date-time
updated_at:
description: Time of last update of the username
type: string
format: date-time
username:
description: The username of the user
type: string
example: john_doe_123
Email:
type: object
required:
- id
- address
- is_verified
- is_primary
- created_at
- updated_at
properties:
id:
description: The ID of the email
allOf:
- $ref: '#/components/schemas/UUID4'
example: 802df042-1ac2-496d-af81-6ace729ed055
address:
description: The email address
type: string
format: email
is_verified:
description: Indicated the email has been verified.
type: boolean
is_primary:
description: Indicates it's the primary email address.
type: boolean
created_at:
description: Time of creation of the email
type: string
format: date-time
updated_at:
description: Time of last update of the email
type: string
format: date-time
Password:
description: The password credential of a user
type: object
properties:
id:
allOf:
- $ref: '#/components/schemas/UUID4'
description: The ID of the password credential
example: 28a7206b-e789-435a-b87c-108e034135c2
created_at:
description: Time of creation of the password credential
type: string
format: date-time
updated_at:
description: Time of last update of the password credential
type: string
format: date-time
WebAuthnCredential:
type: object
required:
- id
- public_key
- attestation_type
- aaguid
- created_at
- backup_eligible
- backup_state
- mfa_only
properties:
id:
description: The ID of the credential
allOf:
- $ref: '#/components/schemas/UUID4'
example: f9bebc04-b894-4018-bdb8-8b520a532fef
name:
description: A name that the user choose
type: string
public_key:
description: The public key of the credential
type: string
attestation_type:
description: The attestation type the credential was registered with
type: string
aaguid:
description: The AAGUID of the authenticator the credentials was created on
type: string
transports:
description: The ways the authenticator is connected
type: array
items:
type: string
created_at:
description: Time of creation of the credential
type: string
format: date-time
last_used_at:
description: The time when the credential was last used
type: string
format: date-time
backup_eligible:
description: Indicates if the credential can be backed up
type: boolean
backup_state:
description: Indicates if the credential is backed up
type: boolean
mfa_only:
description: Indicates if the credential can only be used as a MFA credential
type: boolean
Username_2:
description: The representation of a username of the user
type: object
properties:
id:
description: The ID of the user
allOf:
- $ref: '#/components/schemas/UUID4'
created_at:
description: Time of creation of the username
type: string
format: date-time
updated_at:
description: Time of last update of the username
type: string
format: date-time
username:
description: The username of the user
type: string
example: john_doe
Error:
type: object
required:
- code
- message
properties:
code:
type: integer
format: int32
message:
type: string
UserBase_2:
type: object
properties:
id:
description: The ID of the user. Deprecated, use `user_id` instead.
deprecated: true
allOf:
- $ref: '#/components/schemas/UUID4'
user_id:
description: The ID of the user
allOf:
- $ref: '#/components/schemas/UUID4'
emails:
$ref: '#/components/schemas/Emails'
created_at:
description: Time of creation of the the user
type: string
format: date-time
updated_at:
description: Time of last update of the user
type: string
format: date-time
passkeys:
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
security_keys:
type: array
items:
$ref: '#/components/schemas/WebauthnCredential'
example:
- 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
metadata:
$ref: '#/components/schemas/UserMetadata_2'
name:
type: string
given_name:
type: string
family_name:
type: string
picture:
type: string
format: uri
mfa_config:
type: object
properties:
auth_app_set_up:
type: boolean
totp_enabled:
type: boolean
security_key_enabled:
type: boolean
User:
allOf:
- $ref: '#/components/schemas/UserBase'
- type: object
properties:
otp:
$ref: '#/components/schemas/OTP'
password:
$ref: '#/components/schemas/Password'
identities:
$ref: '#/components/schemas/Identities'
metadata:
$ref: '#/components/schemas/UserMetadata'
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
Identity:
description: A third party provider identity
type: object
properties:
id:
allOf:
- $ref: '#/components/schemas/UUID4'
description: The ID of the identity
example: 77f8d594-9765-4891-ab2b-f31a797b531d
email_id:
allOf:
- $ref: '#/components/schemas/UUID4'
description: The ID of the email this identity is coupled with
example: d4095586-8318-4a40-a840-b4260496f85a
provider_id:
description: The user's third party provider account/user ID
type: string
provider_name:
description: The name of the third party provider this identity coupled with
type: string
created_at:
description: Time of creation of the password credential
type: string
format: date-time
updated_at:
description: Time of last update of the password credential
type: string
format: date-time
UserBase:
type: object
required:
- id
- created_at
- updated_at
properties:
id:
description: The ID of the user
allOf:
- $ref: '#/components/schemas/UUID4'
created_at:
description: Time of creation of the user
type: string
format: date-time
updated_at:
description: Time of last update of the user
type: string
format: date-time
webauthn_credentials:
description: List of registered Webauthn credentials
type: array
items:
$ref: '#/components/schemas/WebAuthnCredential'
emails:
description: List of emails associated to the user
type: array
items:
$ref: '#/components/schemas/Email'
username:
$ref: '#/components/schemas/Username'
UserMetadata_2:
description: The public and unsafe metadata of a user
type: object
properties:
public_metadata:
type: object
additionalProperties: true
example:
role: admin
unsafe_metadata:
type: object
additionalProperties: true
example:
birthday: '2025-05-12'
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
Conflict:
description: Conflict
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 409
message: Conflict
MeResponse:
description: Details for the current user
content:
application/json:
schema:
type: object
allOf:
- $ref: '#/components/schemas/UserBase_2'
- type: object
properties:
username:
$ref: '#/components/schemas/Username_2'
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
requestBodies:
PatchUser:
content:
application/json:
schema:
type: object
description: 'Patch payload for updating a user.
Omitted properties are not changed.
'
additionalProperties: false
properties:
username:
description: 'Set a new username for the user.
Send `null` to remove the username.
'
type: string
nullable: true
example: john_doe_123
name:
description: 'Set a new username for the user.
Send `null` to remove the name.
'
type: string
nullable: true
example: John Doe
given_name:
description: 'Set a new given name for the user.
Send `null` to remove the given_name.
'
type: string
nullable: true
example: John
family_name:
description: 'Set a new family name for the user.
Send `null` to remove the family_name.
'
type: string
nullable: true
example: Doe
picture:
description: 'Set a new picture for the user. Must be a public URL accessible
via HTTP/HTTPS. Must not contain credentials.
Send `null` to remove the picture.
'
type: string
nullable: true
maxLength: 2048
format: uri
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