Access reference
WarmHub access composes from your org role and the scopes that narrow it. Your role sets the ceiling on what you can do; a personal access token’s scopes narrow a token to a subset of that ceiling; and an org admin can attach member scope overrides that narrow a member below their role on a given org or repo. A request is allowed only when your role permits it and every scope layer that applies to it covers it. This page is the canonical map of role → capability, scope → capability, and task → minimum scope.
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 repositories, things, assertions, and shapes (repo:read) | ✓ | ✓ | ✓ | ✓ |
Read repository checkpoint metadata and signed artifacts (repo:checkpoint-read, with unrestricted repo:read) | ✓ | ✓ | ||
Generate or retry repository 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 repos — subscriptions, credentials, actions, notifications, repo settings (repo:configure) | ✓ | ✓ | ||
Administer repos — delete, archive, change visibility (repo:admin) | ✓ | ✓ | ||
Receive repo-level action callbacks (repo:action-callback) | ✓ | ✓ | ||
Configure the org — create repos, manage members, org settings, install components, org-scoped subscriptions and credential bindings (org:configure) | ✓ | ✓ | ||
Receive org-level action callbacks (org:action-callback) | ✓ | ✓ | ||
Administer the org — rename, archive (org:admin) | ✓ |
Owner and admin grant the same repository 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.
| Scope | Grants |
|---|---|
repo:read | Read repositories, queries, things, and shapes |
repo:checkpoint-read | Read retained repository checkpoint metadata and obtain signed artifact URLs; requires unrestricted repo:read too |
repo:checkpoint-generate | Generate and retry repository 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 |
repo:configure | Repo-scoped subscriptions, credentials, action runs, notifications, and repo settings |
repo:admin | Delete, archive, and change repository visibility |
repo:action-callback | Receive repo-level action callbacks — the delivery of action results and status updates addressed to a specific repo; held by repo owners and admins |
org:read | Read the org profile and members, see installed components, and list the org’s repositories — including private ones — in org-level views; reading a repo’s contents still needs repo:read |
org:configure | Create repos, manage members and org settings, install and manage components, and manage org-scoped subscriptions and credential bindings |
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 repo; held by org owners and admins |
org:admin | Rename and archive the org |
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 | repo:read + repo:checkpoint-read |
| Generate or retry a repository checkpoint | 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 repo-scoped subscription | repo:configure |
| Read, lease, or deliver actions | repo:configure |
| Manage repo-scoped credentials — create, bind, grant, revoke | repo:configure |
| Rename a repo or change its settings | repo:configure |
| Delete, archive, or change a repo’s visibility | repo:admin |
| Receive repo-level action callbacks | repo:action-callback |
| Read an org profile or list its members | org:read |
| Read installed components | org:read |
| Create a repo 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 |
| Receive org-level action callbacks | org:action-callback |
| 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.