Security Settings: MFA Mandates and Access Controls

The Security tab is where a firm sets its access policy: who must use multi-factor authentication and how long the audit record is kept. It is policy, not per-user switches — the mandate applies to roles, and the role does the rest. The block stores five fields, but the tab edits three of them and only some of them change how the product behaves; the table below is honest about which is which, because a policy you believe is on and is not is worse than no policy.

What the block holds

Field	Default	Allowed	What it does today
Session timeout	30 minutes	15, 30, 60 or 120 minutes	Stored and validated. Nothing reads it: session length is the platform’s access-token lifetime, not this number
Firm-wide MFA mandate	Off	on/off master toggle	Resolved at sign-in — see the enforcement note below
MFA-enforced roles	none	any of Analyst, Manager, Partner	Resolved at sign-in, but not on the tab: it is set through the firm-settings API only
IP whitelist	empty (no restriction)	IP addresses or CIDR blocks, validated on save	Stored and validated. Nothing consults it — not sign-in, not API traffic
Audit retention	7 years	5, 7 or 10 years	Read by the evidence/retention service for the firm’s records

The tab renders three controls — the session timeout select, the MFA master toggle and the audit retention select — and saves them as a complete Security block. That matters: the two fields it does not render are reset to empty by every save from the tab, not carried over. If you maintain a per-role MFA list or an IP list through the API, re-send it in the same PATCH (or re-apply it afterwards), and do not let the tab be the last writer.

These five fields are the whole per-firm security surface. There is no per-firm password-complexity policy, no per-firm session length, and no enforceable network restriction.

The MFA policy, in resolution order

Multi-factor authentication in Quartyl is free TOTP (RFC 6238) — authenticator apps only, no SMS. Whether an account is mandated is resolved in a fixed order:

1. Superadmin and Firm Admin: always mandatory. These roles are mandated by the platform itself, regardless of firm settings — and they can never disable MFA.
2. The firm-wide mandate. When the master toggle is on, every role in the tenant is subject to MFA.
3. The per-role list. Analyst, Manager and Partner can be individually mandated (the Superadmin and Firm Admin tiers are already mandatory and cannot appear in this list).

How far that reaches is not uniform, and you should know the difference. The tier-1 mandate is a server rule: every authenticated request from an unenrolled Superadmin or Firm Admin account is refused with a 403 until enrolment completes, whatever the client claims. The tier-2 and tier-3 mandates are resolved at sign-in: the login succeeds and the session carries an enrolment flag that drives the MFA enrolment wizard (QR plus the one-time recovery codes), but the per-request server gate does not re-apply the firm policy to those roles. Treat the firm-wide mandate as onboarding discipline plus the role mandate, not as a server-side lock.

• Each enrolment issues 10 single-use recovery codes (three four-character groups, from an ambiguity-free alphabet with no 0/O/1/I/L). They are shown exactly once, at enrolment, and the UI makes the user confirm they are saved before enabling MFA. Only their hashes are stored server-side.
• Losing the device is not self-service. There is no backdoor into the code step: an enrolled user without their authenticator redeems a recovery code, or — if the codes are gone too — the platform superadmin runs the MFA recovery, which clears the TOTP secret and the recovery codes, turns MFA off so the user must re-enrol, sets the password the superadmin supplies, and bumps the token version so every outstanding session for that account dies. The user re-enrols at the next sign-in. Both actor and target are logged.
• Rate limits apply where codes are guessable. The TOTP setup, verify and disable endpoints and the password step are rate-limited, so aggressive retries get 429s, not in. The external API-key surface is not rate-limited — see Developer Console.

Access-control context

The Security tab is the policy layer under the role model. Both reading and saving it require the tenant’s firm_settings plan feature (see Plan Features), and the guard sits on the server, not just the sidebar.

• Roles decide what an authenticated user may do — the five-role hierarchy from roles and permissions, with the Superadmin scoped to their own firm’s data (owner-scoped) rather than the whole platform.
• The IP whitelist is stored and its entries validated as IPs or CIDR blocks at save time — and nothing in the request path reads it. A non-empty list is a declaration, not a control. Do not present it to your auditors as a network restriction.
• Session length today comes from the platform, not this tab. An access token lives 30 minutes and is exchanged through the refresh token; the workspace refreshes silently while you are working and, if the token expires while the tab is idle, shows a continue-or-log-out prompt. The session timeout field on the block records your intended policy; it does not change the token lifetime.
• Audit retention sets the retain-until date computed for each study (its lock date, else its last update, plus the years selected), which the evidence repository surfaces as retained, expiring soon or expired. It does not shorten or purge the audit trail.
• Every security-relevant event is logged — logins, failed code attempts, MFA enable/disable, recoveries, consent re-acceptances — in the access and security logs, where the firm can review who did what, when, and from where.

FAQ

Can a Firm Admin turn off MFA for themselves? No — the Superadmin and Firm Admin mandates are platform-level and cannot be disabled, per-user or per-firm.

If I enable the master MFA toggle, are my analysts locked out? No — they get a session plus the enrolment wizard on sign-in, and the mandate is re-applied each time they sign in. Note that the server-side 403 gate described above covers the Superadmin and Firm Admin tiers, not firm-policy mandates on other roles.

Does the IP whitelist cover API key traffic? It covers nothing yet. No code path reads the list, so it restricts neither sign-in nor machine traffic on API keys, which authenticate by the key alone and are stamped to the access ledger.

Does saving the tab wipe values I set through the API? Yes, for the two fields it does not render. Send them in the same PATCH when you need them to survive.