Scopes & permissions · Verentis Developer

A scope is a fine-grained permission. Tokens carry only the scopes that were both requested (in your manifest's permissions) and granted (by an admin at consent, or via a role/grant). Request the minimum your extension needs.

Naming scheme

Scopes describe what a caller can do to a thing, not which service hosts it:

<resource>.<action>

For example file.read — read files. A third segment is used where it makes the name clearer or marks a tier: ai.policy.write, or billing.admin.read for platform-operator scopes. Every name matches ^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*){1,2}$ and is unique across the platform.

Actions come from a small fixed set:

read covers reading and listing (including search and aggregates).
write covers create and update.
delete stays separate, because it is the action most worth holding back.
A few risky actions get their own verb: publish, history, run, approve, accept, replay, rotate, operate, visibility, connect, start.

<thing>.admin.* scopes are platform-operator tiers. They are never granted by the default account or workspace roles, and apps cannot request them.

Scopes you'll commonly request

Most extensions work with files and content in a workspace:

file.read

Read and list files, folders and file content. Needed by any viewer or any engine that reads inputs.

file.write

Create and update files and folders — this is what file upload and editors that save require.

file.delete

Delete files.

file.history

Read a single file's version history. Intended for power users and tools.

file.publish

Make a path anonymously readable. Held by owners and admins only; avoid requesting it.

Upload uses file.write

To write/upload file content — new or existing files — request file.write. There are no separate create, update or journal scopes.

Workspace shell scopes

The workspace home and global shell use several read-only APIs. Apps need these scopes only if they call the same APIs themselves:

Scope	Authorises
`setting.read`	Read workspace policy settings, such as the workspace time zone.
`notification.read`	Read the authenticated user's notification feed for the token workspace.
`notification.write`	Mark notifications read, mark all read, or dismiss them.
`activity.read`	Read the workspace activity feed shown on the dashboard.
`quota.read`	Read the workspace's storage plan and cap.
`execution.read`	Read executions, logs, engine resolution and the schedule/trigger automation projection.

execution.read does not permit starting or cancelling a run; that requires execution.run. Notification and current-storage endpoints derive their workspace (and, for notifications, user) from token claims rather than caller-supplied ids.

See Workspace shell & routes for the endpoint and response contracts.

Scope catalogue

The full list of platform scopes. Tokens are already bound to one account or workspace, so a scope does not repeat which kind of resource it applies to.

Files and workspaces

Scope	Authorises
`file.read`	Read and list files, folders and content.
`file.write`	Create and update files and folders, including uploads.
`file.delete`	Delete files.
`file.history`	Read a file's version history.
`file.publish`	Make a path anonymously readable (owners and admins only).
`activity.read`	Read the workspace activity feed.
`workspace.read`	Read workspaces, their URLs, storage and navigation.
`workspace.write`	Create workspaces and update their details, URLs and slugs.
`account.read`	Read the account.
`account.write`	Create and update the account.
`profile.write`	Update the caller's own profile, avatar and navigation state.
`onboarding.start`	Create a new user's first account and workspace.
`invitation.read`	List pending account or workspace invitations.
`invitation.write`	Send, resend and revoke invitations.
`invitation.accept`	Accept an invitation.

Billing, metering and quota

Scope	Authorises
`billing.read`	Read invoices, payments, payment methods, budgets, balance and app subscriptions.
`billing.write`	Edit billing details and budgets, auto-recharge, redeem promo codes and top up.
`metering.read`	Read account and workspace usage.
`quota.read`	Read a workspace's storage plan and cap.
`quota.write`	Set a workspace's storage quota.

Apps, installations and the Marketplace

Scope	Authorises
`app.read`	Read app registrations, file types, icons and creatable items.
`app.write`	Register or update an app from its manifest.
`app.delete`	Unregister and delete an app.
`publisher-service.read`	Read a publisher's app backends.
`publisher-service.write`	Register app backends, rotate their secrets and disable their clients.
`installation.read`	Preview, resolve and list installations.
`installation.write`	Install, update and consent to an installation.
`installation.delete`	Uninstall.
`package.read`	Read Marketplace packages.
`package.write`	Create and update packages.
`package.delete`	Delete packages.
`package.publish`	Publish or yank package versions.
`package.visibility`	Change package visibility and private grants.
`publisher.read`	Read publishers.
`publisher.write`	Create and update publishers, signing keys and regional ownership.
`entitlement.read`	Read entitlements.
`entitlement.write`	Purchase an entitlement.
`entitlement.delete`	Revoke an entitlement.
`price.read`	Read price plans and price books.
`price.write`	Edit price plans and price books, and submit them for approval.
`review.write`	Write a package review.
`report.write`	Report a package or publisher for abuse.
`stats.read`	Read Marketplace statistics.

AI and execution

Scope	Authorises
`conversation.read`	Read AI conversations.
`conversation.write`	Converse with the AI assistant.
`conversation.delete`	Delete AI conversations.
`tool.read`	Read the AI tool catalogue.
`tool.run`	Run an AI tool.
`ai.read`	Read agent runs, their events and approvals.
`ai.write`	Submit, message, pause, resume and cancel agent runs.
`ai.approve`	Approve an agent's action.
`ai.model.read`	List available models.
`ai.policy.read`	Read the account or workspace model policy.
`ai.policy.write`	Update the account or workspace model policy.
`execution.read`	Read executions, logs and engine resolution.
`execution.run`	Start and cancel executions.

Platform services

Scope	Authorises
`setting.read`	Read settings.
`setting.write`	Update settings.
`setting.delete`	Delete settings.
`governance.read`	Read workspace governance rules, the effective policy and decision explanations.
`governance.write`	Create and update governance rules.
`notification.read`	Read notifications.
`notification.write`	Mark notifications read or dismiss them.
`webhook.read`	Read webhook delivery history.
`webhook.write`	Configure webhooks and their retention.
`webhook.replay`	Replay webhook deliveries.
`webhook.rotate`	Rotate webhook signing credentials.
`realtime.connect`	Connect to the realtime hub.

Platform operator scopes

These are granted on the Platform resource to operators only. Apps cannot request them.

Scope	Authorises
`billing.admin.read` / `billing.admin.write`	Platform billing: ledger, credits, rate rules, FX, revenue shares, period close.
`metering.admin.read`	Platform-wide usage.
`ai.admin.read` / `ai.admin.write`	System models and the system model policy.
`fabric.admin.read` / `fabric.admin.write` / `fabric.admin.delete`	The service catalogue: services, instances and declared scopes.
`fabric.admin.operate`	Shut down a service instance.
`directory.admin.read` / `directory.admin.write`	The global directory.
`file.admin.read` / `file.admin.write`	Maximum upload size per account or workspace.
`moderation.admin.read` / `moderation.admin.write`	Marketplace moderation queues.
`trust.admin.read` / `trust.admin.write`	Marketplace trust flags.
`report.admin.read` / `report.admin.write`	Marketplace abuse reports.

Identity and access

Scope	Authorises
`user.read`	Read and list users.
`user.create`	Create a user.
`user.write`	Update users.
`role.read`	Read and list roles.
`role.write`	Create and update roles.
`member.read`	Read role memberships.
`member.write`	Assign a person to a role.
`member.delete`	Remove a person from a role.
`grant.read`	Read and list permission grants.
`grant.write`	Grant a permission.
`grant.delete`	Revoke a permission.
`api-key.read`	Read and list API keys.
`api-key.write`	Create and update API keys.
`service-account.read`	Read and list service accounts.
`service-account.write`	Create and update service accounts.
`service-account.delete`	Delete service accounts.
`sso.read`	Read the workspace's single sign-on configuration.
`sso.write`	Change the workspace's single sign-on configuration.

Request write and delete only when your extension genuinely performs those actions. Tighter scope sets are easier for admins to approve.

Custom scopes you define

Apps and engines can define their own scopes (manifest spec.scopes), registered in the Fabric catalog so other callers can be granted them — the basis of app-to-app authorization. Name them the same way, prefixed with your extension's name:

acme-editor.document.export
acme-editor.template.write

Calling the Verentis API

Use your scoped token to make requests.