- API Reference
- Getting Started
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. GET /2fa/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
-
Send the request as usual. If the action is not protected, it simply succeeds.
-
Receive the challenge. If it is protected, the API answers
401withcode: "2fa_required":{"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"} -
Produce the answer for the
methodin the challenge (see below). -
Send the identical request again, with the same method, path and body, plus these headers:
Header Value X-2FA-Algo-IdThe twoFaAlgoIdfrom the challenge.X-2FA-ResponseThe TOTP code, the wallet signature or a backup code. X-2FA-Backup1whenX-2FA-Responseis a backup code. Omit it otherwise.Terminal window 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.
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 to see how many remain, and
POST /2fa/backup-codes/regenerate 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.
Managing two-factor settings
| Task | Endpoint |
|---|---|
| Read the current setup | GET /2fa/status |
| Enrol an authenticator app | POST /2fa/totp/enroll/start, then confirm |
| Enrol a wallet | POST /2fa/wallet/enroll/start, then confirm |
| Protect or unprotect one action | POST /2fa/actions/toggle |
| Protect every action | POST /2fa/protect-all |
| Turn two-factor off | POST /2fa/disable |
Changing these settings can itself require a second factor (label twofa.change_settings).