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.
The Two-factor status object
The second-factor configuration of the account.
Attributes
-
enabledbooleanWhether a second factor is enrolled and active. -
methodenum | nullEnrolled method.Possible valuestotpwallet -
protect_allbooleanWhether every protectable action requires 2FA. -
wallet_addressstring | nullEnrolled wallet, whenmethodiswallet. -
wallet_chainenum | nullChain of the enrolled wallet.Possible valuessolanaevm -
protected_labelsarray<string>Action labels the user's settings protect, including default-on labels. Listed whether or not 2FA is enabled.
The Protected action object
An action that 2FA can protect, and whether it is protected now.
Attributes
-
labelstringAction label, e.g.wallet.withdraw. -
descriptionstringHuman-readable description of the action. -
enabledbooleanWhether the action currently requires 2FA. Alwaysfalsewhile 2FA is not enabled.
Retrieve 2FA status
/2fa/status Returns the second-factor configuration of the account.
- 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.
Parameters
No parameters.
Returns 200 OK · application/json
Returns a Two-factor status object.
Errors
Only the common errors: 401 for a missing or expired session and 429 when rate limited.
Web client proxima.twofa.getStatus() src/lib/proxima/endpoints/twofa.ts
List protectable actions
/2fa/actions Lists every action 2FA can protect, with its current state.
- Token
- Base or upgraded session token.
- Read-only tokens
- Allowed.
- Retry
- Safe to retry
Parameters
No parameters.
Returns 200 OK · application/json
-
protect_allbooleanWhether every action is protected. -
twofa_enabledbooleanWhether 2FA is enabled. -
actionsarray<object>List of Protected action objects.
Errors
Only the common errors: 401 for a missing or expired session and 429 when rate limited.
Web client proxima.twofa.listActions() src/lib/proxima/endpoints/twofa.ts
Toggle an action's protection
/2fa/actions/toggle Turns 2FA protection on or off for one action.
- Token
- Base or upgraded session token.
- Read-only tokens
- Refused with
403 read_only_token. - Two-factor
- Step-up for
twofa.change_settingswhen the user protects it. How it works - Retry
- Safe to retry
enabledsets the state, so repeating the call changes nothing. A challenge answer works once, so a protected retry needs a new challenge.
Body parameters application/json
-
labelstring RequiredAction label, one of the labels from List protectable actions. -
enabledboolean Requiredtrueto protect the action,falseto stop protecting it.
Returns 200 OK · application/json
-
okbooleanAlwaystrue. -
labelstringUpdated label. -
enabledbooleanNew state.
Errors
| Status | Code | When and what to do |
|---|---|---|
| 400 | bad_request | The label is unknown. Use a label returned by List protectable actions. |
Also the common errors: 401 for a missing or expired session, 403 read_only_token, 401 2fa_required and 429 when rate limited.
Web client proxima.twofa.toggleAction({ label, enabled }) src/lib/proxima/endpoints/twofa.ts
Set Protect everything
/2fa/protect-all Requires 2FA on every protectable action, or goes back to per-action settings.
- Token
- Base or upgraded session token.
- Read-only tokens
- Refused with
403 read_only_token. - Two-factor
- Step-up for
twofa.change_settingswhen the user protects it. How it works - Retry
- Safe to retry
enabledsets 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.
Body parameters application/json
-
enabledboolean Requiredtrueto protect every action.
Returns 200 OK · application/json
-
okbooleanAlwaystrue. -
protect_allbooleanNew state.
Errors
Only the common errors: 401 for a missing or expired session, 403 read_only_token, 401 2fa_required and 429 when rate limited.
Web client proxima.twofa.setProtectAll({ enabled }) src/lib/proxima/endpoints/twofa.ts
Start TOTP enrollment
/2fa/totp/enroll/start Generates a TOTP secret for the user to add to an authenticator app.
- 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 succeeds. Use the secret from the latest response.
Nothing is stored yet: the secret only takes effect once Confirm TOTP enrollment succeeds. The web app shows otpauth_url as a QR code.
Parameters
No parameters.
Returns 200 OK · application/json
-
secretstringBase32 TOTP secret. -
otpauth_urlstringotpauth://URI for authenticator apps (SHA1, 6 digits). -
issuerstringIssuer shown in the app,Proxima. -
accountstringAccount label shown in the app: the license key, oruser-<id>for a base token.
Errors
| Status | Code | When and what to do |
|---|---|---|
| 429 | too_many_requests | More than 5 starts per minute. Wait a minute, then start again. |
Also the common errors: 401 for a missing or expired session, 403 read_only_token and 429 when rate limited.
Web client proxima.twofa.totpEnrollStart() src/lib/proxima/endpoints/twofa.ts
Confirm TOTP enrollment
/2fa/totp/enroll/confirm Verifies a code for the new secret and enables TOTP as second factor.
- 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: checkmethodwith Retrieve 2FA status.
Body parameters application/json
-
secretstring RequiredSecret returned by Start TOTP enrollment. -
codestring RequiredCurrent 6-digit code from the authenticator app.
Returns 200 OK · application/json
-
okbooleanAlwaystrue. -
methodstringEnrolled method,totp.
Errors
| Status | Code | When and what to do |
|---|---|---|
| 400 | bad_request | secret is empty. Send the secret returned by Start TOTP enrollment. |
| 400 | bad_request | code is not six digits. Send the six-digit code shown by the authenticator app. |
| 400 | bad_request | secret is not valid base32. Send the secret exactly as returned by Start TOTP enrollment. |
| 401 | unauthorized | 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 | More than 10 attempts per minute. Wait a minute before trying again. |
Also the common errors: 401 for a missing or expired session, 403 read_only_token and 429 when rate limited.
Web client proxima.twofa.totpEnrollConfirm({ secret, code }) src/lib/proxima/endpoints/twofa.ts
Start wallet enrollment
/2fa/wallet/enroll/start Returns a message for the wallet to sign to become the second factor.
- 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 application/json
-
wallet_addressstring RequiredWallet address: base58 on Solana,0xaddress on EVM. -
chainenum RequiredWallet type.Possible valuessolanaevm
Returns 200 OK · application/json
-
twoFaAlgoIdstringChallenge id to send back on confirm. -
challengestringMessage the wallet must sign. -
wallet_addressstringNormalized address. EVM addresses are lowercased with a0xprefix. -
chainenumWallet type.Possible valuessolanaevm
Errors
| Status | Code | When and what to do |
|---|---|---|
| 400 | bad_request | chain is not solana or evm. Send solana or evm. |
| 400 | bad_request | wallet_address is empty. Send the address of the wallet to enroll. |
| 400 | bad_request | 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 | More than 10 starts per minute. Wait a minute, then start again. |
Also the common errors: 401 for a missing or expired session, 403 read_only_token and 429 when rate limited.
Web client proxima.twofa.walletEnrollStart({ wallet_address, chain }) src/lib/proxima/endpoints/twofa.ts
Confirm wallet enrollment
/2fa/wallet/enroll/confirm Verifies the challenge signature and enables the wallet as second factor.
- 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. Checkmethodandwallet_addresswith Retrieve 2FA status.
Body parameters application/json
-
twoFaAlgoIdstring RequiredChallenge id returned by Start wallet enrollment. -
signaturestring RequiredSignature ofchallengeby the wallet.
Returns 200 OK · application/json
-
okbooleanAlwaystrue. -
methodstringEnrolled method,wallet. -
wallet_addressstringEnrolled wallet. -
chainenumWallet type.Possible valuessolanaevm
Errors
| Status | Code | When and what to do |
|---|---|---|
| 400 | bad_request | twoFaAlgoId is not a valid id. Send the twoFaAlgoId returned by Start wallet enrollment. |
| 400 | bad_request | signature is not hex, base58 or base64. Send the signature as the wallet returned it. |
| 400 | bad_request | 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 | The challenge expired (after 5 minutes), was already used, or was issued to another user. Start again with Start wallet enrollment and sign the new challenge. |
| 401 | unauthorized | twoFaAlgoId identifies a step-up challenge, not an enrollment challenge. Send the twoFaAlgoId returned by Start wallet enrollment. |
| 401 | unauthorized | 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 | More than 10 attempts per minute. Wait a minute before trying again. |
Also the common errors: 401 for a missing or expired session, 403 read_only_token and 429 when rate limited.
Web client proxima.twofa.walletEnrollConfirm({ twoFaAlgoId, signature }) src/lib/proxima/endpoints/twofa.ts
Disable 2FA
/2fa/disable Removes the second factor from the account.
- Token
- Base or upgraded session token.
- Read-only tokens
- Refused with
403 read_only_token. - Two-factor
- Step-up for
twofa.change_settingswhen the user protects it. How it works - Retry
- Safe to retry Once 2FA is off, a retry succeeds without a challenge and changes nothing.
Body parameters application/json
-
confirmboolean RequiredMust betrue. The SDK always sends it.
Returns 200 OK · application/json
-
okbooleanAlwaystrue. -
enabledbooleanAlwaysfalse.
Errors
| Status | Code | When and what to do |
|---|---|---|
| 400 | bad_request | confirm is not true. Send confirm: true. |
Also the common errors: 401 for a missing or expired session, 403 read_only_token, 401 2fa_required and 429 when rate limited.
Web client proxima.twofa.disable() src/lib/proxima/endpoints/twofa.ts
Retrieve backup code status
/2fa/backup-codes/status Returns how many backup codes exist and how many are unused.
- Token
- Base or upgraded session token.
- Read-only tokens
- Allowed.
- Retry
- Safe to retry
Parameters
No parameters.
Returns 200 OK · application/json
-
twofa_enabledbooleanWhether 2FA is enabled. -
totalintegerNumber of codes in the current set. -
remainingintegerUnused codes left. -
last_generated_atstring | nullWhen the current set was generated (UTC timestamp), ornullif none was.
Errors
Only the common errors: 401 for a missing or expired session and 429 when rate limited.
Web client proxima.twofa.getBackupStatus() src/lib/proxima/endpoints/twofa.ts
Regenerate backup codes
/2fa/backup-codes/regenerate Replaces all backup codes with a new set and returns it.
- Token
- Base or upgraded session token.
- Read-only tokens
- Refused with
403 read_only_token. - Two-factor
- Step-up for
twofa.change_settingswhen the user protects it. How it works - 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.
Body parameters application/json
-
confirmboolean RequiredMust betrue. The SDK always sends it.
Returns 200 OK · application/json
-
okbooleanAlwaystrue. -
codesarray<string>New single-use backup codes. -
countintegerNumber of codes.
Errors
| Status | Code | When and what to do |
|---|---|---|
| 400 | bad_request | confirm is not true. Send confirm: true. |
| 400 | bad_request | No 2FA method is enabled. Enroll an authenticator app or a wallet first, starting with Start TOTP enrollment. |
| 429 | too_many_requests | More than 5 regenerations per minute. Wait a minute before regenerating again. |
Also the common errors: 401 for a missing or expired session, 403 read_only_token, 401 2fa_required and 429 when rate limited.
Web client proxima.twofa.regenerateBackupCodes() src/lib/proxima/endpoints/twofa.ts