Two-Factor Authentication

Setting Up 2FA

Two-Factor Authentication (2FA) adds a second verification step during login, significantly improving account security. CargoLint supports TOTP (Time-based One-Time Password) authentication.

Enable 2FA via UI

1. Navigate to Settings > Security
2. Click Enable Two-Factor Authentication
3. A QR code appears on screen
4. Open your authenticator app (see supported apps below)
5. Scan the QR code
6. Enter the 6-digit code from your authenticator
7. Click Verify
8. Save your recovery codes in a secure location
9. Click Enable 2FA

Enable 2FA via API

# Step 1: Get setup details (secret + QR code)
curl -X GET https://api.cargolint.com/api/v1/auth/2fa/setup \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response contains:

• secret - Your TOTP secret (save for manual entry)
• qrCodeUrl - URL to generated QR code

# Step 2: Verify and enable with a code from your authenticator
curl -X POST https://api.cargolint.com/api/v1/auth/2fa/enable \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"code": "123456"}'

This returns your 8 one-time recovery codes. Store them securely.

Supported Authenticator Apps

2FA uses the TOTP standard. Compatible apps:

• Google Authenticator (iOS, Android)
• Microsoft Authenticator (iOS, Android)
• Authy (iOS, Android, desktop)
• FreeOTP (iOS, Android)
• 1Password (iOS, Android, desktop)
• Bitwarden (all platforms)

Disabling 2FA

Via API

curl -X POST https://api.cargolint.com/api/v1/auth/2fa/disable \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"code": "123456"}'

Requires a valid TOTP code to confirm the disable action.

Checking 2FA Status

curl -X GET https://api.cargolint.com/api/v1/auth/2fa/status \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Recovery Codes

During 2FA setup, you receive 8 one-time recovery codes. Each code is valid for one login if you lose access to your authenticator.

Using a Recovery Code

1. At the 2FA code prompt, enter your recovery code instead of the 6-digit code
2. The code is consumed and cannot be reused
3. You’re logged in successfully

Regenerating Recovery Codes

curl -X POST https://api.cargolint.com/api/v1/auth/2fa/recovery-codes/regenerate \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"code": "123456"}'

Old codes are invalidated. Store new codes securely.

Losing Your Authenticator Device

If you lose access to your authenticator (lost phone, factory reset):

1. Use a Recovery Code - If you have one saved
2. Account Recovery - Email support@cargolint.com with proof of identity
3. Verification Process - Answer security questions and verify email access
4. Temporary Unlock - We’ll temporarily disable 2FA for one login
5. Re-enable 2FA - Set up 2FA again with a new device

Account recovery typically takes 24-48 hours. Contact support immediately.

Best Practices

• Store recovery codes in a secure password manager
• Test recovery codes regularly
• Never share your TOTP secret or codes
• Use a reputable authenticator app
• Keep your device secure and updated