Concepts
Firms and users
Tenancy, roles, and how the platform isolates each firm from every other.
Firms
A firm is the unit of tenancy in the platform. Each firm has its own ledger chain, its own signing key, its own users, its own API keys, its own webhooks, and its own model registry. Nothing crosses the boundary. Multiple firms within a group each remain independent.
A firm is also the legal entity the FCA holds accountable. That is deliberate: the thing the regulator names and the thing the database keys on must be the same thing, otherwise the records cannot be used for evidence.
Users and roles
Three roles, each scoped to a single firm:
- FIRM_ADMIN, manages users, API keys, webhooks, settings, and the firm profile. May also act as a reviewer (including senior sign-off on jobs that require it).
- REVIEWER, reviews jobs in Review. Carries one or more professional qualifications used by the routing engine. Cannot manage firm settings.
- LEAD_REVIEWER, everything REVIEWER can do, plus senior sign-off on jobs flagged as requiring it (vulnerability cases or any job with
requiresSeniorSignOff: true).
Authorisation comes from the database, not the token
The platform uses Cognito for sign-in but never trusts it for authorisation. The role and firm membership stored on the JWT are ignored; every request looks up the user in the database by their Cognito ID and reads the canonical role from there. This is what makes role changes effective immediately and what stops a stolen token from granting privileges that have since been revoked.
Adding users
Firm admins invite users by email from the dashboard. Invited users receive a sign-in link, set their password on first sign-in (a password change is forced), and then have access scoped to the firm and role they were invited under.
SSO
Larger firms can plug the platform into their existing identity provider through SAML 2.0 or OIDC. Group claims map to the roles above. SCIM provisioning is supported for automatic deactivation when someone leaves the firm.