Two-Factor Authentication
Protect a CargoLint account with a TOTP authenticator app and single-use recovery codes, in the app or through the API.
Setting up 2FA
Two-factor authentication (2FA) adds a second step to signing in: after your password, or after signing in with Google or Microsoft, CargoLint asks for a code from an authenticator app. CargoLint uses TOTP (time-based one-time passwords): six-digit codes that change every 30 seconds.
2FA is set per user. Each person turns it on for their own account.
In the app
- Open Profile and find Two-Factor Authentication under Security.
- Click Enable 2FA.
- Scan the QR code with your authenticator app, or copy the secret into it by hand.
- Enter the six-digit code from the app to verify it.
- Save the 8 recovery codes shown (Copy All Codes copies them), then confirm that you saved them.
CargoLint sends an email when 2FA is turned on.
Through the API
These endpoints take a user’s token (Authorization: Bearer {token}).
# Step 1: get a secret and a QR code
curl https://api.cargolint.com/api/v1/auth/2fa/setup \
-H "Authorization: Bearer YOUR_JWT"
The response contains secret (base32, for manual entry) and qrCodeDataUrl (the QR code as a PNG data URL).
# Step 2: confirm with a code from the authenticator app
curl -X POST https://api.cargolint.com/api/v1/auth/2fa/enable \
-H "Authorization: Bearer YOUR_JWT" \
-H "Content-Type: application/json" \
-d '{ "totpCode": "123456" }'
The response lists your 8 recovery codes in recoveryCodes. They are shown once.
Signing in with 2FA
When 2FA is on, POST /auth/login returns twoFactorRequired: true and a tempToken, valid for 5 minutes, instead of a session token. Sign-in with Google or Microsoft asks for the code too. Send the code with the temporary token:
curl -X POST https://api.cargolint.com/api/v1/auth/2fa-challenge \
-H "Authorization: Bearer TEMP_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "totpCode": "123456" }'
Send { "recoveryCode": "..." } instead to use a recovery code. A valid code returns the session token. Failed attempts are recorded in the audit log, and five wrong codes in a row lock the account for 15 minutes, as wrong passwords do.
In the app, the sign-in page offers Authenticator Code and Backup Code tabs.
Trusted browsers
On the authenticator tab, Trust this browser for 30 days lets a password sign-in from that browser skip the code until then. Your password is always asked; only the second step is skipped, and only on that browser. A recovery code never trusts a browser. The trust also applies when you sign in with Google or Microsoft from the same browser.
The trust lives in a cookie that scripts cannot read and that is sent only to the sign-in endpoints; CargoLint keeps a hash of it, never the value. It ends after 30 days, is not extended by use, and is removed when you change or reset your password, turn off two-factor authentication, or forget the browser. Profile > Security > Trusted browsers lists each one with when it was trusted and last used, with Forget and Forget all. Trusting a browser and forgetting one are recorded in the audit log as user.device_trusted and user.device_forgotten.
Through the API, send "rememberDevice": true with the code; the response sets the cookie. GET /auth/trusted-devices lists them, DELETE /auth/trusted-devices/{id} forgets one and DELETE /auth/trusted-devices forgets all.
Supported authenticator apps
Any app that supports TOTP works, for example Google Authenticator, Microsoft Authenticator, Authy, 1Password and Bitwarden. Codes are generated on your device. CargoLint accepts the current code and the one just before or after it, to allow for small clock differences.
Recovery codes
You receive 8 single-use recovery codes when you turn 2FA on. Each works once, in place of an authenticator code. CargoLint stores only a hash of each code.
Profile > Security shows how many unused codes you have left. To get a new set, which invalidates the old one, click Create new backup codes there and enter an authenticator code, or call:
curl -X POST https://api.cargolint.com/api/v1/auth/2fa/recovery-codes/regenerate \
-H "Authorization: Bearer YOUR_JWT" \
-H "Content-Type: application/json" \
-d '{ "totpCode": "123456" }'
Checking 2FA status
curl https://api.cargolint.com/api/v1/auth/2fa/status \
-H "Authorization: Bearer YOUR_JWT"
Returns enabled and unusedRecoveryCodeCount.
Disabling 2FA
In the app: Profile > Security > Disable 2FA, then confirm with your password, or with an authenticator code when the account has no password. Through the API:
curl -X POST https://api.cargolint.com/api/v1/auth/2fa/disable \
-H "Authorization: Bearer YOUR_JWT" \
-H "Content-Type: application/json" \
-d '{ "password": "your-current-password" }'
Disabling needs your account password. An account that signs in only with Google or Microsoft has no CargoLint password, so it sends { "totpCode": "123456" } with a current authenticator code instead. CargoLint sends an email when 2FA is turned off.
Losing your authenticator
- Use a recovery code at the sign-in prompt (Backup Code tab). Then set up the authenticator again: turn 2FA off and on with the new device.
- No recovery code left? Write to support@cargolint.com from the email address of your account.
Audit trail
Turning 2FA on or off, regenerating recovery codes, using a recovery code and failed 2FA attempts are all recorded in your organization’s audit log.
Best practices
- Keep recovery codes in a password manager or another safe place away from your phone.
- Never share your TOTP secret or codes.
- Keep your authenticator device locked and up to date.