How to Enable Two-Factor Authentication

Two-factor authentication (2FA) adds a TOTP-based second factor — the kind of code generated by an authenticator app — on top of the password every user already has. Atender supports it two ways: a tenant owner can require it for their own workspace, or a superadmin can require it for every superadmin account regardless of any tenant’s own setting. Either way, once required, users who haven’t enrolled are blocked from the app until they do.

Turning on the policy for your tenant

If you’re an owner, the requirement is a tenant-level policy:

1. Go to Settings → 2FA.
2. In the Require two-factor authentication card, turn on Enabled.
3. Confirm with Turn it on. There is no separate save step — the change is written as soon as you confirm.

From that point, every member of the tenant — including you — must have a TOTP authenticator enrolled to keep using the app. There’s no grace period or “enroll within N days”; the check runs on the next authenticated request.

This setting can still be read by an owner who is currently blocked for not being enrolled yet — that exemption only keeps the read and write pair symmetric, since a blocked user never reaches Settings anyway. Changing it, however, always requires being past the block yourself.

Superadmin-enforced policy

A superadmin can also turn on Require 2FA for superadmins, which requires every superadmin account to use TOTP regardless of any tenant’s own toggle. It covers superadmin accounts only — it does not switch 2FA on for a tenant’s own members. The tenant policy above is the only switch for those, though a superadmin can set that policy for a tenant on the owner’s behalf. The same enrollment flow and the same blocking screen apply either way.

If a superadmin is impersonating a tenant to help with support, they’re held to the same rule: if the enforcement is on, the superadmin’s own session needs its own second factor first. Impersonating someone doesn’t borrow their exemption.

Enrolling a TOTP authenticator app

Once 2FA is required — for your tenant or org-wide — each user enrolls individually:

1. Open an authenticator app on your phone (any standard TOTP app works — the kind that generates a rotating 6-digit code).
2. In Atender, go to the two-factor enrollment screen (this is what you land on automatically if the requirement is on and you’re not yet enrolled — see below).
3. Scan the QR code (or enter the setup key manually) in your authenticator app.
4. Enter the code the app generates to confirm the pairing.

Once confirmed, your session is treated as fully verified and you can use the app normally. If you ever need to re-enroll — say, you got a new phone — you can remove the old factor and add a new one from the same screen, as long as you’re not left with zero factors while the policy is on.

What happens if you haven’t enrolled

If the requirement is on and you haven’t set up an authenticator app, Atender blocks you at the app shell level: instead of your workspace, you land on a screen asking you to enroll. You can’t dismiss it or work around it by navigating elsewhere — every authenticated route behaves the same way until you enroll.

A couple of things stay reachable even while you’re blocked, on purpose, so the block doesn’t lock you out of clearing itself:

• Your own account info still loads (needed to render the enrollment screen at all).
• The enrollment/verification exchange itself, obviously.

What does not stay reachable is the policy setting itself in a way that would let you turn the requirement off from a blocked, password-only session. If you’re blocked, the way out is to enroll — not to disable the policy.

Recovering from a lost device or lockout

If a user loses the device their authenticator app was on, they can’t generate new codes and are stuck at the enrollment/verification screen. There are two ways out:

• Remove the lost factor and re-enroll. An owner or admin can reset the user’s 2FA enrollment from Settings → Users with Reset 2FA, clearing the old factor so the user is asked to set up an authenticator app again the next time they sign in.
• Superadmin-mediated recovery. Because superadmins can act on a tenant regardless of that tenant’s own 2FA state, support can step in to reset a locked-out user’s factor even if the whole tenant is currently blocked. The superadmin doing the rescuing must be enrolled themselves if enforcement applies to them too — so recovery depends on at least one enrolled admin existing somewhere in the chain.

There’s no self-service “I lost my phone, let me back in” flow that bypasses a second factor entirely — by design, since that would be the same hole 2FA is meant to close. If you’re locked out, contact an owner/admin or Atender support rather than trying to work around the block.

Removing your own last factor

You can remove an authenticator app from your own account at any time. If 2FA is required for you and it’s your only confirmed factor, no remove button is offered for it — the row reads Required by your organization instead. An unconfirmed factor never counts as that last one and stays removable. That guard is in the UI only, not a server-side lock: if the factor does go away, the very next request lands you back on the enrollment screen, and the block is the intended outcome, not a bug.

Current scope limits

A few things worth knowing before you treat 2FA as covering every door into the app:

• Enrollment is web-only, and the mobile app asks for a code at sign-in. If a user is covered by a workspace or superadmin 2FA requirement, mobile sign-in takes two calls instead of one: POST /api/mobile/auth/login answers with mfaRequired, a factorId and a single-use challengeToken and no tokens, and POST /api/mobile/auth/login/verify exchanges that challenge plus the six-digit code for tokens. POST /api/v1/auth/login and POST /api/v1/auth/login/verify are the same pair for the v1 namespace, and a challenge expires after 5 minutes. A user who hasn’t set up an authenticator app yet can’t do it here — login answers MFA_ENROLLMENT_REQUIRED and they have to enroll in the web app first. Mobile session refresh, workspace switching, mobile /me, /api/v1/auth/me and other /api/v1 requests made with a token minted before the requirement was turned on are refused with MFA_REQUIRED until the user signs in again and answers the challenge.
• 2FA is a login/session requirement, not a per-action step-up (yet). There’s currently no “step up for this specific sensitive action” flow — enrollment and verification happen once per session, the same way password auth does.

If your security requirements depend on 2FA covering mobile app access or mobile-token API requests, those surfaces are covered: a covered user can’t get a mobile or /api/v1 token without answering a TOTP code, and a token issued before the requirement was turned on stops working until they sign in again. Setting the authenticator app up in the first place still has to happen in the web app.