Access & roles

In one line. How you control who can see and do what — users, Access Roles, and the stage gates they enforce. You’ll be able to. Add a user, build an Access Role, and gate a lifecycle stage to it. Where this lives. Studio ▸ Security (Users · Access Roles).

Why access control matters

A solution that works is only half-built; a solution other people can be trusted to run is finished. On this platform, access control does two jobs:

• Roles gate access. A Role (the platform’s RBAC unit) decides which buttons, fields, and Studio pages a user even sees — almost every control in Studio is hidden behind a role check (*botModulePermission). If a colleague “can’t see a button,” it’s nearly always a missing role grant, not a bug.
• Roles gate the lifecycle. The same roles decide who may act on a document at each stage of its review flow. This is how “AI recommends, two humans confirm” actually gets enforced (D3 · Taxonomy, lifecycle, tags & events).

The third leg — the immutable record of who did what — is the audit trail, covered in G5 · Audit & compliance.

Under the hood. Security lives under the permission section key 'security'. The footer + buttons and row-action menus on the Users and Access Roles surfaces only render for Subscription Admins or the Project Creator — if you don’t see them, you’re neither.

Users

Studio ▸ Security ▸ Users — the people who are in this project and the roles they hold. Users must already exist in the subscription; this page adds them to the project and assigns their roles.

The layout is a master/detail split: a menu panel lists every user (full name + email); selecting one fills the details panel on the right. The Access Roles page (below) uses the same split.

┌──────────────────────────┬──────────────────────────────────────────────┐
│  Users                   │   Amy Anderson                               │
│  ──────────────────────  │   ─────────────────────────────────────────  │
│  Amy Anderson            │   Full Name      Amy Anderson                │
│   amy@acme.com        <──┤   User Name      amy@acme.com                │
│  Bob Brown               │   Roles          L1-Reviewer, QA       (i)   │
│   bob@acme.com           │   Active         [ on ]                (i)   │
│  …                       │                                              │
│  ──────────────────────  │                                              │
│  [ + User ]              │                          [ Edit ]  [ Delete ]│
└──────────────────────────┴──────────────────────────────────────────────┘

What every control does

Control	What it does	Notes
Roles	The Access Roles this user holds.	Tooltip SUS03. Edit via Edit (or assign from a role’s own Users in Access Roles field).
Active toggle	Soft-activates/inactivates the user in this project (flips IsInactive).	Tooltip SUS04. A soft inactivate — not a hard delete.
+ User (footer)	Opens the Add User dialog to add someone to the project and pick their roles.	Gated ['security','Add User','Users']. Admin / Creator only.
Edit (row)	Re-opens the same dialog as Edit User.	Gated ['security','Edit','Users'].
Delete (row)	Removes the user from the project (confirm “Do you want to remove this user from the project?”).	Gated ['security','Delete','Users']. Hidden for Subscription Admins and the Project Creator — you can’t delete the people who own the project.

Walkthrough — add a user

1. Open Studio ▸ Security ▸ Users.
2. Click + User.
3. Enter the person’s email (they must exist in the subscription) and pick one or more Roles.
4. Save. The list refreshes and they appear with their roles.

Tip. You can leave a user role-less now and assign them later from Access Roles ▸ Users in Access Roles — handy when you’re building roles before you know who fills them.

Access Roles

Studio ▸ Security ▸ Access Roles — the core RBAC model, and the most important security surface. Everything else (stage gates, hidden buttons, document visibility) resolves against the roles you define here.

Same master/detail layout: a roles menu panel (role names) and a details panel showing the selected role’s Name, resolved Role Actions, Entities (chips), and User Emails (chips). You can deep-link a specific role with ?roleId=<id>.

The model in one paragraph

A Role = a Name + an Entity (collection) scope + a Stage scope + a set of capability Actions + Allowed Studio Pages + document/training/summary action grants + optional label/content filters. Two of those provide feature-level security (Actions and Studio Pages — the *botModulePermission gates), and the label/content filters provide row/label-level security (which documents and fields a role can even see). Saving a role updates the project’s roles in the shared signal, so Studio re-gates immediately.

The Add / Edit Role form

Click + Role to open the dialog. It has basic fields (always shown) and advanced fields (behind a Show Advanced Settings link):

Field	Layer	What it grants
Role Name*	basic	The role’s name.
Entity*	basic	The collection(s) the role applies to. Changing it filters the Stage list.
Stage	basic	Which lifecycle stages the role works in.
Users in Access Roles	basic	Assign users to this role here.
Select action(s) for this role	advanced	The core capability grant (AllowedActionIds).
Label selection	advanced	Which fields the role may train on.
Label Content Filter	advanced	Row-level filter — show only docs where a label = a value.
Training Icons	advanced	Which annotation tools the role sees.
Allowed Document Actions	advanced	Per-document operations allowed.
Allowed Studio Pages	advanced	Which Studio sections the role can open.
Allowed Summary Pane Actions	advanced	Lookup Update / Re-Group Summary.

This is a deliberately summarised view. The full field-by-field reference — every control, its help code, what it stores, and quick recipes — is R5 · RBAC permission reference. Read it before you build a real role.

How roles gate lifecycle stages

A lifecycle stage has a Can be viewed by setting (stored as ViewedByRoleIds). The roles you list there are the only roles that can see and act on documents resting in that stage (leave it empty and every role can). So gating a stage is a two-step move:

1. Create the role here (e.g. L1-Reviewer, Entity = your collection).
2. On the stage, set Can be viewed by = that role.

The seeded Four-Eyes flow ships exactly this L1-Reviewer / L2-Approver pattern: the L1 Review stage is gated to L1-Reviewer (the first human eye) and the L2 Approval stage — the final gate — to L2-Approver (the second eye). Two roles, two gated stages, four eyes before approval.

Watch out. Delete warns “Users and workflow stages mapped to this role (if any), will no longer exist…”. Deleting a role also removes it from any stage gate that referenced it — which can silently leave a stage with an empty ViewedByRoleIds (visible to everyone). Re-check your stage gates after deleting a role.

The Access Overview page

Admin ▸ General ▸ Access Overview answers the question audits always start with: who can get into what, right now? It is a subscription-level map of users and their access across projects — the place to review the whole surface at once rather than project by project. Each user is badged by how they sign in — SSO or Password — and a sign-in filter isolates exactly the password-only accounts, the question every SSO rollout ends on. It can also act: from a user’s detail pane, ⋮ ▸ Generate credentials… recovers a locked-out or bounced-invite user on the spot — email them a reset link, or share a one-time temporary password (shown once; their live sessions are killed). Use it for periodic access reviews and before offboarding; use Studio ▸ Security (above) to actually change grants inside a project.

Note. /admin itself no longer opens on a page catalogue — it lands on the Action Center, a self-clearing to-do list of setup gaps, incidents, and access risks (a last-admin-standing warning is one of its checks). The admin rail is three sections — General / Infrastructure / Utility — with Access Overview under General.

Try it yourself

Create an L1-Reviewer role and gate a review stage to it. (Assumes a Processing collection with a lifecycle — e.g. the one from UC · Invoice processing.)

1. Go to Studio ▸ Security ▸ Access Roles and click + Role.
2. Role Name = L1-Reviewer. Entity = your collection (e.g. Invoices).
3. Click Show Advanced Settings. Under Select action(s) for this role, grant the review actions a first-line reviewer needs; add the relevant Allowed Document Actions. Leave Allowed Studio Pages empty if this is a consumer-only reviewer.
4. Optionally add the user(s) under Users in Access Roles. Create.
5. Now go to Studio ▸ Data Model ▸ Lifecycle, edit your L1 Review stage, and set Can be viewed by = L1-Reviewer. Save.
6. Sign in as that user (or check the Inbox): documents at L1 Review are now visible and actionable only to L1-Reviewers (plus any other roles you listed). You’ve gated a lifecycle stage with RBAC.

Recap

• A Role is the RBAC unit: Name + Entity scope + Stage scope + capability Actions + Allowed Studio Pages + label/content filters — feature-level and row/label-level security.
• Users assigns people to roles; + User / Edit / Delete are Admin/Creator-gated, and the Active toggle is a soft inactivate.
• Roles gate lifecycle stages via Can be viewed by (ViewedByRoleIds); the seeded Four-Eyes flow is the L1-Reviewer / L2-Approver pattern.
• Deleting a role can silently un-gate a stage — always re-check stage gates after a delete.

Where to go next

• R5 · RBAC permission reference — the full Access Role permission matrix: every field, help code, stored key, and quick recipes.
• D3 · Taxonomy, lifecycle, tags & events — the stage model and Can be viewed by gating that roles plug into.
• G5 · Audit & compliance — the trail that proves who did what.
• G3 · Policy & guard rails — the soft-governance layer that sits on top of hard RBAC.