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, or run agents homed there.

Role	Granted to	Effect
steward	Explicit user, or org admin	Full space stewardship
contributor	User, department member, or API key with write reach	Can publish agents and learnings to the space
subscriber	Same principals as contributor	Read-only access to the space
executor	API keys with execute reach	Can run agents homed in the space

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.

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. Give the team an API key limited to those space IDs for CI or automation.
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:read without agents: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 and update agents; store and reinforce learnings
`agents:execute`	Dispatch goals and resume suspended runs
`credentials:read`	List and view provider credentials
`credentials:write`	Create, update, and delete provider credentials
`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

Portal-only scopes (apikeys:read, apikeys:write) are never grantable on API keys.

Scope implications

Only the agents:* family has an implication ladder:

agents:write  ⇒  agents:execute  ⇒  agents:read

claims:* scopes are flat — nothing implies claims:curate or claims:erase.

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.

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 roles:

Tier	Space role	Can dispatch runs	Can curate learnings
read	subscriber	No	No
execute	executor	Yes (with `agents:execute`)	No
write	contributor + executor	Yes (with `agents:execute` or `agents:write`)	Yes (with `agents:write`)

API keys operate through space reach and optional per-agent operator grants. Human stewards and org admins administer agent configuration directly; keys do not receive admin or write access to agent configuration on their own.

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.
Admin — Delete agent, change home space, grant operators.
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`	Admin 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)
Org-wide write key	Yes	No
Home-space contributor key	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.

Security and data isolation for tenant isolation and encryption
Agents API for agent lifecycle endpoints
Learnings API for manual learning operations
Credentials API for provider credential management
MCP server for IDE integration

Access control (FGA and RBAC)

On this page