Permission scopes
Every HTTP route and every MCP tool checks one scope. Both interfaces enforce the same one, because both run the same handler.
Auth0 grants scopes through Edge roles on the token. A token missing the required scope gets 403 with a message naming what was needed. Users with no Edge role receive no Edge scopes.
The scopes
These are the strings Edge checks today:
| Scope | Allows |
|---|---|
namespace.read | List the workspaces your organization has |
distribution.read | List and read distributions; check slug availability; run redirect and header checks; export redirects |
distribution.write | Create, update and copy distributions; import redirects |
distribution.destroy | Delete a distribution |
deployment.read | List and read deployments, diff two of them, list and read published files, list schedules |
deployment.write | Create and commit deployments, write and delete files on a pending one |
deployment.promote | Promote a deployment now or on a schedule, roll back, take down and restore, cancel schedules, invalidate the cache |
document.read | Read data objects, including MCP-only version history |
document.write | Write, delete and roll back data objects |
domain.read | List and read domains |
domain.manage | Create, verify, attach and detach domains |
domain.destroy | Delete a domain |
analytics.read | Query analytics, explore paths, read realtime visitors, properties and distribution health |
goals.read | List, read and check conversion goals |
goals.write | Create, update and archive conversion goals |
funnels.read | List groups and funnels, validate definitions and query results |
funnels.write | Create and update groups; create, update and archive funnels |
properties.write | Declare, update and archive analytics properties |
pii.read | Read PII detectors, effective policy and detection reports |
pii.policy.write | Change PII policy and grant or revoke property exemptions |
logs.read | Read request logs |
access.read | Read visitor access rules, network rules, and sign-outs |
access.write | Change visitor access rules and network rules, and sign visitors out |
function.read | List and inspect function runtimes, invoke them and read their logs |
function.write | Create, update and delete function runtimes |
cron.read | List crons and read their runs |
cron.write | Create, update, pause, run now and delete crons |
queue.read | List queues, read their stats and runs, and peek at messages |
queue.write | Create, update, pause, purge, redrive and delete queues |
queue.send | Send messages to queues, and nothing else |
workflow.read | List workflow runs and read their steps |
workflow.write | Start, signal, cancel and retry workflow runs |
webhook.read | List and read webhook subscriptions and their deliveries |
webhook.write | Create, update, test, rotate, redeliver and delete webhook subscriptions |
hook.read | List and read hooks and their receipts |
hook.write | Create, update and delete hooks |
form.forward | Subscribe a webhook to form submissions (form.*), in addition to webhook.write |
submission.read | Read every form submission and uploaded file in the workspace, and the access log of those reads |
token.admin | List and revoke every personal access token in the organization |
Naming
Scope strings use Edge's internal names, which do not always match the words used in these docs. In particular, the scope for workspace access is namespace.read, not workspace.read; data objects use document.read / document.write, not endpoint.read; function runtimes use function.read / function.write. Send the string exactly as written above.
Do not send data.read or data.write. Those names are retired.
Standard roles
Roles are presets in Auth0. If a person has more than one Edge role, their scopes are combined. The scope check on each operation remains authoritative.
| Role | Granted for |
|---|---|
edge:member | Console reads only |
edge:publisher | Agent publishing plus functions, goals, funnels and properties. No domains, PII or destroy |
edge:manager | Member + publisher + domain manage, webhooks, hooks and reading form submissions. No destroy, PII, form forwarding, or token administration |
edge:admin | Publisher + destroy, all domain scopes, PII, webhooks, hooks, reading form submissions, form forwarding, and token administration |
Capability matrix
Rows are grouped by who can do the work, so the gaps between roles sit next to each other. A missing scope still returns 403 even if the row says yes — the check on the operation is authoritative.
Everyone can read the workspace, distributions, deployments, analytics and logs. Publisher then adds authoring. Manager adds domain manage (and keeps member's domain read, which publisher does not have). Admin adds destroy and PII.
| Capability | Scopes | member | publisher | manager | admin |
|---|---|---|---|---|---|
| Read workspaces | namespace.read | yes | yes | yes | yes |
| Read distributions | distribution.read | yes | yes | yes | yes |
| Read deployments and published files | deployment.read | yes | yes | yes | yes |
| Read analytics | analytics.read | yes | yes | yes | yes |
| Read request logs | logs.read | yes | yes | yes | yes |
| Read visitor access | access.read | yes | — | yes | yes |
| Change visitor access and sign visitors out | access.write | — | — | yes | yes |
| Read custom domains | domain.read | yes | — | yes | yes |
| Create, update and copy distributions | distribution.write | — | yes | yes | yes |
| Create, commit and patch deployments | deployment.write | — | yes | yes | yes |
| Promote, schedule, take down, roll back and invalidate | deployment.promote | — | yes | yes | yes |
| Read and write data objects | document.read, document.write | — | yes | yes | yes |
| Author goals | goals.read, goals.write | — | yes | yes | yes |
| Author funnels | funnels.read, funnels.write | — | yes | yes | yes |
| Declare properties | properties.write | — | yes | yes | yes |
| Manage function runtimes | function.read, function.write | — | yes | yes | yes |
| Read crons and their runs | cron.read | yes | yes | yes | yes |
| Create, change, run and delete crons | cron.write | — | yes | yes | yes |
| Manage queues and their messages | queue.read, queue.write | — | yes | yes | yes |
| Send messages to queues | queue.send | — | yes | yes | yes |
| Read workflow runs | workflow.read | yes | yes | yes | yes |
| Start, signal, cancel and retry workflow runs | workflow.write | — | yes | yes | yes |
| Attach and manage domains | domain.manage | — | — | yes | yes |
| Manage webhooks and hooks | webhook.read, webhook.write, hook.read, hook.write | — | — | yes | yes |
| Read form submissions and uploaded files | submission.read | — | — | yes | yes |
| Delete a distribution | distribution.destroy | — | — | — | yes |
| Delete a domain | domain.destroy | — | — | — | yes |
| Read and change PII policy | pii.read, pii.policy.write | — | — | — | yes |
| Forward form submissions to a webhook | form.forward | — | — | — | yes |
| Manage everyone's access tokens | token.admin | — | — | — | yes |
Every role can create, list and revoke its own personal access tokens; that needs no scope. A token carries only scopes its creator has, and never token.admin.
Admin is not “member plus everything”: it is built from publisher, then destroy, domains and PII. domain.read is on the admin preset, so admin still reads domains. Publisher tokens may still carry health.read; Edge does not check that string — files use deployment.read / deployment.write, and health uses analytics.read.
Working out what you are missing
- Publishing is not promoting.
deployment.writebuilds a deployment and publishes its preview. Making it live needsdeployment.promote. - Destroying is always separate.
distribution.destroyanddomain.destroyare not implied by write or manage. - There is no content scope. A deployment's files are covered by
deployment.readanddeployment.write, even though the tools areedge_content_*and the path is/v1/deployments/{id}/content. - Domains are not on publisher.
domain.readis on member (and admin).domain.manageis on manager and admin. If publishing works but domain calls return 403, this is why. - Data objects are on publisher. Mapping
/_apiusesdistribution.write. Function runtimes usefunction.read/function.write, also on publisher (and therefore manager and admin). - Logs are not analytics.
analytics.readdoes not grantlogs.read. Both are on member, publisher, manager and admin. - Reading conversions is not authoring them.
analytics.readshows conversion results in the console. Creating goals, funnels or properties needsgoals.write,funnels.writeorproperties.write— publisher, manager and admin in the standard roles. - PII policy is administrative.
pii.policy.writeis admin only. - Form data needs its own yes.
webhook.writecovers every event except form submissions. Subscribing toform.*also needsform.forward(admin only), and the request must carry"confirm": true. - Reading submissions is its own scope.
submission.readcovers every form submission and uploaded file in the workspace — visitor personal data. Manager and admin have it. A personal access token carries it only when its creator picks it: it is in no preset, and creating the token shows a personal-data warning. Agent and token reads are capped per day and logged; see Let an agent read form submissions.