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.
Roles and capabilities
Section titled “Roles and capabilities”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?”:
| Capability | viewer | editor | admin | owner |
|---|---|---|---|---|
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.
Scopes and what they grant
Section titled “Scopes and what they grant”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.
| Scope | Grants |
|---|---|
repo:read | Read graphs, queries, things, and shapes |
repo:checkpoint-read | Read retained graph checkpoint metadata, obtain signed artifact URLs, and export a graph; requires unrestricted repo:read too |
repo:checkpoint-generate | Generate and retry graph checkpoints; requires unrestricted repo:read and repo:checkpoint-read too. repo:admin remains compatible for this capability only. |
repo:write | Writes, 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:configure | Graph-scoped subscriptions, credentials, action runs, notifications, and graph settings |
repo:admin | Delete, 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-callback | Receive graph-level action callbacks — the delivery of action results and status updates addressed to a specific graph; held by graph owners and admins |
org:read | Read 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:configure | Create 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-callback | Receive 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-curate | Curate 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:admin | Rename 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.
Access through a grant
Section titled “Access through a grant”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:writelets 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:writelets 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:writegrant cannot change Shapes, and ashapes:writegrant 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.
Minimum scope by task
Section titled “Minimum scope by task”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.
| Task | Minimum scope |
|---|---|
| Read things, assertions, shapes, or write history | repo:read |
| Read checkpoint metadata or obtain a signed checkpoint artifact URL | Unrestricted repo:read + repo:checkpoint-read |
| Export a graph | Unrestricted repo:read + repo:checkpoint-read |
| Generate or retry a graph checkpoint | Unrestricted 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 notifications | repo:configure |
| Create, update, pause, or remove a graph-scoped subscription | repo:configure |
| Read, lease, or deliver actions | repo:configure |
| Manage graph-scoped credentials — create, bind, grant, revoke | repo:configure |
| Rename a graph or change its settings | repo: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 visibility | repo:admin |
| Hard-delete a thing | Unrestricted repo:admin |
| Redact a thing | Unrestricted repo:admin |
| Rewrite the body of one version of a thing in place | Unrestricted repo:admin |
| Receive graph-level action callbacks | repo:action-callback — request this scope for new tokens. repo:write is also accepted for compatibility. |
| Read an org profile or list its members | org:read |
| Read installed components | org:read |
| Create a graph in an org | org:configure |
| Add, remove, or change a member’s role (assigning or removing owner requires owner) | org:configure |
| Install or manage a component | org:configure |
| Change org settings | org:configure |
| Create, update, pause, or remove an org-scoped subscription | org:configure |
| Bind or unbind org-scoped credentials | org:configure |
| Create or manage a service account | org:configure |
| Mint a token for a service account | org:configure |
| Receive org-level action callbacks | org:action-callback |
| Curate the org’s hubs in the answer exchange | org:hub-curate |
| Rename or archive an org | org: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.