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

# Scopes

> Understand the Enginy MCP scope model, how scope ceilings work, and which endpoint families each scope unlock.

## How Enginy scopes work

Think of scopes as permission groups. They let an admin decide what an AI assistant is allowed to read or change in Enginy without reviewing every individual API route.

There are four important rules:

1. The workspace policy is the maximum permission limit.
2. A client can ask for all of that limit or only part of it.
3. Write permissions also include the matching read permissions.
4. `ALL` grants the full MCP surface.

<Tip>If a client requests no scopes at all, Enginy grants the current workspace policy ceiling.</Tip>

## Permission groups

| Scope group          | What it allows                                                                   | Example endpoint families                          |
| -------------------- | -------------------------------------------------------------------------------- | -------------------------------------------------- |
| `WORKSPACE_READ`     | Workspace metadata such as credits, saved views, filters, and validation helpers | credits, validation, saved views                   |
| `IDENTITIES_READ`    | Sender identities and identity performance                                       | identities, sender performance                     |
| `OWNERS_READ`        | CRM owner lookup for routing and task assignment                                 | owner lookup                                       |
| `CAMPAIGNS_READ`     | Read campaigns and folders                                                       | campaigns, campaign folders                        |
| `CAMPAIGNS_WRITE`    | Create and mutate campaigns                                                      | campaign create, clone, status, membership changes |
| `CONTACTS_READ`      | Read contacts, search results, and contact fields                                | contacts, contact fields                           |
| `CONTACTS_WRITE`     | Create and update contacts                                                       | contact create and update                          |
| `COMPANIES_READ`     | Read companies, search results, and company fields                               | companies, company fields                          |
| `COMPANIES_WRITE`    | Create and update companies                                                      | company create and update                          |
| `LISTS_READ`         | Read lists and list folders                                                      | lists, folders                                     |
| `LISTS_WRITE`        | Create or delete lists/folders and move members                                  | list create, add, move, delete                     |
| `AI_VARIABLES_READ`  | Read AI variables and AI variable folders                                        | AI variables, AI variable folders                  |
| `AI_VARIABLES_WRITE` | Create, update, and delete AI variables and folders                              | AI variable mutations                              |
| `ANALYTICS_READ`     | Read analytics exports and campaign analytics                                    | analytics exports, campaign analytics              |
| `ACTIONS_READ`       | Read action-run state                                                            | actions status                                     |
| `ACTIONS_WRITE`      | Start actions, AI Finder imports, and manage saved filters                       | actions create, AI Finder import, saved filters    |
| `MESSAGING_READ`     | Read inbox threads, tags, and conversation messages                              | inboxes, messages                                  |
| `MESSAGING_WRITE`    | Send replies and mutate thread state                                             | replies, tags, archive state                       |
| `WEBHOOKS_READ`      | Read webhook subscriptions and logs                                              | webhooks, webhook logs                             |
| `WEBHOOKS_WRITE`     | Create, update, delete, and test webhooks                                        | webhook mutations                                  |
| `WORKFLOWS_READ`     | Read advanced (graph) workflows, blocks, drafts, and runs                        | workflows, blocks, runs                            |
| `WORKFLOWS_WRITE`    | Create, edit, publish, delete, and run advanced workflows                        | workflow create, publish, run, cancel              |

## Write scopes imply read scopes

Enginy automatically expands write scopes to include the matching read scope:

| If you grant         | Enginy also grants  |
| -------------------- | ------------------- |
| `CAMPAIGNS_WRITE`    | `CAMPAIGNS_READ`    |
| `CONTACTS_WRITE`     | `CONTACTS_READ`     |
| `COMPANIES_WRITE`    | `COMPANIES_READ`    |
| `LISTS_WRITE`        | `LISTS_READ`        |
| `AI_VARIABLES_WRITE` | `AI_VARIABLES_READ` |
| `ACTIONS_WRITE`      | `ACTIONS_READ`      |
| `MESSAGING_WRITE`    | `MESSAGING_READ`    |
| `WEBHOOKS_WRITE`     | `WEBHOOKS_READ`     |
| `WORKFLOWS_WRITE`    | `WORKFLOWS_READ`    |

This is why a token can still satisfy read-only tools even if the original approval selected only the write side.

## How workspace policy and user approval fit together

<Steps>
  <Step title="An admin sets the workspace limit">
    The active MCP policy on the workspace defines the maximum permissions that may be granted.
  </Step>

  <Step title="The AI interface asks for permissions">
    A client can request an explicit subset, or omit scopes entirely and let Enginy grant the whole policy
    limit.
  </Step>

  <Step title="The user reviews what will be granted">
    The approval screen shows the permissions that will actually be granted after policy checks.
  </Step>

  <Step title="Enginy checks again later">
    Access tokens and refresh flows are validated against the current active policy, not only the original
    approval.
  </Step>
</Steps>

## Recommended starting policies

### Read-only exploration

Start here for general assistant workflows where the AI should look things up and summarize, but not make changes:

* `WORKSPACE_READ`
* `IDENTITIES_READ`
* `CONTACTS_READ`
* `COMPANIES_READ`
* `LISTS_READ`

### Campaign operations

Add these only if the AI should be allowed to change campaign state:

* `CAMPAIGNS_WRITE`
* `OWNERS_READ`

### Inbox or automation operations

Add these only for explicit automation or operator flows:

* `MESSAGING_WRITE`
* `ACTIONS_WRITE`
* `WEBHOOKS_WRITE`
* `WORKFLOWS_WRITE`

<Warning>
  `ALL` is convenient for internal testing but is usually the wrong default for production. Start narrow and
  expand only when a real workflow needs more access.
</Warning>