> ## Documentation Index
> Fetch the complete documentation index at: https://docs.alforse.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Roles & Permissions

> How tenant roles, module permissions, and workflow controls fit together.

Tenant permissions have two independent layers. Keep them separate when reasoning about "can
this user do X":

1. **Module permissions** — can this user view or edit a given area of the product at all?
2. **Workflow controls** — can this user advance *this specific contract* from its current
   workflow stage?

A user can have edit access to contracts as a module and still be blocked from moving a locked
contract forward, and vice versa.

## Membership, role, and subject scope

Every tenant user has exactly one `Membership` per tenant, which points at one `Role` and
carries a `subjectScope`:

* `subjectScope: "all"` — the member can act across every subject company in the tenant.
* `subjectScope: "<subjectId>"` — the member is restricted to one subject company.

Tenant admins define roles per tenant. The seeded starting roles are `admin`, `director`,
`lead`, `finance`, `sales`, and `viewer`; tenant admins can also create custom role codes.

## Module permissions

Each role has a permission level per module: `none`, `view`, or `edit`. The API enforces this
server-side on every request via a route-level `@Perm(module, level)` requirement — a `view`-only
member calling an `edit`-only endpoint gets rejected regardless of what the UI shows.

| Module            | Governs                                                                                                                                            |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `contract_view`   | Reading the contract list, contract detail, saved views, contract configuration catalog, and the AI gateway inspection endpoint                    |
| `contract_edit`   | Creating/updating contracts, imports, OCR extraction review, notes, terms, fulfillment tasks, and workflow stage transitions                       |
| `contract_delete` | Deleting contracts and bulk-delete                                                                                                                 |
| `export`          | CSV export of contracts                                                                                                                            |
| `payment_entry`   | Viewing and recording payments, receipts                                                                                                           |
| `invoice`         | Recording invoice evidence, on both contracts and payments                                                                                         |
| `collection`      | Collections list/preview and sending reminders                                                                                                     |
| `custom_fields`   | Reading dynamic field definitions                                                                                                                  |
| `sensitive_data`  | Analytics (summary, cashflow, distribution)                                                                                                        |
| `admin`           | Tenant administration, contract-type/lifecycle configuration, dynamic-field commands, audit log access, calendar integration, and workflow locking |

Manage this matrix from the tenant console (`apps/console`) or directly via
`PATCH /tenant-admin/roles/:code/permissions` — see
[Tenant Administration](/api-reference/tenant-admin).

## Workflow controls

Separately, each role has a `WorkflowControl` level that governs contract lifecycle actions:
`none`, `view`, `edit`, `approve`, `sign`, or `admin`. Locked contracts block core-field edits
unless a role with a sufficiently privileged workflow control unlocks them. Manage this via
`PATCH /tenant-admin/roles/:code/workflow-controls`.

## System roles are separate from tenant roles

Tenant roles only govern tenant workspace and administration actions. System-level service roles
are separate and are not part of the public tenant administration model. A tenant `admin` can
manage their own organization, but cannot bypass tenant data boundaries.