Access control (FGA and RBAC)
How Hyperstruck combines API key scopes, organization roles, and fine-grained authorization to control who can read, run, and curate agents and learnings.
In one line
Every request passes two gates: a scope check (what the caller is allowed to do in general) and a fine-grained access check (whether they may touch this specific agent or space). Both must pass.
Hyperstruck uses a Zanzibar-style authorization model — the same family of design Google uses for consistent, relationship-based access at scale — on top of tenant-scoped API key scopes and portal membership roles. This page is the permissions reference for tenant-facing APIs. Platform-admin scopes and internal admin endpoints are out of scope here.
Two layers, one decision
| Layer | What it checks | Who it applies to |
|---|---|---|
| Scopes | Coarse capability (agents:read, claims:curate, …) | API keys and portal sessions |
| Fine-grained access | Object-level permission on a specific agent or space | Every authenticated caller |
A caller needs the right scope and the right object-level permission. For example, dispatching a goal requires agents:execute and execute access to that agent. Listing agents requires agents:read and returns only agents in spaces the caller can view.
Portal sessions never carry client-supplied scopes. The backend derives scopes from the user's organization membership role (owner, admin, developer, or viewer).
Organization roles
Roles sync from your identity provider into the tenant organization. Higher roles inherit lower ones.
| Role | Inherits | Typical use |
|---|---|---|
| owner | admin, developer, viewer | Full tenant administration |
| admin | developer, viewer | Manage credentials, API keys, and org-wide settings |
| developer | viewer | Build and run agents, curate claims |
| viewer | — | Read-only access to agents, runs, learnings, and usage |
Org admins and owners reach every agent in the tenant. Developers and viewers only reach agents and spaces where they hold an explicit relationship.
Portal role → API scopes
These scopes apply to dashboard sessions. API keys use the grantable scope list in the next section instead.
| Role | Scopes |
|---|---|
| viewer | agents:read, usage:read, apikeys:read, claims:read |
| developer | agents:write, credentials:read, usage:read, apikeys:read, claims:read, claims:curate |
| admin | agents:write, credentials:write, usage:read, apikeys:read, apikeys:write, claims:read, claims:curate, claims:erase |
| owner | Same as admin today |
agents:write implies agents:execute and agents:read. claims:curate and claims:erase do not imply each other or any agents:* scope.
Spaces and kinds
A space is the permissions container for shared learnings. Every agent has exactly one home space — the space where its learnings are born and where stewardship is anchored. Spaces are flexible: use them to group agents and learnings by department, workload, product area, or individual ownership. There is no fixed org chart you must follow.
Learning recall and agent inventory are filtered to spaces the caller can view. When you create an agent, you pick a home space you can publish to (defaults to commons).
Space roles
Each space has explicit roles that control who can read, publish, run, or manage agents homed there.
| Role | Granted to | Effect |
|---|---|---|
| steward | Explicit user, or org admin | Full space stewardship, including the human-only admin rung on homed agents |
| contributor | User, department member, or API key with write reach | Can publish agents and learnings to the space. Does not grant agent config change or delete |
| subscriber | Same principals as contributor | Read-only access to the space |
| executor | API keys with execute reach | Can run agents homed in the space |
| manager | Write-tier API keys only | Can change and delete agents homed in the space. Not assignable to people |
Stewards and contributors can publish. Subscribers can view content in the space but cannot publish or run agents unless they also hold a separate grant. Contributor is not enough to edit or delete an agent — that is why commons stays safe for every org member.
Space kinds
| Kind | What it is for | Default access | Example |
|---|---|---|---|
| commons | Org-wide default home | Every org member is a contributor | General-purpose agents, shared operational knowledge |
| personal | Per-user private space | Creator is steward | A developer's experimental agent they administer alone |
| department | Team-scoped space | Department members are contributors | Engineering team's incident-response agents, synced from your directory group |
| domain | Curated org container | Org admins steward | "HR knowledge base" or "Sales playbooks" — flexible naming, admin-curated |
Practical patterns
- Department workloads — Create department spaces for each team. Home team agents there so learnings stay team-scoped. A team write key limited to those space IDs can create, edit, and delete team-homed agents for CI or automation without an all-spaces key.
- Personal sandboxes — Home experimental agents in a personal space. The creator is steward and can administer without granting org-wide access.
- Domain curation — Use domain spaces for cross-cutting knowledge bases (compliance, onboarding, product specs). Org admins steward; contributors publish approved agents.
- Commons for shared defaults — Agents without an explicit home land in commons. Viewer read-only enforcement is the scope gate (
agents:readwithoutagents:write).
List spaces with GET /spaces (scope: agents:read). Results include only spaces you can view.
API key scopes
API keys carry explicit scopes stored on the key. Space reach on the key determines which spaces the key can access.
Grantable scopes
These scopes can be assigned to programmatic API keys:
| Scope | Meaning |
|---|---|
agents:read | Read agents, runs, sessions, learnings, plans, and spaces |
agents:write | Create, update, and delete agents; store and reinforce learnings |
agents:execute | Dispatch goals and resume suspended runs |
claims:read | Read claim curation data |
claims:curate | Promote, adopt, or correct claims |
claims:erase | Irreversible claim erasure |
usage:read | Tenant usage and billing summary |
reports:read | Run reporting queries, read the metric catalog, charts, and dashboards |
Anything outside that list is refused at key creation rather than silently dropped, and it falls into three groups.
| Not grantable | Why |
|---|---|
apikeys:read, apikeys:write, reports:write | Held by portal roles instead, which is why managing keys, and authoring a chart or a space's reporting constants, are portal actions. See Reporting API. |
identity:admin:write, learning_transfer:admin:write, spaces:admin:write, usage:admin:read | Platform administration, held by us rather than by any tenant principal. |
credentials:read, credentials:write | Vestigial. No role carries them and no endpoint requires them. |
Scope implications
One ladder runs over the three action names, and it applies to whichever resource carries them:
write ⇒ execute ⇒ readSo agents:write holds agents:execute and agents:read, and reports:write holds reports:read, without either being granted separately.
Actions outside that ladder imply nothing and are implied by nothing. claims:curate and claims:erase are the ones to watch: neither is on the ladder, so nothing confers them and holding one does not confer the other. claims:read sits on the bottom rung, which implies nothing further.
Separation of duty
A single API key cannot combine dispatch scopes with curation scopes:
- Dispatch:
agents:execute,agents:write - Curation:
claims:curate,claims:erase
Agent runtimes replay the scopes of the key that dispatched them. Combining dispatch and curation would let an agent approve content it ingested. Issue separate keys for running agents and for curating claims.
For what a claim is, and what each of these scopes actually lets someone decide, see Claims and the Claims API.
API key space reach
When creating a key, choose space reach:
| Mode | Access reach | When to use |
|---|---|---|
| All spaces | Org-wide read, execute, or write tier | Platform integrations, org-wide automation |
| Selected spaces (up to 25) | Per-space access by tier | Team CI keys, department-scoped automation |
Key tiers map to space relations:
| Tier | Space relations | Can dispatch runs | Can curate learnings | Can change / delete agents |
|---|---|---|---|---|
| read | subscriber | No | No | No |
| execute | executor | Yes (with agents:execute) | No | No |
| write | contributor + executor + manager | Yes (with agents:execute or agents:write) | Yes (with agents:write) | Yes, for agents homed in the key's spaces (with agents:write) |
A selected-spaces write key is enough for ordinary agent lifecycle in those spaces. You no longer need an all-spaces key just to update or delete. Agents homed outside the selection stay untouchable.
API keys operate through space reach and optional per-agent operator grants. A write-tier key can create, update, and delete agents inside its reach — org-wide if the key is all-spaces, or only the selected homes (up to 25) otherwise. Keys still do not receive the human-only admin rung: quarantine release, irreversible entity erasure, and wipe-all-learnings stay with space stewards and org admins.
Agent access
Agents split home (where learnings live) from use (who can run the agent). Every agent is homed in exactly one space.
- Read — View agent config, runs, sessions, and learnings.
- Execute — Dispatch goals and resume runs.
- Write — Update agent configuration, change home space, and delete the agent. Write-tier keys hold this inside their space reach.
- Admin — Human-only: quarantine release, entity erasure, and delete-all-learnings. Home-space stewards and org admins. Keys never inherit this, even with
agents:write. - Curate — Store, reinforce, and curate learnings and claims.
A home-space subscriber can read an agent but cannot execute it unless they are also an operator. Visibility in a space does not grant run access.
Permissions matrix
By action
| Action | Required scope | Required access |
|---|---|---|
| List agents / spaces | agents:read | View on readable spaces |
| Create agent | agents:write | Publish on target home space |
| Get agent / list runs | agents:read | Read on agent |
| Update agent | agents:write | Write on agent |
| Delete agent | agents:write | Write on agent |
| Dispatch goal | agents:execute | Execute on agent |
| Resume run | agents:execute | Execute on agent |
| Read learnings | agents:read | Read on agent |
| Store / reinforce learning | agents:write | Curate on agent |
| Delete all learnings | agents:write | Admin on agent |
| Read claims | claims:read | Read on agent |
| Curate claims | claims:curate | Curate on agent |
| Erase claims | claims:erase | Admin on agent |
| Read credentials | credentials:read | Org developer+ or API key |
| Write credentials | credentials:write | Org admin+ or API key |
| Usage summary | usage:read | Tenant-scoped |
MCP resolve | agents:read | Valid active API key |
MCP complete_run | agents:write | Valid active API key |
Org role reach (no explicit space grant)
| Principal | Org admin | Space steward | Agent execute | Agent admin |
|---|---|---|---|---|
| Owner | Yes | Yes | Yes | Yes |
| Admin | Yes | Yes | Yes | Yes |
| Developer (no operator) | No | No | No | No |
| Viewer | No | No | No | No |
Developers need an explicit operator grant, home-space stewardship, or a matching API key to run an agent.
Home visibility vs agent use
| Principal | Read | Execute |
|---|---|---|
| Home-space subscriber (not operator) | Yes | No |
| Operator | Yes | Yes |
Curation vs configuration
| Principal | Curate | Write (config / delete) |
|---|---|---|
| Org-wide write key | Yes | Yes |
| Selected-spaces write key | Yes (agents in granted spaces) | Yes (same homes only) |
| Home-space contributor (no manager) | Yes (agents in space) | No |
| Execute-tier key | No | No |
| Org admin | Yes | Yes |
| Home-space steward | Yes | Yes |
MCP access
The hosted MCP server reuses tenant API key scopes — there is no separate MCP scope namespace.
| Gate | Requirement |
|---|---|
| Transport (connect) | Active key with agents:read or agents:write |
resolve tool | agents:read |
complete_run tool | agents:write |
For end-to-end MCP usage (resolve before a task, complete after), issue a key with both scopes or use agents:write (which implies read). Space reach on the key applies the same way as REST calls.
See MCP server for connection setup.
Read what a key actually holds
GET /entitlements answers, for the calling principal, what it is entitled to: plan_code, compliance_guardrails_addon, and scopes with implied scopes expanded.
curl -H "Authorization: Bearer <API_KEY>" \
"https://api.hyperstruck.com/entitlements"It is scoped to the caller's own principal, so it reports the key you called with rather than the tenant. The expansion is the useful part: the ladder above runs over action names rather than over one resource family, so a key issued agents:write also holds agents:execute and agents:read without either appearing on the key. This endpoint returns what the key can actually do, rather than making you reimplement that reasoning. The scopes off the ladder, claims:curate and claims:erase, come back only when they were granted outright.
Related pages
- Security and data isolation for tenant isolation and encryption
- Agents API for agent lifecycle endpoints
- Learnings API for manual learning operations
- Claims API for the curation and erasure endpoints these scopes gate
- Credentials API for provider credential management
- MCP server for IDE integration