Token exchange

Initialize or advance a token exchange flow.

POST /token_exchange

Token exchange

cURL

curl --request POST \
  --url https://{tenant_id}.hanko.io/token_exchange \
  --header 'Content-Type: application/json' \
  --data '
{
  "input_data": {
    "token": "<string>"
  },
  "csrf_token": "qvcZt29spXYO77Y9IaxxN4MzLnmbjozl"
}
'

200

{
  "actions": {
    "verify_passcode": {
      "action": "verify_passcode",
      "href": "<string>",
      "description": "<string>",
      "inputs": {
        "code": {
          "name": "code",
          "type": "string",
          "required": true,
          "min_length": 6,
          "max_length": 6,
          "hidden": false,
          "value": "<string>",
          "allowed_values": [
            {
              "name": "<string>",
              "value": "<unknown>"
            }
          ]
        }
      }
    },
    "resend_passcode": {
      "action": "resend_passcode",
      "href": "<string>",
      "description": "<string>",
      "inputs": {}
    },
    "back": {
      "action": "back",
      "href": "<string>",
      "description": "<string>",
      "inputs": {}
    }
  },
  "name": "passcode_confirmation",
  "payload": {},
  "status": 200,
  "csrf_token": "HvUwWSfPgz7VnwiS8VMDpnhZ1wNwTNiV",
  "links": []
}

This flow is only available if SAML is enabled.

Headers

X-Language · enum<string>

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.

Available options: bn, de, en, fr, it, nl, pt-BR, zh

Query Parameters

action · string

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.

Example:

"register_client_capabilities@15655672-41ca-48cc-afb1-90be77075764"

Body

application/json

TokenExchangeRequestBody

input_data · ExchangeToken · object

Input data for the exchange_token action.

ExchangeToken

VerifyPasscode

UsernameSet

Show child attributes

csrf_token · string

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.

Example:

"qvcZt29spXYO77Y9IaxxN4MzLnmbjozl"

Response

200

application/json

TokenExchangeFlowResponse

PasscodeConfirmation

OnboardingUsername

ThirdParty

Success

actions · object

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.

Show child attributes

name · enum<string>

The name of the flow state.

Available options: passcode_confirmation

payload · object

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).

status · enum<integer>

The HTTP response status code for this flow response.

Available options: 200

csrf_token · string

Token to prevent Cross-Site Request Forgeries.

Example:

"HvUwWSfPgz7VnwiS8VMDpnhZ1wNwTNiV"

links · object[] | null

Show child attributes

Example:

[]