Skip to content

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:

ScopeAllows
namespace.readList the workspaces your organization has
distribution.readList and read distributions; check slug availability; run redirect and header checks; export redirects
distribution.writeCreate, update and copy distributions; import redirects
distribution.destroyDelete a distribution
deployment.readList and read deployments, diff two of them, list and read published files, list schedules
deployment.writeCreate and commit deployments, write and delete files on a pending one
deployment.promotePromote a deployment now or on a schedule, roll back, take down and restore, cancel schedules, invalidate the cache
document.readRead data objects, including MCP-only version history
document.writeWrite, delete and roll back data objects
domain.readList and read domains
domain.manageCreate, verify, attach and detach domains
domain.destroyDelete a domain
analytics.readQuery analytics, explore paths, read realtime visitors, properties and distribution health
goals.readList, read and check conversion goals
goals.writeCreate, update and archive conversion goals
funnels.readList groups and funnels, validate definitions and query results
funnels.writeCreate and update groups; create, update and archive funnels
properties.writeDeclare, update and archive analytics properties
pii.readRead PII detectors, effective policy and detection reports
pii.policy.writeChange PII policy and grant or revoke property exemptions
logs.readRead request logs
access.readRead visitor access rules, network rules, and sign-outs
access.writeChange visitor access rules and network rules, and sign visitors out
function.readList and inspect function runtimes, invoke them and read their logs
function.writeCreate, update and delete function runtimes
cron.readList crons and read their runs
cron.writeCreate, update, pause, run now and delete crons
queue.readList queues, read their stats and runs, and peek at messages
queue.writeCreate, update, pause, purge, redrive and delete queues
queue.sendSend messages to queues, and nothing else
workflow.readList workflow runs and read their steps
workflow.writeStart, signal, cancel and retry workflow runs
webhook.readList and read webhook subscriptions and their deliveries
webhook.writeCreate, update, test, rotate, redeliver and delete webhook subscriptions
hook.readList and read hooks and their receipts
hook.writeCreate, update and delete hooks
form.forwardSubscribe a webhook to form submissions (form.*), in addition to webhook.write
submission.readRead every form submission and uploaded file in the workspace, and the access log of those reads
token.adminList 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.

RoleGranted for
edge:memberConsole reads only
edge:publisherAgent publishing plus functions, goals, funnels and properties. No domains, PII or destroy
edge:managerMember + publisher + domain manage, webhooks, hooks and reading form submissions. No destroy, PII, form forwarding, or token administration
edge:adminPublisher + 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.

CapabilityScopesmemberpublishermanageradmin
Read workspacesnamespace.readyesyesyesyes
Read distributionsdistribution.readyesyesyesyes
Read deployments and published filesdeployment.readyesyesyesyes
Read analyticsanalytics.readyesyesyesyes
Read request logslogs.readyesyesyesyes
Read visitor accessaccess.readyes—yesyes
Change visitor access and sign visitors outaccess.write——yesyes
Read custom domainsdomain.readyes—yesyes
Create, update and copy distributionsdistribution.write—yesyesyes
Create, commit and patch deploymentsdeployment.write—yesyesyes
Promote, schedule, take down, roll back and invalidatedeployment.promote—yesyesyes
Read and write data objectsdocument.read, document.write—yesyesyes
Author goalsgoals.read, goals.write—yesyesyes
Author funnelsfunnels.read, funnels.write—yesyesyes
Declare propertiesproperties.write—yesyesyes
Manage function runtimesfunction.read, function.write—yesyesyes
Read crons and their runscron.readyesyesyesyes
Create, change, run and delete cronscron.write—yesyesyes
Manage queues and their messagesqueue.read, queue.write—yesyesyes
Send messages to queuesqueue.send—yesyesyes
Read workflow runsworkflow.readyesyesyesyes
Start, signal, cancel and retry workflow runsworkflow.write—yesyesyes
Attach and manage domainsdomain.manage——yesyes
Manage webhooks and hookswebhook.read, webhook.write, hook.read, hook.write——yesyes
Read form submissions and uploaded filessubmission.read——yesyes
Delete a distributiondistribution.destroy———yes
Delete a domaindomain.destroy———yes
Read and change PII policypii.read, pii.policy.write———yes
Forward form submissions to a webhookform.forward———yes
Manage everyone's access tokenstoken.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.write builds a deployment and publishes its preview. Making it live needs deployment.promote.
  • Destroying is always separate. distribution.destroy and domain.destroy are not implied by write or manage.
  • There is no content scope. A deployment's files are covered by deployment.read and deployment.write, even though the tools are edge_content_* and the path is /v1/deployments/{id}/content.
  • Domains are not on publisher. domain.read is on member (and admin). domain.manage is on manager and admin. If publishing works but domain calls return 403, this is why.
  • Data objects are on publisher. Mapping /_api uses distribution.write. Function runtimes use function.read / function.write, also on publisher (and therefore manager and admin).
  • Logs are not analytics. analytics.read does not grant logs.read. Both are on member, publisher, manager and admin.
  • Reading conversions is not authoring them. analytics.read shows conversion results in the console. Creating goals, funnels or properties needs goals.write, funnels.write or properties.write — publisher, manager and admin in the standard roles.
  • PII policy is administrative. pii.policy.write is admin only.
  • Form data needs its own yes. webhook.write covers every event except form submissions. Subscribing to form.* also needs form.forward (admin only), and the request must carry "confirm": true.
  • Reading submissions is its own scope. submission.read covers 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.

See also ​