Skip to content

Access reference

WarmHub access composes from your org role, any grants issued to you, and the scopes that narrow them. Your role sets the ceiling on what you can do as a member of an org; a grant gives you named operations on part of one graph, whether or not you belong to its org; a personal access token’s scopes narrow a token to a subset of what your role and grants allow; and an org admin can attach member scope overrides that narrow a member below their role on a given org or graph. A request is allowed only when your role or a grant permits it and every scope layer that applies to it covers it. This page is the canonical map of role → capability, scope → capability, grant → capability, and task → minimum scope.

Reading a public graph is the exception: anyone can read it, signed in or not, with no role or grant. Writing to and managing a public graph still follow the rules on this page.

Every member of an org has one role: viewer, editor, admin, or owner. Roles are cumulative — each includes everything the one before it can do. This table answers “what can an admin do that an editor can’t?”:

Capabilityviewereditoradminowner
Read graphs, things, assertions, and shapes (repo:read)✓✓✓✓
Read graph checkpoint metadata, signed artifacts, and export a graph (repo:checkpoint-read, with unrestricted repo:read)✓✓
Generate or retry graph checkpoints (repo:checkpoint-generate, with unrestricted repo:read and repo:checkpoint-read)✓✓
Read the org profile, members, and installed components (org:read)✓✓✓✓
Write — create, update, and rename things and shapes (repo:write)✓✓✓
Configure graphs — subscriptions, credentials, actions, notifications, graph settings (repo:configure)✓✓
Administer graphs — delete, archive, change visibility, and hard-delete, redact, or rewrite things (repo:admin)✓✓
Receive graph-level action callbacks (repo:action-callback; repo:write is also accepted for compatibility)✓✓✓
Configure the org — create graphs, manage members, org settings, install components, org-scoped subscriptions and credential bindings, manage service accounts, and mint service-account tokens (org:configure)✓✓
Receive org-level action callbacks (org:action-callback)✓✓
Curate the org’s hubs in the answer exchange (org:hub-curate)✓✓
Administer the org — rename, archive (org:admin)✓

Owner and admin grant the same graph access; they differ only at the org level — only an owner can rename or archive the org. Member management has one further owner-only carve-out within org:configure: only an owner can assign or remove the owner role, and the last owner can’t be removed or demoted. Admins manage all other members and roles.

A token scope binds a resource to one or more of these permissions. Scopes are independent — repo:write does not include repo:read — and can only narrow access, never raise it above your role. The repo:* scopes act on a graph; they keep the spelling from when a graph was called a repo.

A scope entry’s selection is the path or Shape filter inside that entry that controls which Things the scope applies to. A whole-graph selection means no path or Shape filter is set — the scope covers every Thing in the graph. Some operations (hard-delete, redaction, and rewrite) require a whole-graph selection; a token whose scope entry is filtered to a subset of Things is refused for those operations. See Personal access tokens for the full scope model.

ScopeGrants
repo:readRead graphs, queries, things, and shapes
repo:checkpoint-readRead retained graph checkpoint metadata, obtain signed artifact URLs, and export a graph; requires unrestricted repo:read too
repo:checkpoint-generateGenerate and retry graph checkpoints; requires unrestricted repo:read and repo:checkpoint-read too. repo:admin remains compatible for this capability only.
repo:writeWrites, shape mutations, and thing/shape renames. When the write comes from a grant rather than your role, it covers only what the grant’s write operations allow, inside the grant’s coverage — see Access through a grant.
repo:configureGraph-scoped subscriptions, credentials, action runs, notifications, and graph settings
repo:adminDelete, archive, and change graph visibility; hard-delete, redact, and rewrite things. Hard-delete, redaction, and rewrite need this scope’s selection to be the whole graph; a token with a narrower selection is refused for them.
repo:action-callbackReceive graph-level action callbacks — the delivery of action results and status updates addressed to a specific graph; held by graph owners and admins
org:readRead the org profile and members, see installed components, and list the org’s graphs — including private ones — in org-level views; reading a graph’s contents still needs repo:read
org:configureCreate graphs, manage members and org settings, install and manage components, manage org-scoped subscriptions and credential bindings, create and manage service accounts, and mint tokens for service accounts
org:action-callbackReceive org-level action callbacks — the delivery of action results and status updates addressed to the org rather than to a specific graph; held by org owners and admins
org:hub-curateCurate the org’s hubs in the answer exchange. WarmHub reports this scope in access checks and the answer exchange enforces it; it is not included in org:configure. Held by org owners and admins
org:adminRename and archive the org

A write that references a Thing your token cannot read answers as if the Thing were absent when you name it, but resolves when you address it by durable id. See References in a write.

A grant gives a user or component named operations over part of one graph — its coverage, a selection of paths and Shapes — without membership in the graph’s org. The grantable operations are things:read, commits:read, shapes:read, notifications:read, subscriptions:read, subscriptions:create, things:write, and shapes:write. Grants apply only on graphs where grants are enabled, and a revoked or narrowed grant takes effect at your next request.

Reads. A things:read grant lets you read the Things inside its coverage, as a member with repo:read reads the graph, and nothing outside it. When you write through a grant, the same read decides what your write can see: references by name resolve only to Things the grant lets you read, and anything else answers as absent, as for a token.

Writes. Write access from a grant is narrower than an editor’s repo:write:

  • things:write lets you add, revise, retract, and rename Things inside the coverage, and attach files to the Things you write. A rename needs both the old and the new name inside one grant’s coverage.
  • shapes:write lets you add, revise, retract, restore, and rename Shapes whose names (hub/shapes/<name>) fall inside the coverage. System, built-in, and component-owned Shapes stay refused.
  • Each operation covers only its own kind: a things:write grant cannot change Shapes, and a shapes:write grant cannot write Things.
  • A grant confers only the operations it lists. None of them reaches hard-delete, redaction, or rewrite, names that start with a dot, graph settings or credentials, graph administration, or the org. A grant backed by a View confers no write.

A token you mint for a graph you reach through a grant never reaches further than the grant. See Graphs you reach through a grant.

The minimum scope a token needs for each common task. Anything not listed for a scope is not covered by it — request the narrowest scope that covers your task.

TaskMinimum scope
Read things, assertions, shapes, or write historyrepo:read
Read checkpoint metadata or obtain a signed checkpoint artifact URLUnrestricted repo:read + repo:checkpoint-read
Export a graphUnrestricted repo:read + repo:checkpoint-read
Generate or retry a graph checkpointUnrestricted repo:read + repo:checkpoint-read + repo:checkpoint-generate (repo:admin also works for compatibility)
Submit a write (create or rename things and shapes)repo:write
Read notificationsrepo:configure
Create, update, pause, or remove a graph-scoped subscriptionrepo:configure
Read, lease, or deliver actionsrepo:configure
Manage graph-scoped credentials — create, bind, grant, revokerepo:configure
Rename a graph or change its settingsrepo:configure
Create, view, list, or revoke a grant on a graph (creating one also needs every operation it grants)repo:configure
Delete, archive, or change a graph’s visibilityrepo:admin
Hard-delete a thingUnrestricted repo:admin
Redact a thingUnrestricted repo:admin
Rewrite the body of one version of a thing in placeUnrestricted repo:admin
Receive graph-level action callbacksrepo:action-callback — request this scope for new tokens. repo:write is also accepted for compatibility.
Read an org profile or list its membersorg:read
Read installed componentsorg:read
Create a graph in an orgorg:configure
Add, remove, or change a member’s role (assigning or removing owner requires owner)org:configure
Install or manage a componentorg:configure
Change org settingsorg:configure
Create, update, pause, or remove an org-scoped subscriptionorg:configure
Bind or unbind org-scoped credentialsorg:configure
Create or manage a service accountorg:configure
Mint a token for a service accountorg:configure
Receive org-level action callbacksorg:action-callback
Curate the org’s hubs in the answer exchangeorg:hub-curate
Rename or archive an orgorg:admin

Scopes are checked against your role: a token can carry repo:write, but the write still fails if your role is viewer. Use the role:<name> shorthand to mint a token that mirrors a whole role at once.