Your first login & MFA

Multi-factor authentication is required for every TENANT_ADMIN and ADMIN account on CargoSurge. This article covers the setup flow, the standard TOTP apps we support, and what happens when a user gets locked out.

Overview

CargoSurge uses TOTP (Time-based One-Time Passwords) — the same standard used by Google Authenticator, Authy, 1Password, and most enterprise password managers. SMS-based MFA is not supported: it's less secure and less reliable across regions.

First-login flow:

1. You enter email + password.
2. If MFA isn't set up yet, you're guided through setup before the app loads.
3. On every subsequent login, you'll enter a 6-digit code from your authenticator after the password.

When you'll be prompted for MFA

• Every fresh login on a new device or after cookie clearing.
• When you change your password.
• When your session hits its maximum age (currently 8 hours for admin roles, 24 hours for operator roles).

Once logged in on a device, the session cookie means you won't be prompted again until it expires.

Step-by-step — setting up MFA

1. 1
   Install a TOTP app on your phone. Recommended: 1Password, Authy, or Google Authenticator. Avoid password managers that don't support TOTP (some legacy tools don't).
2. 2
   Log in with your email and password. You'll see a QR code and a setup key.
3. 3
   Open your authenticator app and scan the QR code. If scanning doesn't work, paste the setup key manually.
4. 4
   Your app will now show a rotating 6-digit code for CargoSurge. Enter the current code on the login page.
5. 5
   CargoSurge shows you 8 backup codes. Copy them to a password manager or a secure note. You'll need one of them if you ever lose your phone — there's no other way to regain access without involving platform support.
6. 6
   Click Done. You're in.

Common pitfalls

Account lockout

To protect against password-guessing, CargoSurge locks an account after 5 consecutive failed login attempts in 15 minutes. The lock auto-releases after 15 minutes with no further attempts.

If you're locked out:

• Wait 15 minutes — the fastest path. No support action needed.
• Or ask another admin to reset your password from Settings → Users → Reset Password.
• Or use the Forgot Password flow from the login page if you have access to the email account.

Platform support can manually unlock an account as a last resort, but expect a short verification delay — see Login failures & account lockout for the full flow.

Disabling or resetting MFA

You can't disable MFA on a TENANT_ADMIN account while it's the only admin — one admin with MFA is the minimum security posture.

To reset (e.g. you got a new phone): Settings → Account Security → Reset MFA. This invalidates your existing authenticator and starts the setup flow again. Your backup codes are also regenerated.

For non-admin users, a TENANT_ADMIN can reset MFA on their behalf from Settings → Users → {user} → Reset MFA.