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

# Roles and access grants

> Create custom roles from the permission catalog, grant roles to users and teams for the whole organization or single resources, and share resources with another organization.

A role is a named set of permissions. A member receives a role for the whole workspace under
[Users](https://docs.molesignal.com/en-US/identity/members.md#users). An access grant gives a user or a team a role for the whole
organization or for selected resources, optionally until a date. Open **Identity & Access → Roles**
or **Access grants**.

## Roles

**Roles** lists the built-in and the custom roles of the workspace, with the number of permissions of
each and where it is used: members, tokens, invitations, and bindings. Built-in roles are read only.
See [Built-in roles](https://docs.molesignal.com/en-US/identity#built-in-roles).

To create a custom role:

1. Select **New role**.
2. Enter a **Key** of lowercase letters, digits, and underscores. It cannot change later.
3. Enter a **Name** and a **Description**.
4. Optionally choose a **Permission template** as a starting point, then add or remove permissions.
   Each permission shows what it allows.
5. Select **Create role**.

| Template | Permissions |
| - | - |
| **Read-only observer** | Reads observability data, dashboards, alerts, schedules, saved views, pipelines, functions, and reports. |
| **Data analyst** | Explores observability data, and creates dashboards and saved views. |
| **Pipeline developer** | Reads observability data, and manages streams, pipelines, and functions. |
| **Alert administrator** | Reads observability data, and manages alert rules and schedules. |
| **Organization administrator** | Manages organization settings, members, roles, access grants, and API tokens. |

Select a custom role to change it. **Delete** removes a custom role only while nothing uses it: no
membership, token, invitation, or binding. Reading roles requires `iam.roles.read`, and changing them
requires `iam.roles.manage`.

## Access grants

An access grant is a role binding: a role for a principal, in an organization, over a scope of
resources. Use one when access should follow a person, a team, or a resource, instead of widening a
broad role.

1. Open **Access grants** and select **New access grant**.
2. **Principal**: choose a **User** or a **Team**, and select it.
3. **Organization**: the current workspace, shown for reference.
4. **Resource scope**: **Entire organization**, or a resource type (**Dashboard** or **Stream**) with
   one resource or **All resources of this type**.
5. **Role and permissions**: the role that the grant gives.
6. **Constraints**: optionally an **Environment** that requests must match exactly, such as `prod`,
   and an **Expires at** time.
7. Select **Create grant**.

**Delete** ends a grant at once. Reading grants requires `iam.policies.read`, and creating or
deleting them requires `iam.policies.manage`.

## Share resources across organizations

A cross-organization share gives another organization access to selected resources of this one. It
is explicit and not transitive: it applies only to the chosen organization and resources, and is
never inherited or passed on.

1. In **Access grants**, select **Share across organizations**.
2. Choose the **Target organization**.
3. Choose the resource type and the resource: a **Dashboard**, or a **Stream**.
4. Choose the permissions: `dashboards.read` and `dashboards.edit` for a dashboard, `streams.read`
   and `streams.query` for a stream.
5. Optionally set **Expires at**, then select **Create share**.

The share starts as **Pending acceptance**. An administrator of the target organization selects
**Accept** in its own **Access grants**, and the share becomes **Active**. Either side can **Revoke**
it. Creating, accepting, and revoking shares requires `iam.policies.manage`.

## Permission reference

Every permission of the catalog, what it allows, and the built-in roles that hold it. Custom roles
combine any organization permissions.

### Platform

| Permission | Allows | Built-in roles |
| - | - | - |
| `sys.administrators.manage` | Add or remove platform-level administrators. | Owner, `platform_owner` |
| `sys.dashboards.read` | Open and view read-only dashboards in the system organization. | Owner, `platform_owner` |
| `sys.organizations.manage` | Create, update, and administer organizations across the platform. | Owner, `platform_owner` |
| `sys.settings.manage` | Change settings that affect the entire platform. | Owner, `platform_owner` |
| `sys.telemetry.manage` | Configure collection and retention for platform telemetry. | Owner, `platform_owner` |
| `sys.telemetry.read` | Read the platform's own logs, metrics, and traces. | Owner, `platform_owner` |
| `sys.trace_debug.manage` | Enable and configure platform trace debugging. | Owner, `platform_owner` |

### Organization and access

| Permission | Allows | Built-in roles |
| - | - | - |
| `api_tokens.manage` | Create and revoke API tokens. | Owner, Admin |
| `api_tokens.read` | View API token metadata and status. | Owner, Admin |
| `audit.read` | View security and administrative audit events. | Owner, Admin |
| `iam.policies.manage` | Create and revoke role bindings and cross-organization grants. | Owner, Admin |
| `iam.policies.read` | View organization and resource access grants. | Owner, Admin |
| `iam.roles.manage` | Create, update, and delete custom roles. | Owner, Admin |
| `iam.roles.read` | View built-in and custom roles. | Owner, Admin |
| `org.members.manage` | Invite, update, disable, and remove organization members. | Owner, Admin |
| `org.members.read` | View members, teams, and invitations. | Owner, Admin |
| `org.settings.manage` | Change settings for the current organization. | Owner, Admin |
| `org.settings.read` | View settings for the current organization. | Owner, Admin |
| `service_accounts.manage` | Create service accounts with an initial bound API token, and update, disable, or delete those identities. | Owner, Admin |
| `service_accounts.read` | View service account identity, role, and status. | Owner, Admin |

### Data

| Permission | Allows | Built-in roles |
| - | - | - |
| `apm.deploy` | Report deployments with `POST /api/v1/apm/deployments`. | Owner, Admin, Editor, `intake` |
| `apm.manage` | Change service definitions, key transactions, error states, SLOs, and other APM settings. | Owner, Admin, Editor |
| `rum.manage` | Change the state, the team and the owner of the issues RUM errors are grouped into. | Owner, Admin, Editor |
| `rum.write` | Write only to RUM session, action, error, and replay receivers. | Owner, Admin, Editor, `rum_client` |
| `saved_views.create` | Create saved query views. | Owner, Admin, Editor |
| `saved_views.delete` | Delete saved query views. | Owner, Admin, Editor |
| `saved_views.edit` | Update existing saved query views. | Owner, Admin, Editor |
| `saved_views.read` | Open saved query views. | Owner, Admin, Editor, Viewer |
| `streams.configure` | Change stream schema, index, and retention settings. | Owner, Admin, Editor |
| `streams.create` | Create new data streams. | Owner, Admin, Editor |
| `streams.delete` | Permanently delete data streams. | Owner, Admin, Editor |
| `streams.query` | Query logs, metrics, traces, APM User Experience, and profiles stored in streams. | Owner, Admin, Editor, Viewer |
| `streams.read` | View stream definitions, schemas, and runtime status. | Owner, Admin, Editor, Viewer |
| `streams.write` | Intake data into existing streams. | Owner, Admin, Editor, `intake` |

### Dashboards and reports

| Permission | Allows | Built-in roles |
| - | - | - |
| `dashboards.create` | Create and import dashboards. | Owner, Admin, Editor |
| `dashboards.delete` | Permanently delete dashboards. | Owner, Admin, Editor |
| `dashboards.edit` | Change existing dashboards. | Owner, Admin, Editor |
| `dashboards.read` | Open and view dashboards. | Owner, Admin, Editor, Viewer |
| `dashboards.share` | Share dashboards with another organization. | Owner, Admin, Editor |
| `reports.create` | Create report definitions. | Owner, Admin, Editor |
| `reports.delete` | Delete report definitions and schedules. | Owner, Admin, Editor |
| `reports.edit` | Edit report definitions. | Owner, Admin, Editor |
| `reports.read` | View generated and scheduled reports. | Owner, Admin, Editor, Viewer |
| `reports.schedule` | Create and change report schedules. | Owner, Admin, Editor |
| `reports.share` | Create, rotate, and revoke restricted report share credentials. | Owner, Admin, Editor |

### Alerts and reliability

| Permission | Allows | Built-in roles |
| - | - | - |
| `alerts.acknowledge` | Acknowledge and resolve alert incidents. | Owner, Admin, Editor |
| `alerts.manage` | Create, edit, mute, and delete alert rules. | Owner, Admin, Editor |
| `alerts.read` | View alert rules, incidents, and history. | Owner, Admin, Editor, Viewer |
| `alerts.silence` | Silence active incidents and manage mute windows. | Owner, Admin, Editor |
| `postmortems.manage` | Create and update incident postmortems. | Owner, Admin |
| `postmortems.read` | View incident postmortems and their evidence. | Owner, Admin |
| `schedules.manage` | Create and edit notification and on-call schedules. | Owner, Admin, Editor |
| `schedules.read` | View notification and on-call schedules. | Owner, Admin, Editor, Viewer |
| `service_levels.manage` | Create and update service-level policies. | Owner, Admin |
| `service_levels.read` | View service-level policies and their current attainment. | Owner, Admin |
| `status_pages.manage` | Create and manage status pages, events, subscribers, domains, and private access. | Owner, Admin |
| `status_pages.publish` | Publish synthetic failure and recovery updates to linked status pages. | Owner, Admin |
| `status_pages.read` | View status page configuration, components, events, and history. | Owner, Admin |
| `synthetics.locations.manage` | Create private probe locations and register or revoke Probe Agents. | Owner, Admin |
| `synthetics.manage` | Create, edit, run, pause, and archive synthetic checks. | Owner, Admin |
| `synthetics.read` | View synthetic checks, revisions, locations, and execution results. | Owner, Admin |
| `synthetics.secrets.manage` | Create and rotate write-only encrypted values used by synthetic checks. | Owner, Admin |

### Pipelines and functions

| Permission | Allows | Built-in roles |
| - | - | - |
| `functions.create` | Create processing and enrichment functions. | Owner, Admin, Editor |
| `functions.delete` | Delete processing functions. | Owner, Admin, Editor |
| `functions.edit` | Change existing processing functions. | Owner, Admin, Editor |
| `functions.read` | View processing and enrichment functions. | Owner, Admin, Editor, Viewer |
| `functions.run` | Test and run processing functions. | Owner, Admin, Editor |
| `pipelines.create` | Create intake pipelines. | Owner, Admin, Editor |
| `pipelines.delete` | Delete intake pipelines. | Owner, Admin, Editor |
| `pipelines.edit` | Change pipeline definitions and schedules. | Owner, Admin, Editor |
| `pipelines.pause` | Pause or resume scheduled pipelines. | Owner, Admin, Editor |
| `pipelines.read` | View intake pipelines and their runs. | Owner, Admin, Editor, Viewer |
| `pipelines.run` | Run pipelines manually. | Owner, Admin, Editor |

### Mole Agent

| Permission | Allows | Built-in roles |
| - | - | - |
| `agent.approve` | Approve protected actions proposed by agent workflows. | Owner, Admin |
| `agent.automations.manage` | Create, change, switch, delete and run Mole Agent automations, and manage their API tokens. | Owner, Admin, Editor |
| `agent.manage` | Configure agent providers, tools, and policies. | Owner, Admin |
| `agent.use` | Use assisted investigation and analysis features. | Owner, Admin, Editor, Viewer |
| `inspections.manage` | Create, change, pause, delete and run scheduled log inspections. | Owner, Admin, Editor |

## Roles and grants API

| Operation | Endpoint | Permission |
| - | - | - |
| List the permission catalog | `GET /api/v1/iam/permissions` | `iam.roles.read` or `iam.policies.read` |
| List roles | `GET /api/v1/roles` | `iam.roles.read` |
| Create a custom role | `POST /api/v1/roles` | `iam.roles.manage` |
| Update a custom role | `PATCH /api/v1/roles/{id}` | `iam.roles.manage` |
| Delete an unused custom role | `DELETE /api/v1/roles/{id}` | `iam.roles.manage` |
| List or create access grants | `GET /api/v1/iam/role-bindings`, `POST /api/v1/iam/role-bindings` | `iam.policies.read`, `iam.policies.manage` |
| Delete an access grant | `DELETE /api/v1/iam/role-bindings/{id}` | `iam.policies.manage` |
| List or create cross-organization shares | `GET /api/v1/iam/cross-org-grants`, `POST /api/v1/iam/cross-org-grants` | `iam.policies.read`, `iam.policies.manage` |
| Accept or revoke a share | `POST /api/v1/iam/cross-org-grants/{id}/accept`, `POST /api/v1/iam/cross-org-grants/{id}/revoke` | `iam.policies.manage` |


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