Roles & Permissions: Analyst to Superadmin

Quartyl’s access model is a five-role hierarchy. Each role is a scope of permission over studies, records and administration — and the study workflow’s transition table is built on it: a state only moves forward (or back) when the acting user holds a role that the transition allows. No permissions are granted ad hoc; what you can do is what your role is, inside your tenancy.

The five roles

Role	Scope	Day to day
Analyst	Study execution	Creates and configures studies, uploads and maps the dump, reads the comparables grid and the results, addresses rejections, re-runs failed studies and re-submits. It cannot override comparables, cannot approve, and the audit-trail views start one role above it
Manager	Review	Owns the In Review state: overrides comparables (accept or reject, with a reason), approves — which triggers the Excel workbook — or rejects with reasons. Also the role that carries study assignments (who analyses, who reviews)
Partner	Sign-off	Reviews and approves or rejects, requests the on-demand final document, signs the study off, archives it; holds the team-management console alongside the Firm Admin — including peer Partners — and the billing and audit-export views
Firm Admin	The firm	Team management (invites, roles, reports-to, revokes), firm settings and security — including the MFA mandate — billing and usage; acts across study states as the firm’s operator, except archiving. What the firm’s plan includes is assigned by the platform, not chosen here
Superadmin	The platform	Platform consoles — plans and their twelve feature flags, firms and their role scope, per-firm dump retention, study deletion, and the MFA recovery console. Study access is owner-scoped to the records they created, so another firm’s studies, records and API keys are never visible or actionable

Role assignment sits with the Partner and Firm Admin console: invited members are created with a role, and roles can be changed without re-inviting — within the firm’s role scope, which the platform sets for the tenant and which bounds which of Analyst, Manager and Partner may be created or assigned at all (Partner only, Partner + Manager, or all three). Firm Admin is not assignable there (it exists from provisioning), and the Superadmin role is platform-level, never part of a firm’s roster. Within the scope, a Partner may manage peer Partners. At least one active Superadmin must always remain on the platform.

What each role may do to a study

The workflow is a state machine; the table below is the permission map that drives it (system transitions run as the pipeline, not as a user):

Transition	Allowed roles
Draft → Study Initialized (kick off)	Any role in the firm: Analyst, Manager, Partner, Firm Admin (and Superadmin)
Study Initialized → Processing (start the run)	Any role in the firm (and Superadmin)
Processing → In Review	System (the analysis pipeline); no role may push it by hand
Processing → Draft (cancel the run)	Analyst, Firm Admin, Superadmin
In Review → Report Generated (approve)	Manager, Partner, Firm Admin, Superadmin
In Review → Rejected (send back, with reasons)	Manager, Partner, Firm Admin, Superadmin
Rejected → In Review (re-submit)	Analyst, Firm Admin, Superadmin
Failed → Processing (re-run)	Analyst, Firm Admin, Superadmin
Report Generated → Document Generated	System (the final-document task)
Document Generated → Signed Off	Partner, Firm Admin, Superadmin
Signed Off → Archived	Partner, Superadmin only

Two properties of the map are worth internalising:

• The Analyst can drive a study from creation to re-submission but cannot approve it. The review gate (In Review → Report Generated) is, by design, a different person’s role — the separation between the person who built the analysis and the person who accepted it.
• Archiving is the narrowest gate in the system. It is hardcoded to Partner and Superadmin: the Firm Admin who operates every other late step cannot archive, and once a study is Archived no role can transition it again.

Three gates are not state transitions, and they sit on different roles:

• Comparables overrides — Manager, Firm Admin or Superadmin, and only while the study is In Review. An Analyst cannot move a row. Every override is written to the audit log, and a row changed under you since you loaded it fails the write with a conflict rather than overwriting the other reviewer.
• The final-document request — Partner, Firm Admin or Superadmin, from In Review onwards once results exist. It builds the Word master report and the branded PDF from the same recorded context; the PDF is best-effort, so a missing PDF is a missing file, not a failed study.
• Study assignment — the analyst and manager recorded on a study are set by Manager, Firm Admin or Superadmin. Assignment is a review-time decision about who owns the next step, not a permission grant.

MFA mandates by role

Multi-factor authentication is role-bound, not per-user:

• Superadmin and Firm Admin: mandatory, always. These accounts must enrol and cannot disable MFA — the mandate cannot be loosened by the firm.
• Analyst, Manager, Partner: per the firm’s security settings. The Firm Admin can make MFA mandatory firm-wide, or for those specific roles, in the firm security settings. Outside a mandate, enrolment is optional and you can turn it off again yourself.

An unenrolled user who is mandated is not refused at the door: sign-in issues a session flagged as needing enrolment, and the app carries them straight into the enrolment wizard. Until enrolment completes, only the MFA setup, profile, session-refresh and sign-out calls are served — every other request is refused, so the gap cannot be used to read firm data.

The full mechanics — TOTP setup, recovery codes, rate limits — are in sign-in and MFA.

Plan features, in one line

Roles define who can do what; plan features define what exists at all for the tenancy. Twelve capability keys are catalogued — among them user management, firm settings, the predictive risk engine, the evidence repository, API access, white-label branding and priority support — and the platform assigns them per plan. Without the feature, the entry point is not shown in the workspace at all: the restriction is structural, not a locked button, and the server-side plan check stays the actual boundary.

Limitations to know

• A Firm Admin cannot grant the Superadmin role, and neither Superadmin nor Firm Admin is assignable from the team console at all. Role changes apply to the member going forward — actions already taken stand under the role they were taken under.
• The workflow transitions above are the complete set, and they are the same for every firm — there is no per-firm approval gate configuration. A study that has reached its target state can only move to the one state the map allows from there; anything else is rejected as an invalid transition.
• Past sign-off there is no edit-in-place: an Archived study cannot be transitioned by any role, and its record stands as approved. A corrected analysis is a new study.
• All permission-relevant events — who acted, on which study, under which role, and the result — are written to the audit trail. Reading it is itself a permission: Manager and above can view it, Partner and above can export it, and only Firm Admin and above can administer it.

FAQ

Can a user hold two roles? No — each member of a tenancy holds exactly one role at a time. The workflow is designed around that: a person who is a Manager reviewing their own analyst-built study is a conflict the single-role model removes.

What does “owner-scoped” mean for the Superadmin? A Superadmin is normally a platform account without a firm of its own, so the tenant filter cannot apply to it — instead its study access follows ownership: the studies (and API keys) it created. The scope is the creator, not a tenancy: another firm’s data is simply not visible or actionable.

If a study is stuck, who can unstick it? It depends on the state: a run stuck in Processing can be cancelled back to Draft by the Analyst, a Firm Admin or a Superadmin; a Failed study is re-run by that same set; a study in In Review is approved or rejected by a Manager, Partner, Firm Admin or Superadmin. The state name on the study tells you which row of the table applies — and for a study that needs archiving, only a Partner or the platform can do it.