# Two-factor Step-up

> How protected actions return a 2fa_required challenge, and how to answer it with a TOTP code, a wallet signature or a backup code.

When an account has two-factor authentication enabled, sensitive actions need a second factor in addition to the
session token. The API does not have separate "verify" endpoints for this: the protected request itself returns a
challenge, and you send the same request again with the answer in headers.

Endpoints that can require a second factor show a **2FA** badge in this reference.

## Protected actions

Each protected action has a label. The account owner chooses which labels are protected, or protects all of them,
with the [two-factor endpoints](/reference/two-factor/). [`GET /2fa/actions`](/reference/two-factor/#list-actions)
returns the current list with each label's state.

| Label | Action | Protected by default |
| --- | --- | --- |
| `wallet.withdraw` | Withdraw funds from wallets | No |
| `wallet.export_funder` | Export a funder wallet's private key | No |
| `launch.reveal_key` | Export a launch wallet's private key | No |
| `keys.export` | View or export wallet private keys | Yes |
| `launch.share` | Share a launch with another license | No |
| `twofa.change_settings` | Change two-factor settings | No |

Acting on a launch that someone else shared with you always requires your own second factor, whatever your own
settings are. An account without two-factor authentication cannot act on shared launches.

## The flow

1. **Send the request as usual.** If the action is not protected, it simply succeeds.

2. **Receive the challenge.** If it is protected, the API answers `401` with `code: "2fa_required"`:

   ```json
   {
     "ok": false,
     "code": "2fa_required",
     "message": "2fa challenge required",
     "twoFaAlgoId": "9b2f6c1e-3a7d-4e58-b0c4-6d1e2f8a9b37",
     "method": "wallet",
     "label": "wallet.withdraw",
     "challenge": "Proxima 2FA\nAction: wallet.withdraw\nAlgoId: 9b2f6c1e-3a7d-4e58-b0c4-6d1e2f8a9b37\nPayload: 4f1c…",
     "wallet_address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
     "wallet_chain": "solana"
   }
   ```

3. **Produce the answer** for the `method` in the challenge (see below).

4. **Send the identical request again**, with the same method, path and body, plus these headers:

   | Header | Value |
   | --- | --- |
   | `X-2FA-Algo-Id` | The `twoFaAlgoId` from the challenge. |
   | `X-2FA-Response` | The TOTP code, the wallet signature or a backup code. |
   | `X-2FA-Backup` | `1` when `X-2FA-Response` is a backup code. Omit it otherwise. |

   ```bash
   curl -X POST "https://api-mig.proxima.tools/withdraw/execute" \
     -H "Authorization: Bearer $PROXIMA_JWT" \
     -H "Content-Type: application/json" \
     -H "X-2FA-Algo-Id: 9b2f6c1e-3a7d-4e58-b0c4-6d1e2f8a9b37" \
     -H "X-2FA-Response: 482913" \
     -d @withdraw.json
   ```

## Challenge fields

| Field | Type | Description |
| --- | --- | --- |
| `code` | string | Always `2fa_required`. |
| `twoFaAlgoId` | string (UUID) | Identifies this challenge. Send it back in `X-2FA-Algo-Id`. |
| `method` | `totp` \| `wallet` | The second factor enrolled on the account. |
| `label` | string | The protected action, from the table above. |
| `challenge` | string | Wallet method only. The exact message to sign. |
| `wallet_address` | string | Wallet method only. The address that must sign. |
| `wallet_chain` | `solana` \| `evm` | Wallet method only. How to sign. |

## Answering

### Authenticator app (TOTP)

Send the current six-digit code from the authenticator app enrolled with
[`POST /2fa/totp/enroll/start`](/reference/two-factor/#start-totp-enrollment).

### Wallet signature

Sign the `challenge` string exactly as received, as UTF-8 text, with the enrolled wallet:

| `wallet_chain` | How to sign | `X-2FA-Response` |
| --- | --- | --- |
| `solana` | `signMessage` on the UTF-8 bytes of `challenge` (Wallet Standard `solana:signMessage`) | The 64-byte signature, hex-encoded. Base58 and base64 are also accepted. |
| `evm` | `personal_sign` with `challenge` as the message (EIP-191) | The `0x`-prefixed signature returned by the wallet |

### Backup code

Each backup code works once. Send it in `X-2FA-Response` with `X-2FA-Backup: 1`. Use
[`GET /2fa/backup-codes/status`](/reference/two-factor/#retrieve-backup-code-status) to see how many remain, and
[`POST /2fa/backup-codes/regenerate`](/reference/two-factor/#regenerate-backup-codes) to issue a new set.

## Rules

- **Five minutes.** A challenge expires 300 seconds after it is issued.
- **One use.** A challenge is consumed by the first successful answer. Repeat the whole flow for the next action.
- **Same body.** The challenge is bound to a SHA-256 hash of the request body. If any field changes between the
  first request and the retry, the retry is refused with `401` ("request body changed"). Keep the body you sent and
  resend it byte for byte.
- **Same action.** A challenge issued for one label cannot authorize another.
- **Failures.** A wrong code, a bad signature or a used backup code returns `401 unauthorized`. Request a new
  challenge by sending the original request again without the headers.

> **Warning:** Do not cache or reuse answers. Since each challenge is single-use and tied to one request body, an answer cannot be
> replayed, and a client that tries will only accumulate failures.

## Managing two-factor settings

| Task | Endpoint |
| --- | --- |
| Read the current setup | [`GET /2fa/status`](/reference/two-factor/#retrieve-status) |
| Enrol an authenticator app | [`POST /2fa/totp/enroll/start`](/reference/two-factor/#start-totp-enrollment), then [`confirm`](/reference/two-factor/#confirm-totp-enrollment) |
| Enrol a wallet | [`POST /2fa/wallet/enroll/start`](/reference/two-factor/#start-wallet-enrollment), then [`confirm`](/reference/two-factor/#confirm-wallet-enrollment) |
| Protect or unprotect one action | [`POST /2fa/actions/toggle`](/reference/two-factor/#toggle-action) |
| Protect every action | [`POST /2fa/protect-all`](/reference/two-factor/#set-protect-all) |
| Turn two-factor off | [`POST /2fa/disable`](/reference/two-factor/#disable) |

Changing these settings can itself require a second factor (label `twofa.change_settings`).
