Scopes

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:

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

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

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

An admin sets the workspace limit

The active MCP policy on the workspace defines the maximum permissions that may be granted.

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.

The user reviews what will be granted

The approval screen shows the permissions that will actually be granted after policy checks.

Enginy checks again later

Access tokens and refresh flows are validated against the current active policy, not only the original approval.

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

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.

Getting started

Guides

Reference

How Enginy scopes work

Permission groups

Write scopes imply read scopes

How workspace policy and user approval fit together

Recommended starting policies

Read-only exploration

Campaign operations

Inbox or automation operations

​How Enginy scopes work

​Permission groups

​Write scopes imply read scopes

​How workspace policy and user approval fit together

​Recommended starting policies

​Read-only exploration

​Campaign operations

​Inbox or automation operations

How Enginy scopes work

Permission groups

Write scopes imply read scopes

How workspace policy and user approval fit together

Recommended starting policies

Read-only exploration

Campaign operations

Inbox or automation operations