---
title: "Unified sign in setup."
method: POST
path: "/us-setup"
---

# Unified sign in setup.

`POST /us-setup`

An authenticated user can call this endpoint to update or add additional methods for authenticating (e.g. sms, authenticator app). This is controlled by application configuration settings SECURITY_US_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. This verification process is also time-limited.

## Request body

- UsSetup
  - `chosen_method` string — which method should be used to send the code, as configured with SECURITY_US_ENABLED_METHODS
  - `delete_method` string — which previously set up method should be deleted.
  - `phone` string — phone number (this will be normalized). Required if chosen_method == "sms".

## Response `200`

Unified sign in setup response.

- UsSetupJsonResponse
  - `meta` object, required
    - `code` integer, required — Http status code
  - `response` object, required — Response when setting up a new method. When deleting, nothing is returned.
    - `chosen_method` string — The chosen_method as passed into API.
    - `phone` string — The canonicalized phone number if setting up SMS
    - `authr_key` string — Pretty TOTP key for setting up authenticator manually (if chosen_method == 'authenticator')
    - `authr_b32key` string — Base32 TOTP key for setting up authenticator (useful to create a uri) (if chosen_method == 'authenticator')
    - `authr_uri` string — A 'otpauth://' style URI suitable to creating a QRCode (if chosen_method == 'authenticator')
    - `authr_issuer` string — Issuer as configured with TOTP_ISSUER (same as used in QRcode) (if chosen_method == 'authenticator')
    - `authr_username` string — Username (same as used in QRcode) (if chosen_method == 'authenticator')
    - `state` string — Opaque blob that must be pass to /us-setup/<state>. This is a signed, timed token.

## Other responses

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