# User Roles & Permissions

Capsule authorizes every request against a set of **permissions**. Roles are simply named bundles of permissions that you assign to users. Capsule ships built-in system roles and lets you define your own custom roles when the built-in ones do not match how your team is organized.

## How access works

- Each permission is a single capability, such as "view sessions" or "manage integrations".
- A role is a named set of permissions. System roles have fixed permission sets; custom roles have whatever set you choose.
- A user can hold **more than one role**. Their effective access is the **union** of every permission granted by every role they hold, so adding a role can only widen access, never narrow it.
- Permissions are resolved per request from the roles the user holds in that tenant. Role and permission changes take effect on the user's next request - no sign-out or re-invite required.
- Roles are scoped to a tenant. A user who belongs to several tenants can hold different roles in each.


## System roles

The four built-in roles cover the common split between platform ownership, security operations, passive stakeholders, and legal review. They cannot be edited or deleted.

| Role | Manage integrations | Manage users & settings | View security findings | View private conversation content |
|  --- | --- | --- | --- | --- |
| **Owner** | ✅ | ✅ | ✅ | All sessions |
| **Admin** | ✅ | ❌ | ✅ | Flagged sessions only |
| **Viewer** | ❌ | ❌ | ✅ | Always hidden |
| **Legal Discovery** | ❌ | ❌ | ✅ | All sessions |


### Owner

Full administrative access. Owner holds **every permission in the catalog**. Use this role for platform owners.

### Admin

Access to all security findings and detections, with privileged visibility into **flagged sessions** - those with an active policy violation, issue, or detection. Private conversation content remains hidden on sessions that have not been flagged.

Admins can also manage the **Integration center**: connect a new platform, apply configuration, test a connection, trigger a sync, enable or disable an integration, and remove one. They cannot manage users, roles, policies, or the remaining tenant settings - those stay with Owners. This is the recommended role for SOC analysts and security investigators who own platform onboarding.

### Viewer

Read-only access to dashboards, posture, agent inventory, and aggregated metrics. Conversation content is always hidden. Use this role for stakeholders who need awareness without operational responsibilities.

### Legal Discovery

Read-only access with full visibility into **all session content** - private conversation messages and tool input/output across every session, not just flagged ones. Legal Discovery users cannot manage users, configure integrations or policies, or take response actions. Use this role for legal and e-discovery reviewers who must read complete session content for investigations or legal holds without gaining operational control.

## Custom roles

A custom role is a name, an optional description, and any combination of permissions from the catalog below.

Examples:

- A compliance reviewer who needs the audit log and nothing else.
- An automation owner who needs `inventory:sync` and `service_accounts:manage` without session access.
- A detection engineer who needs `policies:write` and `triage:write` but must never read conversation content.


### Managing custom roles

1. Go to **Settings → Roles**.
2. Click **New Role**, give it a name and description, then select its permissions.
3. Use **Edit** on an existing role to rename it or change its permission set, and **Delete** to retire it.


Creating, editing, and deleting custom roles requires the `roles:manage` permission. Viewing the role list requires `roles:read`.

### Rules and limits

- Up to **100 custom roles** per tenant.
- Role names must be **unique within the tenant** and at most 64 characters.
- Editing a role's permissions **replaces** the whole set rather than merging with the previous one.
- Changes to a role apply immediately to every user holding it, on their next request.
- Deleting a role removes it from the users who hold it. Make sure those users still hold another role that covers what they need.


## Assigning roles

1. Go to **Settings → Users**.
2. Click **Add user**, enter the email and name, then select one or more roles.
3. To change an existing assignment, open the user's row and click **Edit**.


The user dialog shows a live **granted permissions** preview: the merged permission set produced by the roles you have selected. Use it to confirm the result before saving, especially when combining a system role with a custom one.

Assigning or changing roles requires the `users:manage` permission, which by default only Owner holds.

## Permission reference

Permissions are grouped the same way they appear in the role editor.

### Users and access

| Permission | Grants |
|  --- | --- |
| `users:read` | View users and their assigned roles. |
| `users:manage` | Invite, edit, and remove users and assign their roles. |
| `roles:read` | View custom roles and the permissions they grant. |
| `roles:manage` | Create, edit, and remove custom roles and their permissions. |
| `service_accounts:read` | View service accounts and their API keys. |
| `service_accounts:manage` | Create, rotate, and remove service accounts and their API keys. |


### Organization

| Permission | Grants |
|  --- | --- |
| `org:manage_sso` | Configure single sign-on and organization identity settings. |
| `settings:read` | View organization and tenant settings. |
| `settings:manage` | Edit organization and tenant settings. |
| `audit:read` | Read the administrative audit log. |


### Sessions

| Permission | Grants |
|  --- | --- |
| `sessions:read` | View agent session metadata: participants, timing, counts, and timelines. |
| `sessions:read_content` | View the full content of agent sessions, flagged or not. |
| `sessions:read_flagged_content` | View the content of sessions that have been flagged for review. |


`sessions:read` controls whether the session list and session pages open at all. The two content permissions control what is visible **inside** a session; see [Redaction behavior](#redaction-behavior).

### Detections and findings

| Permission | Grants |
|  --- | --- |
| `findings:read` | View resource findings. |
| `detections:read` | View detections. |
| `triage:write` | Apply triage verdicts to detections and findings. |
| `resources:flag` | Flag resources for review. |
| `policies:write` | Create, edit, and remove policies. |


### Inventory

| Permission | Grants |
|  --- | --- |
| `inventory:sync` | Trigger inventory synchronization. |


### Integrations

| Permission | Grants |
|  --- | --- |
| `integrations:manage` | Connect, configure, and remove platform integrations. |
| `notifications:manage` | Configure notification integrations and channels. |


## Redaction behavior

Session content permissions work by **redaction**, not by blocking the page. A user with `sessions:read` can always open a session and see who was involved and what happened; the sensitive parts are replaced when they lack the matching content permission.

Identity fields - user email and user IDs - remain visible so investigations can still attribute activity to the right person.

| Content permissions held | What the user sees |
|  --- | --- |
| None | Metadata only; all conversation content redacted. |
| `sessions:read_flagged_content` | Content of flagged sessions; everything else redacted. |
| `sessions:read_content` | Content of all sessions. |