Two-factor authentication

On this page

Check MFA statusEnable MFALogin with MFARecovery codesDisable MFASecurity notes

Add a second layer of security to your account with time-based one-time passwords (TOTP). Works with any authenticator app — Google Authenticator, Authy, 1Password, or similar.

Check MFA status

curl https://api.fold.run/mfa/status \
  -H "Authorization: Bearer YOUR_TOKEN"

Returns { "mfa_enabled": true } or { "mfa_enabled": false }.

Enable MFA

Step 1: Generate a secret

curl -X POST https://api.fold.run/mfa/setup \
  -H "Authorization: Bearer YOUR_TOKEN"

Returns a TOTP URI and secret:

{
  "totp_uri": "otpauth://totp/fold.run:you@example.com?secret=...",
  "secret": "BASE32SECRET"
}

Scan the totp_uri as a QR code in your authenticator app, or manually enter the secret.

Step 2: Verify and activate

Enter the 6-digit code from your authenticator to confirm setup:

curl -X POST https://api.fold.run/mfa/enable \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "code": "123456" }'

On success, this returns 8 recovery codes. Save these somewhere safe — they are your backup if you lose access to your authenticator.

{
  "message": "MFA enabled",
  "recovery_codes": [
    "a1b2c3d4e5f6",
    "g7h8i9j0k1l2",
    "..."
  ]
}

Login with MFA

When MFA is enabled, the login endpoint returns an mfa_token instead of a full JWT:

{
  "mfa_required": true,
  "mfa_token": "mfa_abc123..."
}

Submit the TOTP code to complete login:

curl -X POST https://api.fold.run/mfa/verify \
  -H "Content-Type: application/json" \
  -d '{
    "mfa_token": "mfa_abc123...",
    "code": "654321"
  }'

This returns the full JWT token. The mfa_token expires after 5 minutes.

Recovery codes

If you lose your authenticator, use a recovery code instead:

curl -X POST https://api.fold.run/mfa/recovery \
  -H "Content-Type: application/json" \
  -d '{
    "mfa_token": "mfa_abc123...",
    "code": "a1b2c3d4e5f6"
  }'

Each recovery code can only be used once. After use, it is permanently removed.

Regenerate recovery codes

Generate a new set of 8 codes (invalidates all previous codes):

curl -X POST https://api.fold.run/mfa/recovery-codes \
  -H "Authorization: Bearer YOUR_TOKEN"

Disable MFA

Requires a valid TOTP code from your authenticator:

curl -X POST https://api.fold.run/mfa/disable \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "code": "123456" }'

Disabling MFA invalidates all existing sessions.

Security notes

  • TOTP secrets are encrypted at rest with AES-GCM.
  • Verification endpoints are rate-limited to prevent brute-force attacks.
  • Enabling or disabling MFA invalidates all other sessions.
  • MFA applies to password login, OTP login, and OAuth login.
PreviousAccount managementNextPasswordless login