Scopes
Scopes & permissions
The Verentis scope naming scheme and the scopes your apps and engines will commonly request.
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 follow a consistent three-part pattern:
<service>.<resource>.<action>
For example node.file.read — the file resource in the node service, read action. Actions you'll
see include read, read-all, create, update, delete, and a few resource-specific verbs.
Scopes you'll commonly request
Most extensions work with files and content in a workspace. The Node service owns these:
node.file.readRead/download file content. Needed by any viewer or any engine that reads inputs.
node.node.createCreate nodes — this is what file upload requires. (There is no separate node.file.write scope;
creating file content goes through node.node.create.)
node.node.updateUpdate an existing node — needed by editors and engines that overwrite files.
node.file.deleteDelete files.
node.content.read / node.content.create / node.content.updateLower-level content operations.
node.journal.createAppend journal entries (history/audit of changes), used by editors that record activity.
Upload uses node.node.create
A common mistake is requesting a node.file.write scope — it doesn't exist. To write/upload file
content, request node.node.create (and node.node.update to modify existing files).
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 |
|---|---|
fabric.setting.read-all | Read workspace policy settings, including Daily Brief enablement and time zone. |
ai.brief.read | Read persisted workspace/folder briefs and file summaries. |
ai.brief.generate | Generate and persist workspace/folder briefs or file summaries. |
fabric.notification.read | Read the authenticated user's notification feed for the token workspace. |
fabric.notification.update | Mark notifications read, mark all read, or dismiss them. |
node.storage.read | Read current retained-content usage and quota for the token workspace. |
execution.execution.read | Read executions, logs, engine resolution and the schedule/trigger automation projection. |
execution.execution.read does not permit starting or cancelling a run; that requires
execution.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.
Other service scopes
Depending on what your extension does, you may request scopes from other services. They follow the same
<service>.<resource>.<action> scheme:
| Service | Examples |
|---|---|
node | node.branch.read, node.journal.read |
account | account.workspace.read, account.invitation.read |
security | security.api-key.read, security.role.read |
fabric | fabric.service.read, fabric.setting.read |
Request read/read-all only when you need them, and avoid delete/update unless 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.settings.manage
Next
Use your scoped token to make requests.