> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hanko.io/llms.txt
> Use this file to discover all available pages before exploring further.

> Initialize or advance a token exchange flow.

# Token exchange

This flow is only available if SAML is enabled.


## OpenAPI

````yaml post /token_exchange
openapi: 3.0.3
info:
  title: Flow API
  description: Flow API
  version: 1.2.0
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.
security: []
paths:
  /token_exchange:
    post:
      tags:
        - flow
      summary: Token exchange
      description: |
        Initialize or advance a token exchange flow. 

        This flow is only available if SAML is enabled.
      parameters:
        - $ref: '#/components/parameters/ActionParam'
        - $ref: '#/components/parameters/LanguageParam'
      requestBody:
        $ref: '#/components/requestBodies/TokenExchangeRequestBody'
      responses:
        '200':
          $ref: '#/components/responses/TokenExchangeFlowResponse'
        '400':
          $ref: '#/components/responses/LoginFlowResponseBadRequestError'
        '401':
          $ref: '#/components/responses/FlowResponseUnauthorizedError'
        '403':
          $ref: '#/components/responses/FlowResponseForbiddenError'
        '429':
          $ref: '#/components/responses/FlowResponseTooManyRequestsError'
        '500':
          $ref: '#/components/responses/FlowResponseInternalServerError'
components:
  parameters:
    ActionParam:
      in: query
      name: action
      description: >
        String of the format `{action_name}@{flow_id}`. Indicates the action to
        perform on the flow with the 

        given `flow_id`. Omitting the query parameter initializes a new flow.


        _Note for playground usage_: You can derive the value for this query
        parameter from the `action`'s `href` 

        property in a flow state response, e.g. for an `href` value of 

        `/login?action=register_client_capabilities%4015655672-41ca-48cc-afb1-90be77075764`
        the (non-URL-encoded) value

        would be
        `register_client_capabilities@15655672-41ca-48cc-afb1-90be77075764`.
      schema:
        type: string
        example: register_client_capabilities@15655672-41ca-48cc-afb1-90be77075764
    LanguageParam:
      in: header
      name: X-Language
      schema:
        type: string
        enum:
          - bn
          - de
          - en
          - fr
          - it
          - nl
          - pt-BR
          - zh
      description: >
        Used to internationalize outgoing emails (e.g. for email verification,
        recovery, etc.). 


        If email delivery by Hanko is enabled the values for supported languages
        are: 
          - "bn" (Bengali/Bangla)
          - "de" (German) 
          - "en" (English) 
          - "fr" (French) 
          - "it" (Italian) 
          - "nl" (Dutch)
          - "pt-BR" (Brazilian Portuguese), 
          - "zh" (Chinese)

        If email delivery by Hanko is disabled and a webhook has been configured
        for the `email.send` event, the

        JWT payload of the `token` contained in the response to the webhook
        endpoint contains a `language` claim that

        reflects the value originally passed as the header value.
  requestBodies:
    TokenExchangeRequestBody:
      description: TokenExchangeRequestBody
      content:
        application/json:
          schema:
            title: Token exchange request body
            type: object
            properties:
              input_data:
                oneOf:
                  - $ref: '#/components/schemas/InputDataExchangeToken'
                  - $ref: '#/components/schemas/InputDataVerifyPasscode'
                  - $ref: '#/components/schemas/InputDataUsernameSet'
              csrf_token:
                $ref: '#/components/schemas/CSRFToken'
            additionalProperties: false
  responses:
    TokenExchangeFlowResponse:
      description: TokenExchangeFlowResponse
      headers:
        X-Auth-Token:
          description: >
            Enable via configuration option `session.enable_auth_token_header`

            for purposes of cross-domain communication between client and Hanko
            API.


            Only present on the `success` state of the flow.
          schema:
            $ref: '#/components/schemas/X-Auth-Token'
        X-Session-Lifetime:
          description: |
            Contains the seconds until the session expires.

            Only present on the `success` state of the flow.
          schema:
            $ref: '#/components/schemas/X-Session-Lifetime'
        X-Session-Retention:
          description: >
            Serves as a hint at what type of cookie (session or persistent)
            should be created.


            Only present on the `success` state of the flow.
          schema:
            $ref: '#/components/schemas/X-Session-Retention'
        Set-Cookie:
          description: >
            Value `<JWT>` is a [JSON Web
            Token](https://www.rfc-editor.org/rfc/rfc7519.html)


            Only present on the `success` state of the flow.
          schema:
            $ref: '#/components/schemas/CookieSession'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/StatesTokenExchange'
    LoginFlowResponseBadRequestError:
      description: LoginFlowResponseBadRequestError
      content:
        application/json:
          schema:
            allOf:
              - oneOf:
                  - $ref: '#/components/schemas/StateLoginInit'
                  - $ref: '#/components/schemas/StateLoginPasskey'
                  - $ref: '#/components/schemas/StateLoginPassword'
                  - $ref: '#/components/schemas/StatePasscodeConfirmation'
                  - $ref: '#/components/schemas/StatePasswordCreation'
                  - $ref: '#/components/schemas/StateOnboardingEmail'
                  - $ref: '#/components/schemas/StateOnboardingCreatePasskey'
                  - $ref: >-
                      #/components/schemas/StateOnboardingVerifyPasskeyAttestation
                  - $ref: '#/components/schemas/StateOnboardingUsername'
                  - $ref: '#/components/schemas/StateThirdParty'
              - type: object
                properties:
                  status:
                    enum:
                      - 400
                  error:
                    $ref: '#/components/schemas/Error'
    FlowResponseUnauthorizedError:
      description: FlowResponseUnauthorizedError
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/StateError'
              - type: object
                properties:
                  status:
                    enum:
                      - 401
                  error:
                    allOf:
                      - $ref: '#/components/schemas/Error'
                      - example:
                          code: passcode_max_attempts_reached
                          message: The passcode was entered wrong too many times.
    FlowResponseForbiddenError:
      description: FlowResponseForbiddenError
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/StateError'
              - type: object
                properties:
                  status:
                    enum:
                      - 403
                  error:
                    allOf:
                      - $ref: '#/components/schemas/Error'
                      - example:
                          code: operation_not_permitted_error
                          message: The flow is not permitted.
    FlowResponseTooManyRequestsError:
      description: FlowResponseTooManyRequestsError
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/StateError'
              - type: object
                properties:
                  status:
                    enum:
                      - 429
                  payload:
                    $ref: '#/components/schemas/PayloadResendAfter'
                  error:
                    allOf:
                      - $ref: '#/components/schemas/Error'
                      - example:
                          code: rate_limit_exceeded
                          message: The rate limit has been exceeded.
    FlowResponseInternalServerError:
      description: FlowResponseInternalServerError
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/StateError'
              - type: object
                properties:
                  status:
                    enum:
                      - 500
                  error:
                    allOf:
                      - $ref: '#/components/schemas/Error'
                      - example:
                          code: technical_error
                          message: Something went wrong.
  schemas:
    InputDataExchangeToken:
      title: ExchangeToken
      description: Input data for the `exchange_token` action.
      type: object
      properties:
        token:
          type: string
      required:
        - token
      additionalProperties: false
    InputDataVerifyPasscode:
      title: VerifyPasscode
      description: Input data for the `verify_passcode` action.
      type: object
      properties:
        code:
          type: string
          minLength: 6
          maxLength: 6
      required:
        - code
      additionalProperties: false
    InputDataUsernameSet:
      title: UsernameSet
      description: Input data for the `username_set` action.
      type: object
      properties:
        username:
          type: string
      required:
        - provider
      additionalProperties: false
    CSRFToken:
      description: >
        Not required on flow initialization, i.e. on requests without an
        `action`

        query parameter.


        Required on all other requests performing an action, i.e. on requests
        that use an `action` 

        query parameter. Should be the `csrf_token` value from the most recent
        flow state response.
      type: string
      example: qvcZt29spXYO77Y9IaxxN4MzLnmbjozl
    X-Auth-Token:
      type: string
      format: JWT
    X-Session-Lifetime:
      type: number
    X-Session-Retention:
      type: string
      enum:
        - session
        - persistent
    CookieSession:
      description: >
        Value `<JWT>` is a [JSON Web
        Token](https://www.rfc-editor.org/rfc/rfc7519.html)


        Only present on the `success` state of the flow.
      type: string
      example: hanko=<JWT>; Path=/; HttpOnly
    StatesTokenExchange:
      oneOf:
        - $ref: '#/components/schemas/StatePasscodeConfirmation'
        - $ref: '#/components/schemas/StateOnboardingUsername'
        - $ref: '#/components/schemas/StateThirdParty'
        - $ref: '#/components/schemas/StateSuccessTokenExchange'
      discriminator:
        propertyName: name
        mapping:
          thirdparty:
            $ref: '#/components/schemas/StateThirdParty'
          passcode_confirmation:
            $ref: '#/components/schemas/StatePasscodeConfirmation'
          onboarding_username:
            $ref: '#/components/schemas/StateOnboardingUsername'
          success:
            $ref: '#/components/schemas/StateSuccessTokenExchange'
    StateLoginInit:
      title: LoginInit
      allOf:
        - $ref: '#/components/schemas/StateBase'
        - type: object
          properties:
            actions:
              $ref: '#/components/schemas/ActionsLoginInit'
            name:
              type: string
              enum:
                - login_init
            payload:
              $ref: '#/components/schemas/PayloadRequestOptions'
            status:
              type: integer
              enum:
                - 200
    StateLoginPasskey:
      title: LoginPasskey
      type: object
      allOf:
        - $ref: '#/components/schemas/StateBase'
        - properties:
            actions:
              $ref: '#/components/schemas/ActionsLoginPasskey'
            name:
              type: string
              enum:
                - login_passkey
            payload:
              $ref: '#/components/schemas/PayloadRequestOptions'
            status:
              type: integer
              enum:
                - 200
    StateLoginPassword:
      title: LoginPassword
      type: object
      allOf:
        - $ref: '#/components/schemas/StateBase'
        - properties:
            actions:
              $ref: '#/components/schemas/ActionsLoginPassword'
            name:
              type: string
              enum:
                - login_password
            status:
              type: integer
              enum:
                - 200
    StatePasscodeConfirmation:
      title: PasscodeConfirmation
      type: object
      allOf:
        - $ref: '#/components/schemas/StateBase'
        - properties:
            actions:
              $ref: '#/components/schemas/ActionsPasscodeConfirmation'
            name:
              type: string
              enum:
                - passcode_confirmation
            status:
              type: integer
              enum:
                - 200
    StatePasswordCreation:
      title: PasswordCreation
      type: object
      allOf:
        - $ref: '#/components/schemas/StateBase'
        - properties:
            actions:
              $ref: '#/components/schemas/ActionsPasswordCreation'
            name:
              type: string
              enum:
                - password_creation
            status:
              type: integer
              enum:
                - 200
    StateOnboardingEmail:
      title: OnboardingEmail
      type: object
      allOf:
        - $ref: '#/components/schemas/StateBase'
        - properties:
            actions:
              $ref: '#/components/schemas/ActionsOnboardingEmail'
            name:
              type: string
              enum:
                - onboarding_email
            payload:
              type: object
            status:
              type: integer
              enum:
                - 200
    StateOnboardingCreatePasskey:
      title: OnboardingCreatePasskey
      type: object
      allOf:
        - $ref: '#/components/schemas/StateBase'
        - properties:
            actions:
              $ref: '#/components/schemas/ActionsOnboardingCreatePasskey'
            name:
              type: string
              enum:
                - onboarding_create_passkey
            payload:
              type: object
            status:
              type: integer
              enum:
                - 200
    StateOnboardingVerifyPasskeyAttestation:
      title: OnboardingVerifyPasskeyAttestation
      type: object
      allOf:
        - $ref: '#/components/schemas/StateBase'
        - properties:
            actions:
              $ref: '#/components/schemas/ActionsOnboardingVerifyPasskeyAttestation'
            name:
              type: string
              enum:
                - onboarding_verify_passkey_attestation
            payload:
              $ref: '#/components/schemas/PayloadCreationOptions'
            status:
              type: integer
              enum:
                - 200
    StateOnboardingUsername:
      title: OnboardingUsername
      type: object
      allOf:
        - $ref: '#/components/schemas/StateBase'
        - properties:
            actions:
              $ref: '#/components/schemas/ActionsOnboardingUsername'
            name:
              type: string
              enum:
                - onboarding_username
            payload:
              type: object
            status:
              type: integer
              enum:
                - 200
    StateThirdParty:
      title: ThirdParty
      type: object
      allOf:
        - $ref: '#/components/schemas/StateBase'
        - properties:
            actions:
              $ref: '#/components/schemas/ActionsThirdParty'
            name:
              type: string
              enum:
                - thirdparty
            payload:
              $ref: '#/components/schemas/PayloadThirdParty'
            status:
              type: integer
              enum:
                - 200
    Error:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
        cause:
          type: string
    StateError:
      title: Error
      type: object
      allOf:
        - $ref: '#/components/schemas/StateBase'
        - properties:
            name:
              type: string
              enum:
                - error
            payload:
              type: object
            status:
              type: integer
    PayloadResendAfter:
      description: Returned with a flow response when the request rate limit was exceeded.
      type: object
      properties:
        resend_after:
          description: >
            Indicates the amount of seconds required to pass in order to be able
            to send another request.
          type: integer
          example: 60
    StateSuccessTokenExchange:
      title: Success
      type: object
      allOf:
        - $ref: '#/components/schemas/StateSuccess'
        - type: object
          properties:
            payload:
              allOf:
                - $ref: '#/components/schemas/PayloadProfileData'
                - type: object
                  properties:
                    claims:
                      $ref: '#/components/schemas/Claims'
    StateBase:
      type: object
      properties:
        actions:
          description: >
            List of actions that can be performed in the current flow state in
            order to advance the flow to the next 

            state.


            Depending on user details (e.g. presence or absence of credentials)
            or the tenant's configuration 

            some actions may or may not be present in the response.
          type: object
        name:
          description: The name of the flow state.
          type: string
        payload:
          description: >
            Additional data that can be used by the client (e.g. `user` or
            `sessions` data provided in the

            profile flow) or should/must be used as intermediary data in an out
            of band process to produce input data 

            for advancing the flow (e.g. the WebAuthn credential
            request/creation options that must be passed to the 

            Webauthn API to produce an assertion/attestation).
          type: object
        status:
          description: The HTTP response status code for this flow response.
          type: integer
        csrf_token:
          description: Token to prevent Cross-Site Request Forgeries.
          type: string
          example: HvUwWSfPgz7VnwiS8VMDpnhZ1wNwTNiV
        links:
          type: array
          items:
            $ref: '#/components/schemas/Link'
          nullable: true
          example: []
    ActionsLoginInit:
      type: object
      properties:
        continue_with_login_identifier:
          $ref: '#/components/schemas/ActionContinueWithLoginIdentifier'
        webauthn_generate_request_options:
          $ref: '#/components/schemas/ActionWebauthnGenerateRequestOptions'
        webauthn_verify_assertion_response:
          $ref: '#/components/schemas/ActionWebauthnVerifyAssertionResponse'
        thirdparty_oauth:
          $ref: '#/components/schemas/ActionThirdPartyOauth'
        remember_me:
          $ref: '#/components/schemas/ActionRememberMe'
    PayloadRequestOptions:
      type: object
      properties:
        request_options:
          $ref: '#/components/schemas/CredentialRequestOptions'
      required:
        - request_options
    ActionsLoginPasskey:
      type: object
      properties:
        webauthn_verify_assertion_response:
          $ref: '#/components/schemas/ActionWebauthnVerifyAssertionResponse'
        back:
          $ref: '#/components/schemas/ActionBack'
    ActionsLoginPassword:
      type: object
      properties:
        password_login:
          $ref: '#/components/schemas/ActionPasswordLogin'
        continue_to_passcode_confirmation_recovery:
          $ref: '#/components/schemas/ActionContinueToPasscodeConfirmationRecovery'
        back:
          $ref: '#/components/schemas/ActionBack'
    ActionsPasscodeConfirmation:
      type: object
      properties:
        verify_passcode:
          $ref: '#/components/schemas/ActionVerifyPasscode'
        resend_passcode:
          $ref: '#/components/schemas/ActionResendPasscode'
        back:
          $ref: '#/components/schemas/ActionBack'
    ActionsPasswordCreation:
      type: object
      properties:
        register_password:
          $ref: '#/components/schemas/ActionRegisterPassword'
        skip:
          $ref: '#/components/schemas/ActionSkip'
        back:
          $ref: '#/components/schemas/ActionBack'
    ActionsOnboardingEmail:
      type: object
      properties:
        email_address_set:
          $ref: '#/components/schemas/ActionEmailAddressSet'
        skip:
          $ref: '#/components/schemas/ActionSkip'
    ActionsOnboardingCreatePasskey:
      type: object
      properties:
        webauthn_generate_creation_options:
          $ref: '#/components/schemas/ActionWebauthnGenerateCreationOptions'
        skip:
          $ref: '#/components/schemas/ActionSkip'
        back:
          $ref: '#/components/schemas/ActionBack'
    ActionsOnboardingVerifyPasskeyAttestation:
      type: object
      properties:
        webauthn_verify_attestation_response:
          type: object
          properties:
            action:
              enum:
                - webauthn_verify_attestation_response
            inputs:
              $ref: '#/components/schemas/InputsWebauthnVerifyAttestationResponse'
        back:
          $ref: '#/components/schemas/ActionBack'
    PayloadCreationOptions:
      type: object
      properties:
        creation_options:
          $ref: '#/components/schemas/CredentialCreationOptions'
      required:
        - creation_options
    ActionsOnboardingUsername:
      type: object
      properties:
        username_set:
          type: object
          properties:
            action:
              enum:
                - username_set
            inputs:
              $ref: '#/components/schemas/InputsUsernameSet'
        skip:
          $ref: '#/components/schemas/ActionSkip'
    ActionsThirdParty:
      type: object
      properties:
        exchange_token:
          $ref: '#/components/schemas/ActionExchangeToken'
        back:
          $ref: '#/components/schemas/ActionBack'
    PayloadThirdParty:
      type: object
      properties:
        redirect_url:
          type: string
          format: uri
      required:
        - redirect_url
    StateSuccess:
      title: Success
      type: object
      allOf:
        - $ref: '#/components/schemas/StateBase'
        - properties:
            name:
              type: string
              enum:
                - success
            payload:
              $ref: '#/components/schemas/PayloadProfileData'
            status:
              type: integer
              enum:
                - 200
    PayloadProfileData:
      type: object
      properties:
        user:
          $ref: '#/components/schemas/ProfileDataUser'
    Claims:
      description: >-
        Contains the claims of a user as they appear in the payload of session
        JWTs.
      type: object
      properties:
        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
        subject:
          type: string
          format: uuid4
        issued_at:
          type: string
          format: date-time
        audience:
          type: array
          items:
            type: string
        issuer:
          type: string
        email:
          type: object
          properties:
            address:
              type: string
            is_verified:
              type: boolean
            is_primary:
              type: boolean
      additionalProperties:
        description: >-
          Any additional claims defined through templates for customizing the
          session JWT
    Link:
      type: object
      properties:
        name:
          description: The name of the link.
          type: string
        href:
          description: The destination of the link.
          type: string
          format: uri
        category:
          description: The category of the link.
          type: string
        target:
          description: The target of the link.
          type: string
          enum:
            - _self
            - _blank
            - _parent
            - _top
    ActionContinueWithLoginIdentifier:
      description: Provide a login identifier (email or username).
      allOf:
        - $ref: '#/components/schemas/Action'
        - type: object
          properties:
            action:
              enum:
                - continue_with_login_identifier
            inputs:
              $ref: '#/components/schemas/InputsContinueWithLoginIdentifier'
    ActionWebauthnGenerateRequestOptions:
      description: Generate passkey request options for authenticating with a passkey.
      allOf:
        - $ref: '#/components/schemas/Action'
        - type: object
          properties:
            action:
              enum:
                - webauthn_generate_request_options
    ActionWebauthnVerifyAssertionResponse:
      description: Verify an assertion response to complete a passkey authentication.
      allOf:
        - $ref: '#/components/schemas/Action'
        - type: object
          properties:
            action:
              enum:
                - webauthn_verify_assertion_response
            inputs:
              $ref: '#/components/schemas/InputsWebauthnVerifyAssertionResponse'
    ActionThirdPartyOauth:
      description: >
        Initialize a third party sign-up/sign-in by specifying the `provider`
        (it must be enabled and configured at the 

        tenant) to use and the  URL to redirect to (`redirect_to`) after
        successful authentication with the provider. 


        A `redirect_url` to the selected provider is placed in the `payload` of
        the next state (`thirdparty`).
      allOf:
        - $ref: '#/components/schemas/Action'
        - type: object
          properties:
            action:
              enum:
                - thirdparty_oauth
            inputs:
              $ref: '#/components/schemas/InputsThirdPartyOauth'
    ActionRememberMe:
      description: >
        This action determines whether a session cookie or a persistent cookie
        is issued on flow success. 


        - If the `remember_me` input is set to `true`, the flow response on flow
        success contains a `Set-Cookie` header

        with a persistent cookie and an `X-Session-Retention` header with a
        `persistent` value.

        - If the `remember_me` input is set to `false`, the flow response on
        flow success contains a `Set-Cookie` header

        with a session cookie and an `X-Session-Retention` header with a
        `session` value.


        The action is only present if the tenant's cookie retention type is set
        to 'prompt'.
      allOf:
        - $ref: '#/components/schemas/Action'
        - type: object
          properties:
            action:
              enum:
                - remember_me
            inputs:
              $ref: '#/components/schemas/InputsRememberMe'
    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
    ActionBack:
      description: Go back to the previous state.
      allOf:
        - $ref: '#/components/schemas/Action'
        - type: object
          properties:
            action:
              enum:
                - back
    ActionPasswordLogin:
      description: Authenticate with a password.
      allOf:
        - $ref: '#/components/schemas/Action'
        - type: object
          properties:
            action:
              enum:
                - password_login
            inputs:
              $ref: '#/components/schemas/InputsPasswordLogin'
    ActionContinueToPasscodeConfirmationRecovery:
      description: Continue to the `passcode_confirmation` state.
      allOf:
        - $ref: '#/components/schemas/Action'
        - type: object
          properties:
            action:
              enum:
                - continue_to_passcode_confirmation_recovery
    ActionVerifyPasscode:
      description: Verify a passcode.
      allOf:
        - $ref: '#/components/schemas/Action'
        - type: object
          properties:
            action:
              enum:
                - verify_passcode
            inputs:
              $ref: '#/components/schemas/InputsVerifyPasscode'
    ActionResendPasscode:
      description: Resend a passcode.
      allOf:
        - $ref: '#/components/schemas/Action'
        - type: object
          properties:
            action:
              enum:
                - resend_passcode
    ActionRegisterPassword:
      description: Register a password.
      allOf:
        - $ref: '#/components/schemas/Action'
        - type: object
          properties:
            action:
              enum:
                - register_password
            inputs:
              $ref: '#/components/schemas/InputsRegisterPassword'
    ActionSkip:
      description: Skip to the next state.
      allOf:
        - $ref: '#/components/schemas/Action'
        - type: object
          properties:
            action:
              enum:
                - skip
    ActionEmailAddressSet:
      description: Set an email address.
      allOf:
        - $ref: '#/components/schemas/Action'
        - type: object
          properties:
            action:
              enum:
                - email_address_set
            inputs:
              $ref: '#/components/schemas/InputsEmailAddressSet'
    ActionWebauthnGenerateCreationOptions:
      description: Generate passkey creation options for registering a passkey.
      allOf:
        - $ref: '#/components/schemas/Action'
        - type: object
          properties:
            action:
              enum:
                - webauthn_generate_creation_options
    InputsWebauthnVerifyAttestationResponse:
      type: object
      properties:
        public_key:
          $ref: '#/components/schemas/InputPublicKey'
      required:
        - public_key
    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
    InputsUsernameSet:
      type: object
      properties:
        username:
          $ref: '#/components/schemas/InputUsername'
      required:
        - username
    ActionExchangeToken:
      description: >-
        Exchange a one time token after a third party authentication for a
        session token.
      allOf:
        - $ref: '#/components/schemas/Action'
        - type: object
          properties:
            action:
              enum:
                - exchange_token
            inputs:
              $ref: '#/components/schemas/InputsExchangeToken'
    ProfileDataUser:
      description: Data pertaining to the user associated with the current session.
      type: object
      properties:
        user_id:
          type: string
          format: uuid
        passkeys:
          type: array
          items:
            $ref: '#/components/schemas/WebauthnCredential'
        security_keys:
          type: array
          items:
            $ref: '#/components/schemas/WebauthnCredential'
        emails:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                format: uuid
              address:
                type: string
                format: email
              is_primary:
                type: boolean
              is_verified:
                type: boolean
              identity:
                deprecated: true
                description: Deprecated. See `identities` instead.
                type: object
                properties:
                  id:
                    type: string
                    description: Contains the ID of the user at the provider.
                  provider:
                    type: string
                    description: >
                      Contains the display name of the provider, if available.
                      Otherwise contains the provider ID.
              identities:
                deprecated: true
                description: Deprecated. See top-level `identities` instead.
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                      description: ID of the user at the provider
                    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:
            type: object
            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.
        metadata:
          type: object
          properties:
            public_metadata:
              type: object
              additionalProperties: {}
            unsafe_metadata:
              type: object
              additionalProperties: {}
        mfa_config:
          type: object
          properties:
            auth_app_set_up:
              type: boolean
              description: >-
                Indicates whether the user has set up an authenticator app for
                2FA.
            totp_enabled:
              type: boolean
              description: >
                Indicates whether 2FA via authenticator app is enabled on this
                tenant. 


                To check whether a user has set up an authenticator app for 2FA,
                see
                [`payload.user.mfa_config.app_auth_set_up`](#response-one-of-1-payload-user-mfa-config-app-auth-set-up).
            security_keys_enabled:
              type: boolean
              description: >
                Indicates whether 2FA via security keys is enabled on this
                tenant.


                To check whether a user has enrolled security keys for 2FA, see
                [`payload.user.security_keys`](#response-one-of-1-payload-user-security-keys).
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        name:
          type: string
        given_name:
          type: string
        family_name:
          type: string
        picture:
          type: string
          format: uri
    Action:
      description: Action
      type: object
      properties:
        action:
          description: The name of the action.
          type: string
        href:
          description: The action target as a URL relative to the API tenant base URL.
          type: string
        description:
          description: The description for the action.
          type: string
        inputs:
          description: >
            The inputs for the action. 


            An input indicates that when making a request to perform an action,
            the `input_data` value of the 

            request body must contain a key with the given `name` value of the
            respective input. The corresponding 

            value for that key is specified by the remaining properties of the
            input.
          type: object
    InputsContinueWithLoginIdentifier:
      type: object
      properties:
        identifier:
          oneOf:
            - $ref: '#/components/schemas/InputIdentifier'
            - $ref: '#/components/schemas/InputEmail'
            - $ref: '#/components/schemas/InputUsername'
          discriminator:
            propertyName: name
    InputsWebauthnVerifyAssertionResponse:
      type: object
      properties:
        assertion_response:
          $ref: '#/components/schemas/InputAssertionResponse'
      required:
        - assertion_response
    InputsThirdPartyOauth:
      type: object
      properties:
        provider:
          $ref: '#/components/schemas/InputProvider'
        redirect_to:
          $ref: '#/components/schemas/InputRedirectTo'
        code_verifier:
          $ref: '#/components/schemas/InputCodeVerifier'
      required:
        - provider
        - redirect_to
    InputsRememberMe:
      type: object
      properties:
        remember_me:
          $ref: '#/components/schemas/InputRememberMe'
    InputsPasswordLogin:
      type: object
      properties:
        password:
          $ref: '#/components/schemas/InputPassword'
      required:
        - password
    InputsVerifyPasscode:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/InputCode'
      required:
        - code
    InputsRegisterPassword:
      type: object
      properties:
        new_password:
          $ref: '#/components/schemas/InputNewPassword'
    InputsEmailAddressSet:
      type: object
      properties:
        email:
          $ref: '#/components/schemas/InputEmail'
    InputPublicKey:
      allOf:
        - $ref: '#/components/schemas/Input'
        - type: object
          properties:
            name:
              enum:
                - public-key
            type:
              enum:
                - json
            required:
              default: true
            hidden:
              default: true
    InputUsername:
      title: Username
      allOf:
        - $ref: '#/components/schemas/Input'
        - type: object
          properties:
            name:
              enum:
                - username
            type:
              enum:
                - string
            min_length:
              type: number
              enum:
                - 3
            max_length:
              type: number
              enum:
                - 40
            required:
              default: false
            hidden:
              default: false
    InputsExchangeToken:
      type: object
      properties:
        token:
          $ref: '#/components/schemas/InputToken'
    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
        public-key:
          type: string
        transports:
          type: array
          items:
            type: string
            enum:
              - ble
              - internal
              - nfc
              - usb
    InputIdentifier:
      title: Identifier
      allOf:
        - $ref: '#/components/schemas/Input'
        - type: object
          properties:
            name:
              enum:
                - identifier
            type:
              enum:
                - string
            max_length:
              type: integer
              default: 255
            required:
              default: true
            hidden:
              default: false
    InputEmail:
      title: Email
      allOf:
        - $ref: '#/components/schemas/Input'
        - type: object
          properties:
            name:
              type: string
              enum:
                - email
            type:
              type: string
              enum:
                - email
            max_length:
              default: 120
            required:
              default: true
            hidden:
              default: false
    InputAssertionResponse:
      allOf:
        - $ref: '#/components/schemas/Input'
        - type: object
          properties:
            name:
              enum:
                - assertion_response
            type:
              enum:
                - json
    InputProvider:
      allOf:
        - $ref: '#/components/schemas/Input'
        - type: object
          properties:
            name:
              enum:
                - provider
            type:
              enum:
                - string
            value:
              type: string
            required:
              default: true
            hidden:
              default: true
            allowed_values:
              items:
                properties:
                  name:
                    description: A display name to use for the provider.
                  value:
                    $ref: '#/components/schemas/InputProviderAllowedValue'
    InputRedirectTo:
      allOf:
        - $ref: '#/components/schemas/Input'
        - type: object
          properties:
            name:
              enum:
                - redirect_to
            type:
              enum:
                - string
            required:
              default: true
            hidden:
              default: true
    InputCodeVerifier:
      allOf:
        - $ref: '#/components/schemas/Input'
        - type: object
          properties:
            name:
              enum:
                - code_verifier
            type:
              enum:
                - string
            required:
              default: false
            hidden:
              default: true
    InputRememberMe:
      allOf:
        - $ref: '#/components/schemas/Input'
        - type: object
          properties:
            name:
              enum:
                - remember_me
            type:
              enum:
                - boolean
            required:
              default: true
    InputPassword:
      allOf:
        - $ref: '#/components/schemas/Input'
        - type: object
          properties:
            name:
              enum:
                - password
            type:
              enum:
                - password
            min_length:
              default: 8
            required:
              default: true
            hidden:
              default: false
    InputCode:
      allOf:
        - $ref: '#/components/schemas/Input'
        - type: object
          properties:
            name:
              enum:
                - code
            type:
              enum:
                - string
            min_length:
              default: 6
            max_length:
              default: 6
            required:
              default: true
            hidden:
              default: false
    InputNewPassword:
      allOf:
        - $ref: '#/components/schemas/InputPassword'
        - type: object
          properties:
            name:
              type: string
              enum:
                - new_password
    Input:
      type: object
      properties:
        name:
          type: string
        type:
          type: string
        required:
          type: boolean
        min_length:
          type: integer
        max_length:
          type: integer
        hidden:
          type: boolean
        value:
          type: string
        allowed_values:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              value:
                $ref: '#/components/schemas/AnyValue'
    InputToken:
      allOf:
        - $ref: '#/components/schemas/Input'
        - type: object
          properties:
            name:
              enum:
                - token
            type:
              enum:
                - string
            required:
              default: true
            hidden:
              default: true
    InputProviderAllowedValue:
      type: string
      enum:
        - apple
        - discord
        - facebook
        - github
        - google
        - linkedin
        - microsoft
    AnyValue:
      description: Can be any value - string, number, boolean, array or object.

````