# Two-factor authentication

> Enroll a TOTP app or a wallet as second factor and choose which actions require it.

An account can protect sensitive actions with one second factor: a TOTP authenticator app or a wallet signature (Solana or EVM). Enrollment takes two calls, start then confirm. After enrolling, the web app turns on **Protect everything**, then offers to generate backup codes.

Each protectable action has a label. `keys.export` is protected by default once 2FA is on; the others are opt-in, unless `protect_all` is set.

| Label | Action |
|---|---|
| `wallet.withdraw` | Withdraw funds from your wallets |
| `wallet.export_funder` | Export a funder wallet's private key |
| `launch.reveal_key` | Export a launch wallet's private key |
| `keys.export` | View or export your wallets' private keys |
| `launch.share` | Share one of your launches with another license |
| `twofa.change_settings` | Change your 2FA settings |

A protected call answers `401 2fa_required` with a challenge. The client retries the same request with the `X-2FA-*` headers, using a code, a wallet signature or a backup code.

Base URL: `https://api-mig.proxima.tools`

## Endpoints

- `GET /2fa/status`: Retrieve 2FA status
- `GET /2fa/actions`: List protectable actions
- `POST /2fa/actions/toggle`: Toggle an action's protection
- `POST /2fa/protect-all`: Set Protect everything
- `POST /2fa/totp/enroll/start`: Start TOTP enrollment
- `POST /2fa/totp/enroll/confirm`: Confirm TOTP enrollment
- `POST /2fa/wallet/enroll/start`: Start wallet enrollment
- `POST /2fa/wallet/enroll/confirm`: Confirm wallet enrollment
- `POST /2fa/disable`: Disable 2FA
- `GET /2fa/backup-codes/status`: Retrieve backup code status
- `POST /2fa/backup-codes/regenerate`: Regenerate backup codes

## The Two-factor status object

The second-factor configuration of the account.

- `enabled` (boolean): Whether a second factor is enrolled and active.
- `method` (enum | null): Enrolled method. Possible values: `totp`, `wallet`.
- `protect_all` (boolean): Whether every protectable action requires 2FA.
- `wallet_address` (string | null): Enrolled wallet, when `method` is `wallet`.
- `wallet_chain` (enum | null): Chain of the enrolled wallet. Possible values: `solana`, `evm`.
- `protected_labels` (array<string>): Action labels the user's settings protect, including default-on labels. Listed whether or not 2FA is enabled.

```json
{
  "enabled": true,
  "method": "totp",
  "protect_all": false,
  "wallet_address": null,
  "wallet_chain": null,
  "protected_labels": [
    "wallet.withdraw",
    "keys.export"
  ]
}
```

## The Protected action object

An action that 2FA can protect, and whether it is protected now.

- `label` (string): Action label, e.g. `wallet.withdraw`.
- `description` (string): Human-readable description of the action.
- `enabled` (boolean): Whether the action currently requires 2FA. Always `false` while 2FA is not enabled.

```json
{
  "label": "wallet.withdraw",
  "description": "Withdraw funds from your wallets",
  "enabled": true
}
```

### Retrieve 2FA status

`GET /2fa/status`

Returns the second-factor configuration of the account. (Bearer JWT)

- Token: Base or upgraded session token.
- Read-only tokens: allowed.
- Retry: Safe to retry.

The 2FA settings page loads this first, and only loads actions and backup codes when `enabled` is `true`.

#### Returns 200 OK

Returns a [Two-factor status](#object-two-factor-status) object.

#### Example request

```bash
curl "https://api-mig.proxima.tools/2fa/status" \
  -H "Authorization: Bearer $PROXIMA_JWT"
```

#### Example response

```json
{
  "enabled": true,
  "method": "totp",
  "protect_all": false,
  "wallet_address": null,
  "wallet_chain": null,
  "protected_labels": [
    "wallet.withdraw",
    "keys.export"
  ]
}
```

### List protectable actions

`GET /2fa/actions`

Lists every action 2FA can protect, with its current state. (Bearer JWT)

- Token: Base or upgraded session token.
- Read-only tokens: allowed.
- Retry: Safe to retry.

#### Returns 200 OK

- `protect_all` (boolean): Whether every action is protected.
- `twofa_enabled` (boolean): Whether 2FA is enabled.
- `actions` (array<object>): List of [Protected action](#object-protected-action) objects.

#### Example request

```bash
curl "https://api-mig.proxima.tools/2fa/actions" \
  -H "Authorization: Bearer $PROXIMA_JWT"
```

#### Example response

```json
{
  "protect_all": false,
  "twofa_enabled": true,
  "actions": [
    {
      "label": "wallet.withdraw",
      "description": "Withdraw funds from your wallets",
      "enabled": true
    },
    {
      "label": "wallet.export_funder",
      "description": "Export a funder wallet's private key",
      "enabled": false
    },
    {
      "label": "launch.reveal_key",
      "description": "Export a launch wallet's private key",
      "enabled": false
    },
    {
      "label": "keys.export",
      "description": "View or export your wallets' private keys",
      "enabled": true
    },
    {
      "label": "launch.share",
      "description": "Share one of your launches with another license",
      "enabled": false
    },
    {
      "label": "twofa.change_settings",
      "description": "Change your 2FA settings",
      "enabled": false
    }
  ]
}
```

### Toggle an action's protection

`POST /2fa/actions/toggle`

Turns 2FA protection on or off for one action. (Bearer JWT · 2FA step-up)

- Token: Base or upgraded session token.
- Read-only tokens: refused with `403 read_only_token`.
- Two-factor: step-up for `twofa.change_settings` when the user protects it (`401 2fa_required`).
- Retry: Safe to retry. `enabled` sets the state, so repeating the call changes nothing. A challenge answer works once, so a protected retry needs a new challenge.

> The challenge label is `twofa.change_settings`. When the change would lift `keys.export` protection for a user whose license can manage keys, the label is `keys.export` instead, and it is asked even if `twofa.change_settings` is not protected.

#### Body parameters

- `label` (string, required): Action label, one of the labels from [List protectable actions](#list-actions).
- `enabled` (boolean, required): `true` to protect the action, `false` to stop protecting it.

#### Returns 200 OK

- `ok` (boolean): Always `true`.
- `label` (string): Updated label.
- `enabled` (boolean): New state.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `unknown action label` | The label is unknown. | Use a label returned by [List protectable actions](/reference/two-factor/#list-actions). |

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/2fa/actions/toggle" \
  -H "Authorization: Bearer $PROXIMA_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "label": "launch.share",
  "enabled": true
}'
```

#### Example response

```json
{
  "ok": true,
  "label": "launch.share",
  "enabled": true
}
```

### Set Protect everything

`POST /2fa/protect-all`

Requires 2FA on every protectable action, or goes back to per-action settings. (Bearer JWT · 2FA step-up)

- Token: Base or upgraded session token.
- Read-only tokens: refused with `403 read_only_token`.
- Two-factor: step-up for `twofa.change_settings` when the user protects it (`401 2fa_required`).
- Retry: Safe to retry. `enabled` sets the state, so repeating the call changes nothing. A challenge answer works once, so a protected retry needs a new challenge.

The web app sends `enabled: true` right after a successful enrollment.

> The challenge label is `twofa.change_settings`. When the change would lift `keys.export` protection for a user whose license can manage keys, the label is `keys.export` instead, and it is asked even if `twofa.change_settings` is not protected.

#### Body parameters

- `enabled` (boolean, required): `true` to protect every action.

#### Returns 200 OK

- `ok` (boolean): Always `true`.
- `protect_all` (boolean): New state.

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/2fa/protect-all" \
  -H "Authorization: Bearer $PROXIMA_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "enabled": true
}'
```

#### Example response

```json
{
  "ok": true,
  "protect_all": true
}
```

### Start TOTP enrollment

`POST /2fa/totp/enroll/start`

Generates a TOTP secret for the user to add to an authenticator app. (Bearer JWT)

- Token: Base or upgraded session token.
- Read-only tokens: refused with `403 read_only_token`.
- Retry: Safe to retry. Nothing is stored until [Confirm TOTP enrollment](/reference/two-factor/#confirm-totp-enrollment) succeeds. Use the secret from the latest response.

Nothing is stored yet: the secret only takes effect once [Confirm TOTP enrollment](#confirm-totp-enrollment) succeeds. The web app shows `otpauth_url` as a QR code.

#### Returns 200 OK

- `secret` (string): Base32 TOTP secret.
- `otpauth_url` (string): `otpauth://` URI for authenticator apps (SHA1, 6 digits).
- `issuer` (string): Issuer shown in the app, `Proxima`.
- `account` (string): Account label shown in the app: the license key, or `user-<id>` for a base token.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 429 | `too_many_requests` | `rate limit exceeded for twofa_totp_start, please retry later` | More than 5 starts per minute. | Wait a minute, then start again. |

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/2fa/totp/enroll/start" \
  -H "Authorization: Bearer $PROXIMA_JWT"
```

#### Example response

```json
{
  "secret": "KZXW6YTBOJ2GKZLTMVZXIZLSMFWWK3TU",
  "otpauth_url": "otpauth://totp/Proxima:NOVA-x7Kp2QmZr9Tb4Lw8E?secret=KZXW6YTBOJ2GKZLTMVZXIZLSMFWWK3TU&issuer=Proxima&algorithm=SHA1&digits=6&period=30",
  "issuer": "Proxima",
  "account": "NOVA-x7Kp2QmZr9Tb4Lw8E"
}
```

### Confirm TOTP enrollment

`POST /2fa/totp/enroll/confirm`

Verifies a code for the new secret and enables TOTP as second factor. (Bearer JWT)

- Token: Base or upgraded session token.
- Read-only tokens: refused with `403 read_only_token`.
- Retry: Safe to retry. Confirming again stores the same secret. If the code has rotated in the meantime, the retry fails with `401`: check `method` with [Retrieve 2FA status](/reference/two-factor/#retrieve-status).

#### Body parameters

- `secret` (string, required): Secret returned by [Start TOTP enrollment](#start-totp-enrollment).
- `code` (string, required): Current 6-digit code from the authenticator app.

#### Returns 200 OK

- `ok` (boolean): Always `true`.
- `method` (string): Enrolled method, `totp`.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `secret required` | `secret` is empty. | Send the `secret` returned by [Start TOTP enrollment](/reference/two-factor/#start-totp-enrollment). |
| 400 | `bad_request` | `code must be 6 digits` | `code` is not six digits. | Send the six-digit code shown by the authenticator app. |
| 400 | `bad_request` | `invalid base32 character` | `secret` is not valid base32. | Send the `secret` exactly as returned by [Start TOTP enrollment](/reference/two-factor/#start-totp-enrollment). |
| 401 | `unauthorized` | `invalid totp code` | The code does not match the secret. Codes change every 30 seconds, and one step of clock drift is accepted. | Check the device clock, then send the code the app shows now. |
| 429 | `too_many_requests` | `rate limit exceeded for twofa_totp_confirm, please retry later` | More than 10 attempts per minute. | Wait a minute before trying again. |

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/2fa/totp/enroll/confirm" \
  -H "Authorization: Bearer $PROXIMA_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "secret": "KZXW6YTBOJ2GKZLTMVZXIZLSMFWWK3TU",
  "code": "492015"
}'
```

#### Example response

```json
{
  "ok": true,
  "method": "totp"
}
```

### Start wallet enrollment

`POST /2fa/wallet/enroll/start`

Returns a message for the wallet to sign to become the second factor. (Bearer JWT)

- Token: Base or upgraded session token.
- Read-only tokens: refused with `403 read_only_token`.
- Retry: Safe to retry. Each call issues a new challenge and stores nothing else. Sign the challenge from the latest response.

#### Body parameters

- `wallet_address` (string, required): Wallet address: base58 on Solana, `0x` address on EVM.
- `chain` (enum, required): Wallet type. Possible values: `solana`, `evm`.

#### Returns 200 OK

- `twoFaAlgoId` (string): Challenge id to send back on confirm.
- `challenge` (string): Message the wallet must sign.
- `wallet_address` (string): Normalized address. EVM addresses are lowercased with a `0x` prefix.
- `chain` (enum): Wallet type. Possible values: `solana`, `evm`.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `invalid wallet chain` | `chain` is not `solana` or `evm`. | Send `solana` or `evm`. |
| 400 | `bad_request` | `wallet_address required` | `wallet_address` is empty. | Send the address of the wallet to enroll. |
| 400 | `bad_request` | `invalid solana address: <reason>` | The address is not valid for `chain`. For an EVM wallet the message is `invalid evm address: <reason>`. | Send a base58 public key for `solana`, or a 20-byte hex address for `evm`. |
| 429 | `too_many_requests` | `rate limit exceeded for twofa_wallet_start, please retry later` | More than 10 starts per minute. | Wait a minute, then start again. |

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/2fa/wallet/enroll/start" \
  -H "Authorization: Bearer $PROXIMA_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "wallet_address": "7xKQm3vR9pTn2LcW8fYbHs4dJ6gA5uE1zNqXwVy2Bk3P",
  "chain": "solana"
}'
```

#### Example response

```json
{
  "twoFaAlgoId": "b2c9e4f1-6a3d-4d8b-9e7c-1f5a3b8d2c46",
  "challenge": "Proxima 2FA enrollment\nWallet: 7xKQm3vR9pTn2LcW8fYbHs4dJ6gA5uE1zNqXwVy2Bk3P\nAlgoId: b2c9e4f1-6a3d-4d8b-9e7c-1f5a3b8d2c46",
  "wallet_address": "7xKQm3vR9pTn2LcW8fYbHs4dJ6gA5uE1zNqXwVy2Bk3P",
  "chain": "solana"
}
```

### Confirm wallet enrollment

`POST /2fa/wallet/enroll/confirm`

Verifies the challenge signature and enables the wallet as second factor. (Bearer JWT)

- Token: Base or upgraded session token.
- Read-only tokens: refused with `403 read_only_token`.
- Retry: Check before retrying. A successful call consumes the challenge, so a retry fails with `401`. Check `method` and `wallet_address` with [Retrieve 2FA status](/reference/two-factor/#retrieve-status).

#### Body parameters

- `twoFaAlgoId` (string, required): Challenge id returned by [Start wallet enrollment](#start-wallet-enrollment).
- `signature` (string, required): Signature of `challenge` by the wallet.

#### Returns 200 OK

- `ok` (boolean): Always `true`.
- `method` (string): Enrolled method, `wallet`.
- `wallet_address` (string): Enrolled wallet.
- `chain` (enum): Wallet type. Possible values: `solana`, `evm`.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `invalid twoFaAlgoId` | `twoFaAlgoId` is not a valid id. | Send the `twoFaAlgoId` returned by [Start wallet enrollment](/reference/two-factor/#start-wallet-enrollment). |
| 400 | `bad_request` | `invalid signature encoding` | `signature` is not hex, base58 or base64. | Send the signature as the wallet returned it. |
| 400 | `bad_request` | `ed25519 signature must be 64 bytes, got <length>` | The decoded signature has the wrong length: 64 bytes for a Solana wallet, 65 for an EVM wallet (message `evm signature must be 65 bytes, got <length>`). | Send the complete signature returned by the wallet. |
| 401 | `unauthorized` | `enrollment challenge expired or unknown` | The challenge expired (after 5 minutes), was already used, or was issued to another user. | Start again with [Start wallet enrollment](/reference/two-factor/#start-wallet-enrollment) and sign the new challenge. |
| 401 | `unauthorized` | `not an enrollment challenge` | `twoFaAlgoId` identifies a step-up challenge, not an enrollment challenge. | Send the `twoFaAlgoId` returned by [Start wallet enrollment](/reference/two-factor/#start-wallet-enrollment). |
| 401 | `unauthorized` | `invalid wallet signature` | The signature was not made over the challenge by the wallet being enrolled. On EVM the message is `wallet signature does not match`. | Sign the `challenge` string exactly as returned, with the wallet whose address you sent. |
| 429 | `too_many_requests` | `rate limit exceeded for twofa_wallet_confirm, please retry later` | More than 10 attempts per minute. | Wait a minute before trying again. |

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/2fa/wallet/enroll/confirm" \
  -H "Authorization: Bearer $PROXIMA_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "twoFaAlgoId": "b2c9e4f1-6a3d-4d8b-9e7c-1f5a3b8d2c46",
  "signature": "4kXr9WmT2bQn7YcHs5Ld3GpZf8Jv6Ae1KuN2Bt7Ew4Mh9Zx3Vr5Cy8Pk2Ds6Gq1Lb4Hn7Wt3Jm9Nf5Re2Uz8Ka6Vb3Qs"
}'
```

#### Example response

```json
{
  "ok": true,
  "method": "wallet",
  "wallet_address": "7xKQm3vR9pTn2LcW8fYbHs4dJ6gA5uE1zNqXwVy2Bk3P",
  "chain": "solana"
}
```

### Disable 2FA

`POST /2fa/disable`

Removes the second factor from the account. (Bearer JWT · 2FA step-up)

- Token: Base or upgraded session token.
- Read-only tokens: refused with `403 read_only_token`.
- Two-factor: step-up for `twofa.change_settings` when the user protects it (`401 2fa_required`).
- Retry: Safe to retry. Once 2FA is off, a retry succeeds without a challenge and changes nothing.

> Every protected action, including key exports and withdrawals, stops asking for a second factor.

> The challenge label is `twofa.change_settings`. When the change would lift `keys.export` protection for a user whose license can manage keys, the label is `keys.export` instead, and it is asked even if `twofa.change_settings` is not protected.

#### Body parameters

- `confirm` (boolean, required): Must be `true`. The SDK always sends it.

#### Returns 200 OK

- `ok` (boolean): Always `true`.
- `enabled` (boolean): Always `false`.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `confirm=true required` | `confirm` is not `true`. | Send `confirm: true`. |

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/2fa/disable" \
  -H "Authorization: Bearer $PROXIMA_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "confirm": true
}'
```

#### Example response

```json
{
  "ok": true,
  "enabled": false
}
```

### Retrieve backup code status

`GET /2fa/backup-codes/status`

Returns how many backup codes exist and how many are unused. (Bearer JWT)

- Token: Base or upgraded session token.
- Read-only tokens: allowed.
- Retry: Safe to retry.

#### Returns 200 OK

- `twofa_enabled` (boolean): Whether 2FA is enabled.
- `total` (integer): Number of codes in the current set.
- `remaining` (integer): Unused codes left.
- `last_generated_at` (string | null): When the current set was generated (UTC timestamp), or `null` if none was.

#### Example request

```bash
curl "https://api-mig.proxima.tools/2fa/backup-codes/status" \
  -H "Authorization: Bearer $PROXIMA_JWT"
```

#### Example response

```json
{
  "twofa_enabled": true,
  "total": 10,
  "remaining": 8,
  "last_generated_at": "2026-10-14T08:31:52.204118"
}
```

### Regenerate backup codes

`POST /2fa/backup-codes/regenerate`

Replaces all backup codes with a new set and returns it. (Bearer JWT · 2FA step-up)

- Token: Base or upgraded session token.
- Read-only tokens: refused with `403 read_only_token`.
- Two-factor: step-up for `twofa.change_settings` when the user protects it (`401 2fa_required`).
- Retry: Safe to retry. Each call replaces the whole set. A retry invalidates the codes of a lost response and returns the only valid set.

The codes are only returned in this response. The web app shows them once and offers a text file download.

> Previous backup codes stop working immediately.

> The challenge label is `twofa.change_settings`.

#### Body parameters

- `confirm` (boolean, required): Must be `true`. The SDK always sends it.

#### Returns 200 OK

- `ok` (boolean): Always `true`.
- `codes` (array<string>): New single-use backup codes.
- `count` (integer): Number of codes.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `confirm=true required` | `confirm` is not `true`. | Send `confirm: true`. |
| 400 | `bad_request` | `enable a 2FA method before generating backup codes` | No 2FA method is enabled. | Enroll an authenticator app or a wallet first, starting with [Start TOTP enrollment](/reference/two-factor/#start-totp-enrollment). |
| 429 | `too_many_requests` | `rate limit exceeded for twofa_backup_regenerate, please retry later` | More than 5 regenerations per minute. | Wait a minute before regenerating again. |

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/2fa/backup-codes/regenerate" \
  -H "Authorization: Bearer $PROXIMA_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "confirm": true
}'
```

#### Example response

```json
{
  "ok": true,
  "codes": [
    "3f9a1-c07be",
    "8d2e4-71af0",
    "b56c9-2e8d1",
    "04fa7-9c3b2",
    "e19d8-5a6c4",
    "7c0b3-d4e92",
    "5a8f1-0b7c6",
    "c2e60-8f1a9",
    "91b4d-3e7f5",
    "6d7a2-c9e03"
  ],
  "count": 10
}
```
