---
title: "Start two-factor authentication enrollment"
method: POST
path: "/auth/totp/setup"
---

# Start two-factor authentication enrollment

`POST /auth/totp/setup`

## Request

- Base URL: `https://app.yoping.me/api/v1`
- URL: `https://app.yoping.me/api/v1/auth/totp/setup`
- Auth: API key in cookie `yp_session`

Re-verifies the caller's password (a stolen session cookie alone must not be able to enroll 2FA and lock the owner out), then generates a fresh TOTP secret and stores it as pending — login ignores it until POST /auth/totp/confirm proves the authenticator holds it. Refused with 400 if two-factor authentication is already enabled. Shares the per-user 5 code attempts per minute limiter with confirm and login phase 2.

## Request body

- TOTPSetupRequest
  - `password` string, required: The caller's current password, re-verified before starting enrollment so a stolen session cookie alone cannot enable two-factor authentication.

## Response `200`

Pending secret created.

- object: Uniform success envelope: the payload is always under `data`.
  - `data` object, required
    - `otpauth_uri` string, required: otpauth:// URI for the authenticator app to scan or import.
    - `secret` string, required: The base32 TOTP secret, for manual entry.

## Other responses

- `400`: Invalid input (code `validation_failed`): malformed JSON, a missing or out-of-range field, bad pagination parameters, or a rejected token.
- `401`: Not authenticated (code `unauthorized`): missing, invalid, or expired session; invalid login credentials; or a Bearer token, which this surface rejects.
- `403`: Forbidden. Code `forbidden` for a cross-origin (CSRF) request blocked by origin validation or for API-key management attempted without a browser session; `account_suspended` when a suspended account attempts a mutation; `account_deleted` when an account in its deletion grace window calls a non-exempt route.
- `429`: Too many requests (code `rate_limited`). A global per-IP budget of 300 requests/minute (burst 60) applies to every endpoint; login, signup, and test alerts have tighter dedicated limits.

---

[API](https://skmtc.dev/yoping/apis/yopingme-api.md) · [All operations](https://skmtc.dev/yoping/apis/yopingme-api/llms.txt) · [OpenAPI document](https://skmtc.dev/yoping/apis/yopingme-api/revisions/76d8deb40173?raw)