Skip to content
API Reference

Search is only available in production builds. Try building and previewing the site to test it out locally.

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.

LabelActionProtected by default
wallet.withdrawWithdraw funds from walletsNo
wallet.export_funderExport a funder wallet’s private keyNo
launch.reveal_keyExport a launch wallet’s private keyNo
keys.exportView or export wallet private keysYes
launch.shareShare a launch with another licenseNo
twofa.change_settingsChange two-factor settingsNo

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":

    {
    "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:

    HeaderValue
    X-2FA-Algo-IdThe twoFaAlgoId from the challenge.
    X-2FA-ResponseThe TOTP code, the wallet signature or a backup code.
    X-2FA-Backup1 when X-2FA-Response is 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

FieldTypeDescription
codestringAlways 2fa_required.
twoFaAlgoIdstring (UUID)Identifies this challenge. Send it back in X-2FA-Algo-Id.
methodtotp | walletThe second factor enrolled on the account.
labelstringThe protected action, from the table above.
challengestringWallet method only. The exact message to sign.
wallet_addressstringWallet method only. The address that must sign.
wallet_chainsolana | evmWallet 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_chainHow to signX-2FA-Response
solanasignMessage on the UTF-8 bytes of challenge (Wallet Standard solana:signMessage)The 64-byte signature, hex-encoded. Base58 and base64 are also accepted.
evmpersonal_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

TaskEndpoint
Read the current setupGET /2fa/status
Enrol an authenticator appPOST /2fa/totp/enroll/start, then confirm
Enrol a walletPOST /2fa/wallet/enroll/start, then confirm
Protect or unprotect one actionPOST /2fa/actions/toggle
Protect every actionPOST /2fa/protect-all
Turn two-factor offPOST /2fa/disable

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