---
title: "Two-Factor setup."
method: POST
path: "/tf-setup"
---

# Two-Factor setup.

`POST /tf-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.

## Request body

- TfSetup
  - `setup` string, 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.
  - `phone` string — phone number (this will be validated for format). Required if setup == "sms".

## Response `200`

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

- TfSetupJsonResponse
  - `meta` object, required
    - `code` integer, required — Http status code
  - `response` object, required
    - `tf_state` string — Current state of Two-Factor configuration. Not present when disabling 2FA. This will be set to 'validating_profile' indicating the caller needs to call '/tf-validate' with the correct code. N.B. as of 5.5.0 this is only used for setting up as part of initial login when 2FA is required. See tf_state_token below for use when an authenticated user wants to change their 2FA method.
    - `tf_state_token` string — Timed and signed token containing necessary state to complete the setup. To validate the method POST the code to '/tf-setup/<tf_state_token>'.
    - `tf_primary_method` string — Current method being configured (deprecated).
    - `tf_method` string — Current method being configured.
    - `tf_authr_key` string — Pretty TOTP key for setting up authenticator manually (if tf_primary_method == 'authenticator')
    - `tf_authr_b32key` string — Base32 TOTP key for setting up authenticator (useful to create a uri) (if chosen_method == 'authenticator')
    - `tf_authr_uri` string — A 'otpauth://' style URI suitable to creating a QRCode (if chosen_method == 'authenticator')
    - `tf_authr_issuer` string — Issuer as configured with TOTP_ISSUER (same as used in QRcode) (if tf_primary_method == 'authenticator')
    - `tf_authr_username` string — Username (same as used in QRcode) (if tf_primary_method == 'authenticator')

## Other responses

- `302` — Successfully disabled two-factor.
- `400` — Errors while validating attributes.
- `500` — Error when trying to send code.

---

[API](https://skmtc.net/pallets-eco/apis/flask-security-external-api.md) · [All operations](https://skmtc.net/pallets-eco/apis/flask-security-external-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/pallets-eco/flask-security-external-api/versions/5ee7c28d6e1e/schema)