POST
/
token_exchange
curl --request POST \
  --url https://{tenant_id}.hanko.io/token_exchange \
  --header 'Content-Type: application/json' \
  --data '{
  "input_data": {
    "token": "<string>"
  },
  "csrf_token": "qvcZt29spXYO77Y9IaxxN4MzLnmbjozl"
}'
{
  "actions": {
    "verify_passcode": {
      "action": "verify_passcode",
      "href": "<string>",
      "description": "<string>",
      "inputs": {
        "code": {
          "name": "code",
          "type": "string",
          "required": true,
          "min_length": 123,
          "max_length": 123,
          "hidden": true,
          "value": "<string>",
          "allowed_values": [
            {
              "name": "<string>",
              "value": "<any>"
            }
          ]
        }
      }
    },
    "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": []
}

Headers

​
X-Language
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)
  • "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.

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
object

Input data for the exchange_token action.

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

​
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
Example:
[]

Was this page helpful?

Suggest editsRaise issue