Sign in

v1

latestOpenAPI 3.0.3MIT2026-07-176638100.8 KB

Two-Factor setup.

Two-factor setup can be used in three cases:

  1. Initial login and application requires 2FA
  2. An authenticated user wishing to change their 2FA configuration
  3. An authenticated user wishes to enable or disable 2FA (assuming SECURITY_TWO_FACTOR_REQUIRED is False). Allowed 2FA methods are controlled via the configuration SECURITY_TWO_FACTOR_ENABLED_METHODS. This endpoint is protected by a 'freshness' check - meaning the caller will be required to have authenticated recently. In addition, to ensure correctness, the newly setup method must be verified by sending and entering a code prior to it being permanently stored.
post/tf-setup

Request body

setupstring required

Which method should be used to send the code, as configured with SECURITY_TWO_FACTOR_ENABLED_METHODS. If SECURITY_TWO_FACTOR_REQUIRED is False, the additional method 'disable' is available.

phonestring

phone number (this will be validated for format). Required if setup == "sms".

Example request

{
  "setup": "sms",
  "phone": "650-555-1212"
}

Response

Two-Factor setup response. Please note that the newly setup method must be validated PRIOR to it being stored permanently.

Example response

{
  "meta": {
    "code": 200
  },
  "response": {
    "tf_state": "validating_profile",
    "tf_primary_method": "sms",
    "tf_method": "sms"
  }
}