public.yaml

openapi: 3.0.0
info:
  version: '0.9.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: 'localhost:8000'
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
      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: false
      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
      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
      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
      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
      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
      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
      security:
        - CookieAuth: [ ]
        - BearerTokenAuth: [ ]
      responses:
        '200':
          description: 'Challenge'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CredentialCreationOptions'
        '400':
          $ref: '#/components/responses/BadRequest'
        '422':
          $ref: '#/components/responses/Unprocessable Entity'
        '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
      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
      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
      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
                  required: false
      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
      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:
      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'
  /thirdparty/auth:
    get:
      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:
      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/Unprocessable Entity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /user:
    post:
      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:
      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 ID'
      description: Retrieve the user ID for the current user (i.e. the subject of the JWT).
      operationId: IsUserAuthorized
      tags:
        - User Management
      security:
        - CookieAuth: [ ]
        - BearerTokenAuth: [ ]
      responses:
        '200':
          description: 'User'
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    description: The id of the current user
                    allOf:
                      - $ref: '#/components/schemas/UUID4'
        '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:
      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/CreateUserResponse'
        '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
      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'
        '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
      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:
      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:
      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:
      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'
  /saml/provider:
    get:
      summary: Get a SAML Provider - Only available when SAML in config is enabled
      description: Get a SAML service provider config for a provided domain.
      operationId: get-saml-provider
      tags:
        - Enterprise Features
      parameters:
        - name: domain
          in: query
          description: full qualified domain name to 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: The Name
                  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
      servers:
        - url: 'localhost:8000'
  /saml/metadata:
    get:
      summary: Get SAML Metadata - Only available when SAML in config is enabled
      description: Downloads SAML service Provider Metadata or Public Certificate
      operationId: get-saml-metadata
      tags:
        - Enterprise Features
      parameters:
        - name: domain
          in: query
          description: full 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
      servers:
        - url: 'localhost:8000'
  /saml/auth:
    get:
      summary: Initialize SAML login - Only available when SAML in config is enabled
      description: |
        Initialize an SAML login with an identity provider by redirecting to
        the specified domain login URL to retrieve a SAML Assertion.
      operationId: get-saml-auth
      tags:
        - Enterprise Features
      parameters:
        - name: domain
          in: query
          description: full qualified domain name to which a SAML service provider is registered
          required: true
          schema:
            type: string
        - name: redirect_to
          in: query
          description: |
            Base64url encoded string representing the URL the
            [`/callback`](#tag/Enterprise-Features/operation/post-saml-callback) eventually redirects to after successful login
            with the saml identity 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 `saml.allowed_redirect_urls`.
          required: true
          schema:
            type: string
            format: base64url
      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 `saml.default_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.
      servers:
        - url: 'localhost:8000'
  /saml/callback:
    post:
      summary: SAML identity provider callback - Only available when SAML in config is enabled
      description: Callback endpoint called by the identity provicer after successful login.
      operationId: post-saml-callback
      tags:
        - Enterprise Features
      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.'
      servers:
        - url: 'localhost:8000'
components:
  responses:
    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
    Unprocessable Entity:
      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: number
              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: number
              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
    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...
    CreateUserResponse:
      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'
    User:
      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
        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...
    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
      example:
        - id: 5333cc5b-c7c4-48cf-8248-9c184ac72b65
          address: john.doe@example.com
          is_verified: true
          is_primary: false
    WebauthnCredentials:
      description: 'A list of WebAuthn credentials'
      type: array
      items:
        type: object
        properties:
          id:
            description: The ID of the Webauthn credential
            type: string
            format: base64url
            example: Meprtysj5ZZrTlg0qiLbsZ168OtQMeGVAikVy2n1hvvG...
          name:
            description: The name of the credential. Can be updated by the user.
            type: string
            required: false
          public_key:
            description: The public key assigned to the credential.
            type: boolean
          aaguid:
            description: The AAGUID of the authenticator.
            type: boolean
          transports:
            description: Transports which may be used by the authenticator.
            type: array
            items:
              type: string
              enum:
                - usb
                - nfc
                - ble
                - internal
          last_used_at:
            description: The time when the credential was used last
            type: string
            required: false
            format: date-time
          created_at:
            description: Time of creation of the credential
            type: string
            format: date-time
      example:
        - id: 5333cc5b-c7c4-48cf-8248-9c184ac72b65
          name: "iCloud"
          public_key: "pQECYyagASFYIBblARCP_at3cmprjzQN1lJ..."
          aaguid: "adce0002-35bc-c60a-648b-0b25f1f05503"
          transports:
            - internal
          created_at: "022-12-06T21:26:06.535106Z"
    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