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

# Roles and permissions

> The admin and viewer roles and the scope model.

Access in Anyreach is controlled by **scopes**, not by a single role flag. Each member of an organization is assigned an organization role, that role grants a set of scopes, and every protected action checks for one of the scopes it needs. The dashboard reads the caller's scopes and hides any control they cannot use, so a member only ever sees what their role permits.

There are two interactive roles you assign to people: `admin` and `viewer`. `admin` carries the full scope set; `viewer` carries read-only scopes. You pick one of these when you invite a member or change their role.

<Note>
  Roles are the package; scopes are the actual permissions. Two members with the same role always have the same scopes. This page documents the scope catalog so you can reason about exactly what each role can do.
</Note>

## Roles

| Role     | Intent                                                                     | Typical scopes                                                                                      |
| -------- | -------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| `admin`  | Full control of the organization, its members, billing, and all resources. | Every `*:manage`, `members:manage`, `billing:manage`, `organizations:manage`, plus all read scopes. |
| `viewer` | See conversations and resources without changing anything.                 | The `*:read` scopes (and `conversations:read`), without `manage`, `dial`, or `billing:manage`.      |

Only `admin` and `viewer` appear in the role picker when you invite or update a member. See [Members and invitations](/organizations/members-and-invitations) for how to assign them.

## How scope gating works

Scopes are checked in two layers:

```text theme={null}
member  →  role (admin | viewer)  →  scopes  →  endpoint / UI control
```

* **Backend.** Each endpoint declares the scope(s) it accepts. A request succeeds only if the caller's token carries at least one of them; otherwise it is rejected with `403`.
* **Frontend.** The dashboard fetches your scopes and renders a control only when you hold a matching scope. Missing the scope hides the button or page rather than showing a disabled state. Pages that require a scope you lack show a no-access fallback.

You can read your own scopes for the current organization from the admin API:

```bash theme={null}
curl https://api.anyreach.ai/admin/members/me/scopes \
  -H "Authorization: Bearer <token>" \
  -H "X-Anyreach-Org: <organization_id>"
```

This returns the flat list of scope strings granted to you in that organization. Any authenticated member can call it for themselves; reading another member's scopes requires `members:read` or `members:manage`.

## Organization-administration scopes

These scopes gate the account, members, and billing surfaces. They live in the admin service.

| Scope                        | Grants                                                                |
| ---------------------------- | --------------------------------------------------------------------- |
| `members:read`               | View the member list and a member's scopes.                           |
| `members:manage`             | Invite, remove, and change roles for members. Implies `members:read`. |
| `billing:manage`             | View and manage billing, plans, and usage.                            |
| `organizations:manage`       | Manage organization settings.                                         |
| `child_organizations:manage` | Create and manage child organizations.                                |
| `resources:manage`           | Manage organization-level resources.                                  |
| `email_sequences:read`       | View email sequences.                                                 |
| `email_sequences:manage`     | Create and edit email sequences.                                      |

<Info>
  `members:manage` and `billing:manage` are admin-only. A `viewer` can list members with `members:read` but cannot invite, remove, or re-role anyone, and cannot open billing.
</Info>

## Resource scopes

Every product area exposes its own permissions through the API service. Most areas follow a `read` versus `manage` split: `read` lets you view, `manage` lets you create, edit, and delete. Conversations add finer-grained scopes for sensitive data and for placing calls.

### Conversations

| Scope                          | Grants                                               |
| ------------------------------ | ---------------------------------------------------- |
| `conversations:read`           | List and view conversations and their basic data.    |
| `conversations:read_sensitive` | See redacted/sensitive fields within a conversation. |
| `conversations:manage`         | Create, update, and delete conversations.            |
| `conversations:dial`           | Place outbound calls.                                |

The split between `conversations:read` and `conversations:read_sensitive` controls who can see protected fields. See [Permissions and data access](/conversations/permissions-and-data-access) for what each level exposes.

### Telephony and agents

| Area                    | Read scope                     | Manage scope                     |
| ----------------------- | ------------------------------ | -------------------------------- |
| Trunks                  | `trunks:read`                  | `trunks:manage`                  |
| Phone numbers           | `phone_numbers:read`           | `phone_numbers:manage`           |
| Agents                  | `agents:read`                  | `agents:manage`                  |
| Agent versions          | `agent_versions:read`          | `agent_versions:manage`          |
| Web widgets             | `web_widgets:read`             | `web_widgets:manage`             |
| Inbound routing configs | `inbound_routing_configs:read` | `inbound_routing_configs:manage` |
| Managed accounts        | `managed_accounts:read`        | `managed_accounts:manage`        |
| Concurrency             | `concurrency:read`             | `concurrency:manage`             |

### Email

| Area            | Read scope             | Manage scope             |
| --------------- | ---------------------- | ------------------------ |
| Email addresses | `email_addresses:read` | `email_addresses:manage` |
| Email domains   | `email_domains:read`   | `email_domains:manage`   |
| Unsubscribes    | `unsubscribes:read`    | `unsubscribes:manage`    |

### Assessments, workflows, knowledge base, and campaigns

| Area                                    | Read scope                 | Other scopes                            |
| --------------------------------------- | -------------------------- | --------------------------------------- |
| Assessments (metrics, scorecards, runs) | `assessments:read`         | `assessments:manage`                    |
| Workflows                               | `workflows:read`           | `workflows:manage`, `workflows:execute` |
| Workflow executions                     | `workflow_executions:read` | `workflow_executions:read_sensitive`    |
| Datasets                                | `datasets:read`            | `datasets:query`, `datasets:manage`     |
| Sources                                 | `sources:read`             | `sources:manage`                        |
| Dataset sources                         | `dataset_sources:read`     | `dataset_sources:manage`                |
| Campaigns                               | `campaigns:read`           | `campaigns:manage`                      |

<Note>
  `assessments:read` and `assessments:manage` cover the evaluation suite — metrics, scorecards, scorecard runs, and assessment results — under a single read/manage pair at the API.
</Note>

## How scopes reach a request

The role and its scopes are resolved differently depending on how you authenticate:

* **Dashboard users** sign in and receive a token bound to the organization they have open. Their scopes come from the `admin` or `viewer` role assigned to them in that organization.
* **User personal access tokens** (`pat_`) act as the user, so they carry the user's scopes for the organization named in the required `X-Anyreach-Org` header.
* **Organization API keys** (`ak_`) carry their organization implicitly and are granted scopes when the key is created.

See [Authentication](/api-reference/authentication) for the full token model.

<CardGroup cols={2}>
  <Card title="Members and invitations" icon="users" href="/organizations/members-and-invitations">
    Invite people and assign the admin or viewer role.
  </Card>

  <Card title="Conversations data access" icon="lock" href="/conversations/permissions-and-data-access">
    What the sensitive-read scope exposes.
  </Card>
</CardGroup>