Grants
How a team declares a dependency on another team's API, what permissions they request, and how the API owner approves.
A grant is one team's approved permission on another team's API — a first-class object in the registry, not an HTTP convention. The consumer team says "we want to call these operations on your API"; the API's team admin reviews and approves; the result is a record connecting a consumer team to a producer API with an explicit set of permissions on specific operations.
That record is the seam Spec0 grows into an authorization control plane for your internal APIs (see Roadmap below).
Grants were previously called subscriptions, and consumers were subscribers. The names changed because "subscription" was doing two jobs — I depend on this and notify me — and collided with pub/sub semantics. "Subscribe" now means notification opt-in only. Your existing access is unchanged.
Two views, one object
| Route | Audience | What it shows |
|---|---|---|
/grants | Consumer team | Every API your team depends on, with the permissions granted on each. |
/consumers | Producer team | Every team consuming the APIs you publish. Approve, reject, revoke. |
Both views read the same grant records, filtered by which side of the relationship the viewer is on.
Requesting a grant
From the UI: Grants → New → pick an API → select the operations you want to invoke → submit. The API's team admin sees the request in their /consumers view and approves, rejects, or comes back with questions.
Programmatically: the same backend endpoint is documented in the API Reference — same approval flow. Useful when a service's CI bootstraps its dependencies declaratively.
State
A grant is PENDING until the producer's team admin acts on it:
PENDING ── admin approves ─▶ APPROVED
│
└───── admin rejects ──▶ REJECTEDOnly APPROVED grants receive change notifications from the producer side (Events).
What the grant captures
| Field | Meaning |
|---|---|
| Consumer team | The team that requested the grant. |
| API | The team-owned API the grant is against. |
| Permissions | The set of operations the consumer is approved to call. The producer's admin confirms or trims the requested set during approval. |
| Grant ID | Stable identifier for this consumer-API relationship. Today it's a registry key; under the roadmap below it's also the binding to your IAM. |
API versions move forward independently of grants. A consumer that took a grant at acme/orders@v3 keeps that record until they change it; the registry's tag stream and the spec0 pull <api>@<tag> and spec0 log <api> commands let them roll forward at their own pace.
Why it's intra-org
Grants exist to organise internal API consumption inside one engineering org — who depends on what, with which permissions, with explicit approval. Cross-org integrations are a different kind of relationship and aren't part of this surface.
Why this isn't Slack
Producer teams know who their consumers are, with permissions visible at a glance. Consumer teams know which version of which API they're on. Leadership can see the full mesh — which teams call which APIs, with what scope — without scraping channels or chasing emails. The communication that used to live in unstructured Slack threads ("hey, we're going to start calling your /orders endpoint, cool?") becomes a structured object with an audit trail.
Roadmap — authorization control plane
The foundation for using a grant as the authorization decision for runtime API calls is in place; the feature isn't yet generally available. The shape we're building toward:
- DCR (Dynamic Client Registration). When a grant is approved, Spec0 registers a corresponding client in your IAM provider and binds the IAM client ID to the grant ID.
- Producer-side SDK + OPA policy bundle. The producing service pulls a small bundle that encodes "which client IDs are approved to call which operations on this API" and evaluates incoming requests locally — no network hop on the hot path.
- The result. An incoming request carries an IAM-issued token; the producer's SDK decodes it, looks up the client ID's permissions in the bundle, and accepts or rejects based on what the producer-team admin approved in the dashboard. The full chain — request → token → client ID → grant ID → approved permissions — is auditable end-to-end inside Spec0.
Today, treat grants as the organisational and governance record. Production authorization still goes through your existing IAM. As the bundle + SDK lands we'll close the loop without changing the dashboard surface.
What an AI agent sees
An agent talking to the platform via MCP with an authenticated bearer token can read your team's grant state through the org-scoped MCP tools (search APIs, list APIs you depend on, get_api_consumers). Mutating grants through MCP is intentionally not exposed — declaring a dependency is a deliberate human act with an approval flow, not an agent shortcut.
A note on permission names
The rename covered the domain object. The authorization strings did not change: permissions are still subscription:view / subscription:manage / subscription:admin, the API-token scopes are still read:subscribers / write:subscribers, and the role is still Subscription Admin. See Access control — those pages are correct as written.
Where to go next
- APIs — what gets granted access to.
- Events — change notifications that flow off approved grants.
- Teams — who can request a grant and who can approve.
- API Reference — the REST surface for grants.
Managing members
Invite people to your organisation by email, manage pending invitations, and understand how accepting an invite works for new and existing Spec0 users.
Access control
Roles, permissions, and the rules Spec0 uses to decide whether a request from your dashboard, CLI, or CI is allowed. What we accept, what we reject, and why.