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

# Roles & Permissions

> Roles, the permission matrix, and per-member permission overrides.

Every member of an organization has a role. Each role grants a fixed set of permissions. Every permission is a `resource:action` pair, such as `policies:write`. On plans with role-based access control (`rbac`) you can also adjust a single member's permissions on top of their role.

## Roles

| Role | Intended for |
| - | - |
| Owner | Full control, including billing and deleting the organization. |
| Admin | Everything except billing and organization deletion. |
| Developer | Builds and runs integrations: policies, sessions, MCP servers, connections, API keys. Read-only on alerts and AI systems. |
| CISO | Governance and compliance: policies, sessions, incidents and alerts, compliance, reports, HIPAA, SOC 2 export, AI systems. Read-only on connections and servers. |
| Auditor | Read-only access, plus SOC 2 export. |

<Note>
  On Starter and Growth, only the Owner and Admin roles can be assigned. Assigning Developer, CISO or Auditor requires a plan with `rbac` (Scale and Enterprise). Inviting or changing a role without it returns `403` from the auth endpoints, with the plan error JSON inside the `message` string. See [Limits & errors](/reference/limits-and-errors#plan-errors).
</Note>

## Permission matrix

"Yes" means the role holds the permission by default.

| Permission | Owner | Admin | Developer | CISO | Auditor |
| - | - | - | - | - | - |
| `team:manage` | Yes | Yes | - | - | - |
| `team:members` | Yes | Yes | - | - | - |
| `team:billing` | Yes | - | - | - | - |
| `team:delete` | Yes | - | - | - | - |
| `member:create` | Yes | Yes | - | - | - |
| `member:update` | Yes | Yes | - | - | - |
| `member:delete` | Yes | Yes | - | - | - |
| `invitation:create` | Yes | Yes | - | - | - |
| `invitation:cancel` | Yes | Yes | - | - | - |
| `policies:read` | Yes | Yes | Yes | Yes | Yes |
| `policies:write` | Yes | Yes | Yes | Yes | - |
| `sessions:read` | Yes | Yes | Yes | Yes | Yes |
| `sessions:write` | Yes | Yes | Yes | Yes | - |
| `servers:read` | Yes | Yes | Yes | Yes | Yes |
| `servers:write` | Yes | Yes | Yes | - | - |
| `api-keys:read` | Yes | Yes | Yes | - | - |
| `api-keys:write` | Yes | Yes | Yes | - | - |
| `connections:read` | Yes | Yes | Yes | Yes | Yes |
| `connections:write` | Yes | Yes | Yes | - | - |
| `observe:read` | Yes | Yes | Yes | Yes | Yes |
| `alerts:read` | Yes | Yes | Yes | Yes | Yes |
| `alerts:manage` | Yes | Yes | - | Yes | - |
| `audit:read` | Yes | Yes | Yes | Yes | Yes |
| `comply:read` | Yes | Yes | - | Yes | Yes |
| `comply:generate` | Yes | Yes | - | Yes | - |
| `reports:read` | Yes | Yes | - | Yes | Yes |
| `reports:generate` | Yes | Yes | - | Yes | - |
| `hipaa:read` | Yes | Yes | - | Yes | Yes |
| `hipaa:write` | Yes | Yes | - | Yes | - |
| `soc2:export` | Yes | Yes | - | Yes | Yes |
| `sso:manage` | Yes | Yes | - | - | - |
| `settings:read` | Yes | Yes | - | Yes | - |
| `settings:write` | Yes | Yes | - | - | - |
| `ai-systems:read` | Yes | Yes | Yes | Yes | Yes |
| `ai-systems:write` | Yes | Yes | - | Yes | - |

## What each permission unlocks

| Resource | `read` / view | Action |
| - | - | - |
| `team` | n/a | `manage` and `members` for team management, `billing` for the Billing & Plan tab (Owner only), `delete` for deleting the organization. |
| `member`, `invitation` | n/a | Invite, change, remove members and cancel invitations. |
| `policies` | See policies and detectors. | `write` creates and edits them. |
| `sessions` | See agent sessions. | `write` changes sessions. |
| `servers` | See MCP servers. | `write` manages them. |
| `connections` | See connections. | `write` creates, edits and rotates credentials. |
| `api-keys` | See API keys. | `write` creates and revokes keys. |
| `observe` | See dashboards. | None. |
| `alerts` | See incidents and alerts. | `manage` handles incidents and alert webhooks (for example, rotating a webhook signing secret). |
| `audit` | See the audit trail. | None. |
| `comply`, `reports`, `hipaa` | See compliance, reports and HIPAA. | `comply:generate`, `reports:generate` and `hipaa:write` produce documents and records. |
| `soc2` | n/a | `export` exports SOC 2 evidence. |
| `sso` | n/a | `manage` configures SSO. |
| `settings` | See organization settings. | `write` changes them. |
| `ai-systems` | See the AI system inventory. | `write` edits it. |

A request without the needed permission gets `403` with `{ "error": "Forbidden", "required": "resource:action" }`.

## API keys

An API key acts as the member who created it, with that member's current effective permissions. If you change the creator's role or permissions, their keys change with them. If the creator is removed from the organization, their keys stop working.

## Per-member overrides

Overrides let you grant extra permissions to one member, or take some away, without changing their role. They require a plan with `rbac`.

### What you can customize

| Area | View | Actions |
| - | - | - |
| Dashboards | `observe:read` | none |
| Audit trail | `audit:read` | none |
| Incidents & alerts | `alerts:read` | `alerts:manage` |
| Policies & detectors | `policies:read` | `policies:write` |
| Connections | `connections:read` | `connections:write` |
| MCP servers | `servers:read` | `servers:write` |
| Sessions | `sessions:read` | `sessions:write` |
| API keys | `api-keys:read` | `api-keys:write` |
| AI systems | `ai-systems:read` | `ai-systems:write` |
| Compliance | `comply:read`, `reports:read`, `hipaa:read` | `reports:generate`, `hipaa:write`, `soc2:export` |
| Org settings | `settings:read` | `settings:write` |

Team management, billing, SSO and organization deletion are not customizable. They stay tied to the role.

### Rules

* An override is a list of grants and a list of revokes applied on top of the role.
* An action implies its view. Granting `policies:write` also grants `policies:read`. Revoking a view removes the actions that depend on it.
* The Owner's permissions can't be customized. Overrides on an Owner are rejected.
* You can't change your own permissions.
* You can only grant what you hold yourself. Anything a change newly gives the member, including role defaults, must already be in your effective permissions.
* Changing a member's role clears their overrides.
* If your plan loses `rbac`, existing overrides stay enforced, but you can only clear them.

### In the dashboard

Set overrides when you invite a member, or later through **Edit permissions** on the member's row in **Settings → Team**. Members with overrides show a **Customized** badge.

### API

`PATCH /api/v1/members/:userId/permissions` requires `member:update` (Owner and Admin by default).

```bash theme={null}
curl -X PATCH https://api.igrisecurity.com/api/v1/members/USER_ID/permissions \
  -H "Authorization: Bearer ig_..." \
  -H "Content-Type: application/json" \
  -d '{ "grants": ["connections:write"], "revokes": ["api-keys:write"] }'
```

Both `grants` and `revokes` are required arrays (up to 64 strings each). Send two empty arrays to clear overrides. The request is normalized to the smallest difference from the role. The response is:

```json theme={null}
{
  "data": {
    "grants": ["connections:read", "connections:write"],
    "revokes": ["api-keys:write"],
    "permissions": ["alerts:read", "..."]
  }
}
```

| Status | When |
| - | - |
| `400` | Body fails schema validation. |
| `403` | You lack `member:update`; the target is yourself or the Owner; a permission isn't customizable; you'd grant something you don't hold; or the plan has no `rbac`. |
| `404` | The member doesn't exist in your organization. |
| `409` | The member's role changed while you were editing. Reload and retry. |

### Audit

Every override change is recorded as an `access_change` audit event, with the actor, target, role, and the before and after grants and revokes. The event `kind` is `invite`, `edit` or `role_change` (when a role change clears overrides). See [Audit trail](/monitor/audit-trail).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.