openapi: 3.0.0
info:
  version: 1.2.0
  title: Hanko Public 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
externalDocs:
  description: More about Hanko
  url: https://github.com/teamhanko/hanko
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.
paths:
  /:
    get:
      summary: Status page
      description: >-
        Return information about the API status. Returns a 500 if there are
        issues with database connectivity.
      operationId: status
      tags:
        - Status
      responses:
        '200':
          description: API is running
          content:
            text/html:
              schema:
                type: string
        '500':
          description: API is not functioning properly
          content:
            text/html:
              schema:
                type: string
  /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'
  /password/login:
    post:
      summary: Do password login
      description: >
        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](https://github.com/teamhanko/hanko/blob/main/backend/docs/Config.md#hanko-backend-config)
        option `passwords.enabled`.
      operationId: passwordLogin
      tags:
        - Password
      deprecated: true
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                user_id:
                  description: The ID of the user to perform a password login for
                  allOf:
                    - $ref: '#/components/schemas/UUID4'
                password:
                  $ref: '#/components/schemas/Password'
              required:
                - user_id
                - password
      responses:
        '200':
          description: Successful password 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'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /password:
    put:
      summary: Create/Set a password
      description: >
        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](https://github.com/teamhanko/hanko/blob/main/backend/docs/Config.md#hanko-backend-config)
        option `passwords.enabled`.
      operationId: password
      tags:
        - Password
      deprecated: true
      security:
        - CookieAuth: []
        - BearerTokenAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                user_id:
                  description: The ID of the user to create/set a password for
                  allOf:
                    - $ref: '#/components/schemas/UUID4'
                password:
                  $ref: '#/components/schemas/Password'
              required:
                - user_id
                - password
      responses:
        '200':
          description: Successful password update
        '201':
          description: Successful password creation
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /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'
  /.well-known/jwks.json:
    get:
      summary: Get JSON Web Key Set
      description: >
        Retrieve a [JSON Web Key
        Set](https://www.rfc-editor.org/rfc/rfc7517#section-5) (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.
      operationId: getJwks
      tags:
        - .well-known
      responses:
        '200':
          description: JSON Web Key Set
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JSONWebKeySet'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /.well-known/config:
    get:
      deprecated: true
      summary: Get public Hanko configuration
      description: >
        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).
      operationId: getConfig
      tags:
        - .well-known
      responses:
        '200':
          description: Hanko configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HankoConfiguration'
  /saml/provider:
    get:
      deprecated: true
      summary: Get a SAML provider
      description: Get a SAML service provider config for a provided domain.
      operationId: get-saml-provider
      tags:
        - SAML
      parameters:
        - name: domain
          in: query
          description: >-
            Fully qualified domain name for which a SAML service provider is
            registered
          required: true
          schema:
            type: string
            format: hostname
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  enabled:
                    type: boolean
                    readOnly: true
                    default: true
                  name:
                    type: string
                    readOnly: true
                    example: MySamlProvier
                  domain:
                    type: string
                    format: hostname
                    readOnly: true
                    example: text.example
                  metadata_url:
                    type: string
                    format: uri
                    readOnly: true
                    example: http://idp-metadata.url
                  skip_email_verification:
                    type: boolean
                    readOnly: true
                    default: false
                  attribute_map:
                    type: object
                    additionalProperties: false
                    properties:
                      name:
                        type: string
                      family_name:
                        type: string
                      given_name:
                        type: string
                      middle_name:
                        type: string
                      nickname:
                        type: string
                      preferred_username:
                        type: string
                      profile:
                        type: string
                      picture:
                        type: string
                      website:
                        type: string
                      gender:
                        type: string
                      birthdate:
                        type: string
                      zone_info:
                        type: string
                      locale:
                        type: string
                      updated_at:
                        type: string
                      email:
                        type: string
                      email_verified:
                        type: string
                      phone:
                        type: string
                      phone_verified:
                        type: string
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          description: Not Found
  /saml/metadata:
    get:
      summary: Get SAML Metadata
      description: Download SAML service provider metadata or public certificate.
      operationId: get-saml-metadata
      tags:
        - SAML
      parameters:
        - name: domain
          in: query
          description: >-
            Fully qualified domain name to which a SAML service provider is
            registered
          required: true
          schema:
            type: string
        - name: cert_only
          in: query
          description: Toggle to download the SAML service provider public certificate
          schema:
            type: boolean
      responses:
        '200':
          description: OK
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          description: Not found
  /saml/callback:
    post:
      summary: SAML identity provider callback
      description: >-
        Callback endpoint called by the identity provider after successful
        login.
      operationId: post-saml-callback
      tags:
        - SAML
      requestBody:
        description: SAML Identity Provider Response
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                RelayState:
                  type: string
                SAMLResponse:
                  type: string
      responses:
        '302':
          description: Found
          headers:
            Set-Cookie:
              schema:
                type: string
              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`.
            X-Auth-Token:
              schema:
                type: string
              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.
        '307':
          description: Temporary Redirect
          headers:
            Location:
              schema:
                type: string
              description: >-
                On error, redirect to the `saml.default_redirect_url` set in the
                backend-configuration. Error details are provided in the
                location URL in the form of `error` and `error_description`query
                params.
  /sessions/validate:
    get:
      tags:
        - Session Management
      summary: Validate a session
      description: >
        Validate a session using a cookie header or an authorization header.

        This is a passive check that does not update the session's internal last
        activity timestamp.
      security:
        - CookieAuth: []
        - BearerTokenAuth: []
      responses:
        '200':
          $ref: '#/components/responses/ValidateSessionResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      tags:
        - Session Management
      summary: Validate a session
      description: >
        Validate a session using a session token in a request body.

        This endpoint updates the session's internal last activity timestamp.
        This extends the idle timeout window

        if configured).
      requestBody:
        content:
          application/json:
            schema:
              properties:
                session_token:
                  description: The session token (JWT) to validate
                  type: string
                  format: JWT
              required:
                - session_token
      responses:
        '200':
          $ref: '#/components/responses/ValidateSessionResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /thirdparty/auth:
    get:
      deprecated: true
      summary: Initialize third party login
      description: >
        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.
      operationId: thirdPartyAuth
      tags:
        - Third Party
      parameters:
        - in: query
          name: provider
          required: true
          schema:
            type: string
            enum:
              - google
              - github
          description: >
            The name of the third party provider to log in with. Only providers
            enabled in the

            [configuration](https://github.com/teamhanko/hanko/blob/main/backend/docs/Config.md#hanko-backend-config)

            via the `thirdparty.providers` option can be used. Requesting an
            unsupported provider results in a

            redirect with error details in the location query.
        - in: query
          name: redirect_to
          required: true
          schema:
            type: string
            format: base64url
          description: >
            Base64url encoded string representing the URL the

            [`/callback`](#tag/Third-Party/operation/thirdPartyCallback)
            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](https://github.com/teamhanko/hanko/blob/main/backend/docs/Config.md#hanko-backend-config)

            through the `third_party.allowed_redirect_urls`.
      responses:
        '307':
          description: Redirect to third party provider
          headers:
            Location:
              schema:
                type: string
              description: >
                Redirect to the third party provider on success. On error,
                redirects to the `Referer`. If `Referer` is

                not present, redirects to the `third_party.error_redirect_url`
                set in the backend

                [configuration](https://github.com/teamhanko/hanko/blob/main/backend/docs/Config.md#hanko-backend-config).

                Error details are provided in the location URL in the form of
                `error` and `error_description`

                query params.
  /thirdparty/callback:
    get:
      summary: Third party provider callback
      description: >-
        Callback endpoint called by the third party provider after successful
        login.
      operationId: thirdPartyCallback
      tags:
        - Third Party
      parameters:
        - in: query
          name: code
          schema:
            type: string
          description: >
            The authorization code that can be exchanged for an access token and
            to retrieve user provider data
        - in: query
          name: state
          required: true
          schema:
            type: string
          description: The state
        - in: query
          name: error
          schema:
            type: string
          description: |
            An error returned from the third party provider
        - in: query
          name: error_description
          schema:
            type: string
          description: The description of the error that occurred (if any)
      responses:
        '307':
          description: >-
            Redirect to requested redirect URL or to configured site redirect
            URL
          headers:
            Location:
              schema:
                type: string
              description: >
                Redirect to the URL requested via `redirect_to` query parameter
                during third party

                provider login via
                [`/auth`](#tag/Third-Party/operation/thirdPartyAuth) endpoint on
                success. On error,

                redirect to the `third_party.error_redirect_url` set in the
                backend

                [configuration](https://github.com/teamhanko/hanko/blob/main/backend/docs/Config.md#hanko-backend-config).

                Error details are provided in the location URL in the form of
                `error` and `error_description`

                query params.
            X-Auth-Token:
              description: >
                Present only on successful callback and 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'
            Set-Cookie:
              description: >
                Present only on successful callback. 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'
  /token:
    post:
      deprecated: true
      summary: Exchange one time token for session
      description: >
        Provide a one time token (e.g. obtained through the [thirdparty
        callback](#tag/Third-Party/operation/thirdPartyCallback)) to retrieve a
        session JWT as cookie

        and/or via `X-Auth-Token` header.
      operationId: token
      tags:
        - Token
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                value:
                  type: string
                  format: base64url
      responses:
        '200':
          description: Successful token exchange
          headers:
            X-Auth-Token:
              description: >
                Present only on successful exchange and 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: >
                Present only on successful exchange. 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:
                type: object
                properties:
                  user_id:
                    description: >-
                      The ID of the user on whose behalf the token was
                      exchanged.
                    allOf:
                      - $ref: '#/components/schemas/UUID4'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/unprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /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'
  /users:
    post:
      deprecated: true
      summary: Create a user
      description: >-
        Used to create a new user. To disable this endpoint,
        `config.account.allow_signup` must be set to false.
      operationId: createUser
      tags:
        - User Management
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  format: email
              required:
                - email
      responses:
        '200':
          description: Details about the created user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateUserResponseObject'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /users/{id}:
    get:
      summary: Get a user by ID
      operationId: listUser
      deprecated: true
      tags:
        - User Management
      security:
        - CookieAuth: []
        - BearerTokenAuth: []
      parameters:
        - name: id
          in: path
          description: ID of the user
          required: true
          schema:
            $ref: '#/components/schemas/UUID4'
      responses:
        '200':
          $ref: '#/components/responses/GetUserByIdResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /emails:
    get:
      summary: Get a list of emails of the current user.
      operationId: listEmails
      tags:
        - Email Management
      deprecated: true
      security:
        - CookieAuth: []
        - BearerTokenAuth: []
      responses:
        '200':
          description: A list of emails assigned to the current user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Emails'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      deprecated: true
      summary: Add a new email address to the current user.
      operationId: createEmail
      tags:
        - Email Management
      security:
        - CookieAuth: []
        - BearerTokenAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                address:
                  type: string
                  format: email
              required:
                - address
      responses:
        '201':
          description: Email successfully added
        '400':
          $ref: '#/components/responses/BadRequest'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /emails/{id}/set_primary:
    post:
      deprecated: true
      summary: Marks the email address as primary email
      operationId: setPrimaryEmail
      tags:
        - Email Management
      security:
        - CookieAuth: []
        - BearerTokenAuth: []
      parameters:
        - name: id
          in: path
          description: ID of the email address
          required: true
          schema:
            $ref: '#/components/schemas/UUID4'
      responses:
        '201':
          description: Email has been set as primary
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /emails/{id}:
    delete:
      deprecated: true
      summary: Delete an email address
      operationId: deleteEmail
      tags:
        - Email Management
      security:
        - CookieAuth: []
        - BearerTokenAuth: []
      parameters:
        - name: id
          in: path
          description: ID of the email address
          required: true
          schema:
            $ref: '#/components/schemas/UUID4'
      responses:
        '201':
          description: Email has been deleted
        '401':
          $ref: '#/components/responses/Unauthorized'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  responses:
    MeResponse:
      description: Details for the current user
      content:
        application/json:
          schema:
            type: object
            allOf:
              - $ref: '#/components/schemas/UserBase'
              - type: object
                properties:
                  username:
                    $ref: '#/components/schemas/Username'
    GetUserByIdResponse:
      description: Details for a user retrieved by ID
      content:
        application/json:
          schema:
            type: object
            allOf:
              - $ref: '#/components/schemas/UserBase'
              - type: object
                properties:
                  email:
                    description: The email address of the user
                    type: string
                    format: email
                  username:
                    description: The username of the user
                    type: string
                  webauthn_credentials:
                    $ref: '#/components/schemas/WebauthnCredentials'
    ValidateSessionResponse:
      description: Session validation response
      content:
        application/json:
          schema:
            properties:
              is_valid:
                description: Indicates whether the session is valid or not
                type: boolean
              expiration_time:
                description: >-
                  Date-time indicating the expiration of the session.
                  Deprecated, please use `claims.expiration` instead.
                type: string
                format: date-time
                deprecated: true
              user_id:
                description: >-
                  The ID of the user the session is associated with. Deprecated,
                  please use `claims.subject` instead.
                type: string
                format: uuid4
                deprecated: true
              claims:
                $ref: '#/components/schemas/JWTClaims'
              idle_expires_at:
                description: >
                  Timestamp (in UTC) indicating when the session will expire due
                  to inactivity, assuming no further activity occurs before this
                  time.

                  Only present when idle timeout is configured. The value is
                  capped to the JWT expiration time.
                type: string
                format: date-time
            required:
              - isValid
    BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: 400
            message: Bad Request
    Conflict:
      description: Conflict
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: 409
            message: Conflict
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: 403
            message: Forbidden
    Gone:
      description: Gone
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: 410
            message: Gone
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: 500
            message: Internal Server Error
    NotFound:
      description: Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: 404
            message: Not found
    RequestTimeOut:
      description: Request Timeout
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: 408
            message: Request Timeout
    TooManyRequests:
      description: Too Many Requests
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: 429
            message: Too Many Requests
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: 401
            message: Unauthorized
    unprocessableEntity:
      description: Unprocessable Entity
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: 422
            message: Unprocessable Entity
  schemas:
    HankoConfiguration:
      description: Public backend configuration options
      type: object
      externalDocs:
        description: Hanko Configuration
        url: https://github.com/teamhanko/hanko/blob/main/backend/docs/Config.md
      properties:
        emails:
          description: Controls the behavior regarding email addresses.
          type: object
          properties:
            require_verification:
              description: >-
                Require email verification after account registration and
                prevent signing in with unverified email addresses. Also, email
                addresses can only be marked as primary when they have been
                verified before.
              type: boolean
        password:
          description: Configuration options concerning passwords
          type: object
          properties:
            enabled:
              description: Indicates whether passwords are enabled or not
              type: boolean
            min_password_length:
              description: Describes the minimum password length
              type: number
              example: 8
        account:
          description: Controls the behavior regarding user account.
          type: object
          properties:
            allow_deletion:
              description: Indicates the user account can be deleted by the current user.
              type: boolean
            allow_signup:
              description: Indicates users are able to create new accounts.
              type: boolean
    CookieSession:
      type: string
      description: >-
        Value `<JWT>` is a [JSON Web
        Token](https://www.rfc-editor.org/rfc/rfc7519.html)
      example: hanko=<JWT>; Path=/; HttpOnly
    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
    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
    Identity:
      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.
    Identities:
      description: The user's third party connections/identities.
      type: array
      items:
        $ref: '#/components/schemas/Identity'
    JSONWebKey:
      type: object
      externalDocs:
        description: RFC7517 - JSON Web Key (JWK)
        url: https://datatracker.ietf.org/doc/html/rfc7517
      properties:
        alg:
          type: string
          example: RS256
          externalDocs:
            description: RFC7517 - JSON Web Key (JWK) - Section 4.4
            url: https://www.rfc-editor.org/rfc/rfc7517#section-4.4
        e:
          type: string
          format: base64url
          example: AQAB
          externalDocs:
            description: RFC7518 - JSON Web Algorithms (JWA) - Section 6.3.1.2
            url: https://www.rfc-editor.org/rfc/rfc7518#section-6.3.1.2
        kid:
          type: string
          example: d6ff37d7-e3d1-4432-ab80-b64faf55ae36
          externalDocs:
            description: RFC7517 - JSON Web Key (JWK) - Section 4.5
            url: https://www.rfc-editor.org/rfc/rfc7517#section-4.5
        kty:
          type: string
          example: RSA
          externalDocs:
            description: RFC7517 - JSON Web Key (JWK) - Section 4.1
            url: https://www.rfc-editor.org/rfc/rfc7517#section-4.1
        'n':
          type: string
          format: base64url
          example: vPFRUCRoxN3RygdJHR3S5BV-DDLw6n-7oUXtX0nr7Twl...
          externalDocs:
            description: RFC7518 - JSON Web Algorithms (JWA) - Section 6.3.1.1
            url: https://www.rfc-editor.org/rfc/rfc7518#section-6.3.1.1
        use:
          type: string
          example: sig
          externalDocs:
            description: RFC7517 - JSON Web Key (JWK) - Section 4.2
            url: https://www.rfc-editor.org/rfc/rfc7517#section-4.2
    JSONWebKeySet:
      type: object
      properties:
        keys:
          type: array
          items:
            $ref: '#/components/schemas/JSONWebKey'
          externalDocs:
            description: RFC7517 - JSON Web Key (JWK) - Section 5.1
            url: https://www.rfc-editor.org/rfc/rfc7517#section-5.1
      externalDocs:
        description: RFC7517 - JSON Web Key (JWK) - Section 5
        url: https://www.rfc-editor.org/rfc/rfc7517#section-5
    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
    Password:
      description: >
        The actual password, its `minLength` defaults to 8 but

        can be
        [configured](https://github.com/teamhanko/hanko/blob/main/backend/docs/Config.md#hanko-backend-config)

        through the `password.min_password_length` option.
      type: string
      minLength: 8
      maxLength: 72
      example: 9UnCBEx924a45P7p
    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
    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
    GetUserResponse:
      type: object
      properties:
        id:
          description: The ID of the user
          allOf:
            - $ref: '#/components/schemas/UUID4'
        email:
          description: The email address of the user
          type: string
          format: email
        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
        verified:
          description: Indicates whether the user's email address was verified
          type: boolean
        webauthn_credentials:
          description: List of registered Webauthn credentials
          type: array
          items:
            type: object
            properties:
              id:
                description: The ID of the Webauthn credential
                type: string
                format: base64url
                example: Meprtysj5ZZrTlg0qiLbsZ168OtQMeGVAikVy2n1hvvG...
    CreateUserResponseObject:
      type: object
      properties:
        user_id:
          description: The ID of the newly created user
          allOf:
            - $ref: '#/components/schemas/UUID4'
        email_id:
          description: The ID of the newly created email address
          allOf:
            - $ref: '#/components/schemas/UUID4'
    JWTClaims:
      type: object
      description: The claims extracted from a JWT.
      properties:
        subject:
          description: The unique identifier of the token's subject.
          allOf:
            - $ref: '#/components/schemas/UUID4'
        issued_at:
          description: The timestamp indicating when the token was issued.
          type: string
          format: date-time
        expiration:
          description: The timestamp indicating when the token will expire.
          type: string
          format: date-time
        audience:
          description: The intended audience of the token.
          type: array
          items:
            type: string
        issuer:
          description: The entity that issued the token.
          type: string
        email:
          description: >-
            Data about the email address associated with the token's subject, if
            available.
          type: object
          properties:
            address:
              description: The actual email address.
              type: string
              format: email
            is_primary:
              description: Indicates whether the email address is the primary address.
              type: boolean
            is_verified:
              description: Indicates whether the email address is verified.
              type: boolean
        session_id:
          description: The unique identifier for the session associated with this token.
          allOf:
            - $ref: '#/components/schemas/UUID4'
        amr:
          description: >-
            Authentication Method References, JSON array of strings that are
            identifiers for authentication methods used in the authentication.
          type: array
          items:
            type: string
            enum:
              - pwd
              - passkey
              - otp
              - ext:<provider>
              - totp
              - security_key
            description: >
              - `pwd` => password

              - `passkey` => passkey

              - `otp` => email passcode

              - `ext:<provider>` => thirdparty provider, where <provider> is the
              internal provider ID, e.g. `ext:microsoft`

              - `totp` => 2FA authenticator app

              - `security_key` => 2FA security key
      required:
        - subject
        - expiration
        - session_id
    UserBase:
      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'
        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
    UserMetadata:
      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'
    Username:
      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
    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'
              - deprecated: true
              - description: Deprecated, use `user.identities` instead.
          identities:
            allOf:
              - $ref: '#/components/schemas/Identities'
              - 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
    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
    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
    WebauthnLoginResponse:
      description: Response after a successful login with webauthn
      type: object
      properties:
        credential_id:
          type: string
          format: base64url
        user_id:
          type: string
          format: uuid4
    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
    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