Roles & Permissions

Every Talonic workspace controls what people can do with permissions. Each role carries a default set, and any member can be given their own set that differs from their role. This page describes the model for workspace owners and for the IT security teams who review it.

Permissions are configured on the Team Members page (user menu, then Team Members) in two grids. Role permissions set what each role can do by default. Member permissions show what each person can actually do and let you change it for one person. Both grids are visible only to members holding Team & access; other members neither see them nor receive the data from the API.

Reading workspace data is not a permission: every active member can open the documents and results their role's visibility allows. Which documents a member sees is decided separately, by compartments, collections and source access rules, and Admins see every document regardless of permissions. Talonic Apps have their own per-app access and are not governed by these permissions.

Role defaults

• Viewer: Export.
• Member (shown as Contract Management): Export, Upload & sources, Edit & review, Run pipelines.
• Senior Member (shown as Senior Contract Management): Member permissions plus Complex review.
• Admin: all ten permissions.

These are the built-in defaults, and every workspace starts with them. Ticking or clearing a box in Role permissions changes the default for that role in your workspace only, and applies at once to every member of the role who has no permissions of their own. Restore default returns a role to the built-in set. Defaults can both widen and narrow a role: a workspace can let Viewers manage billing, or keep Admins away from data retention.

Per-member permissions

Changing a box in Member permissions gives that person their own set, marked Custom. From then on their permissions no longer follow role defaults, including after a role change. Use role default removes the custom set and returns them to their role.

How enforcement works

Permissions are enforced by the Talonic API, not by the browser. Every protected route names the permission it requires, and the global authorization guard admits a request only when the caller holds it, whatever their role. A refused request returns 403 with the error code INSUFFICIENT_PERMISSIONS and a message naming the missing permission. A write route that names no permission stays closed to every customer member. The web app hides controls the caller cannot use for convenience only.

The guard resolves a member's permissions from the database on every request, not from the session token: first the member's own set, then the workspace's default for their role, then the built-in default. A change therefore takes effect on the member's next request, with no sign-out. Connecting a mailbox or drive re-checks the permission against the member's real membership, so a Talonic employee viewing a workspace cannot connect sources in it. Workspace API keys are separate: they carry their own scopes and are not governed by member permissions.

Privilege escalation controls

• Only Team & access manages permissions. Editing role or member permissions, inviting, approving, re-roling and removing members all require Team & access.
• Grant only what you hold. A member can tick or clear only permissions they hold themselves, in both grids.
• No acting on someone more powerful. A member can change the role or permissions of, remove, or reset the password or two-factor authentication of another member only when that member's permissions are a subset of their own, before and after the change.
• No promotion beyond yourself. Inviting someone into a role, approving a joiner, or moving a member to a role is refused when that role would hold a permission the acting member lacks.
• No self-service. Nobody changes their own role or their own permissions.
• Lockout protection. The workspace always keeps at least one active member holding Team & access. Any change that would leave none, in either grid or by role change or removal, is refused.

Audit trail

Every change is written to the platform security log: team.role_permissions_changed records the workspace, role, previous and new set, and the acting member; team.member_permissions_changed records the affected member, their custom set (or its removal), their resulting effective permissions, and the acting member. Every request the authorization guard refuses is logged as security.rbac_denied with the user, method, path and reason. Role changes, removals and credential resets keep their existing log events.

API

The Team Members page uses these endpoints with the signed-in member's session; all three require Team & access. Sending null as permissions restores the built-in default for a role, or returns a member to their role's default.

GET /team/role-permissions

PUT /team/role-permissions/viewer
Content-Type: application/json

{ "permissions": ["export", "billing"] }

PATCH /team/members/{userId}/permissions
Content-Type: application/json

{ "permissions": ["team", "data"] }

{
  "user_id": "3f1c9a2e-6b0d-4e7a-9c55-1d2e8f4a7b10",
  "permissions": ["team", "data"],
  "custom_permissions": true
}

For an access review, GET /team/members called by a member holding Team & access returns every member with their role, effective permissions and custom_permissions. Together with GET /team/role-permissions it gives a point-in-time record of who can do what in the workspace.