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 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 second-factor configuration of the account.

Attributes

  • enabled boolean
    Whether a second factor is enrolled and active.
  • method enum | null
    Enrolled method.
    Possible values totpwallet
  • 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 solanaevm
  • protected_labels array<string>
    Action labels the user's settings protect, including default-on labels. Listed whether or not 2FA is enabled.

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

Attributes

  • 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.

Retrieve 2FA status

Bearer JWT
GET /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

GET /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_all boolean
    Whether every action is protected.
  • twofa_enabled boolean
    Whether 2FA is enabled.
  • actions array<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

POST /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_settings when the user protects it. How it works
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.

Body parameters application/json

  • label string Required
    Action label, one of the labels from List protectable actions.
  • enabled boolean Required
    true to protect the action, false to stop protecting it.

Returns 200 OK · application/json

  • ok boolean
    Always true.
  • label string
    Updated label.
  • enabled boolean
    New state.

Errors

StatusCodeWhen 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

POST /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_settings when the user protects it. How it works
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.

Body parameters application/json

  • enabled boolean Required
    true to protect every action.

Returns 200 OK · application/json

  • ok boolean
    Always true.
  • protect_all boolean
    New 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

POST /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

  • 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

StatusCodeWhen 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

POST /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: check method with Retrieve 2FA status.

Body parameters application/json

  • secret string Required
    Secret returned by Start TOTP enrollment.
  • code string Required
    Current 6-digit code from the authenticator app.

Returns 200 OK · application/json

  • ok boolean
    Always true.
  • method string
    Enrolled method, totp.

Errors

StatusCodeWhen 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

POST /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_address string Required
    Wallet address: base58 on Solana, 0x address on EVM.
  • chain enum Required
    Wallet type.
    Possible values solanaevm

Returns 200 OK · application/json

  • 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 solanaevm

Errors

StatusCodeWhen 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

POST /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. Check method and wallet_address with Retrieve 2FA status.

Body parameters application/json

  • twoFaAlgoId string Required
    Challenge id returned by Start wallet enrollment.
  • signature string Required
    Signature of challenge by the wallet.

Returns 200 OK · application/json

  • ok boolean
    Always true.
  • method string
    Enrolled method, wallet.
  • wallet_address string
    Enrolled wallet.
  • chain enum
    Wallet type.
    Possible values solanaevm

Errors

StatusCodeWhen 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

Bearer JWT 2FA
POST /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_settings when 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

  • confirm boolean Required
    Must be true. The SDK always sends it.

Returns 200 OK · application/json

  • ok boolean
    Always true.
  • enabled boolean
    Always false.

Errors

StatusCodeWhen 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

GET /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_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.

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

POST /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_settings when 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

  • confirm boolean Required
    Must be true. The SDK always sends it.

Returns 200 OK · application/json

  • ok boolean
    Always true.
  • codes array<string>
    New single-use backup codes.
  • count integer
    Number of codes.

Errors

StatusCodeWhen 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