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

## Changes

> 52 revisions in range; 15 could not be searched.

- **2023-10-22** `b647a0e917e6` — 2 breaking, 6 info
  - the response's body type/format changed from ``/`` to `object`/`` for status `400`
  - the response's body type/format changed from ``/`` to `object`/`` for status `500`
  - removed `#/components/schemas/BaseJsonResponse, subschema #2` from the response body `allOf` list for the response status `400`
  - removed `#/components/schemas/BaseJsonResponse, subschema #2` from the response body `allOf` list for the response status `500`
  - …4 more
- **2022-07-22** `4b3ea48a957a` — 5 breaking, 4 warning, 5 info
  - the response's body type/format changed from `object`/`` to ``/`` for status `200`
  - the `allOf[subschema #2]/response/errors` response's property type/format changed from `object`/`` to `array`/`` for status `400`
  - the `allOf[subschema #2]/response/errors` response's property type/format changed from `object`/`` to `array`/`` for status `500`
  - removed the required property `meta` from the response with the `200` status
  - …10 more
- …earlier changes not shown

[Full history](https://skmtc.dev/pallets-eco/apis/flask-security-external-api/changes/us-setup/post.md)

---

[API](https://skmtc.dev/pallets-eco/apis/flask-security-external-api.md) · [All operations](https://skmtc.dev/pallets-eco/apis/flask-security-external-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/pallets-eco/flask-security-external-api/revisions/ee92f388dafa/schema)