Subscriptions
How a team declares a dependency on another team's API, what permissions they request, and how the API owner approves.
A subscription is one team's permission grant on another team's API — a first-class object in the registry, not an HTTP convention. The subscriber says "we want to call these operations on your API"; the API's team admin reviews and approves; the result is a record that connects 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).
Two views, one object
| Route | Audience | What it shows |
|---|---|---|
/subscriptions | Subscriber team | Every API your team consumes, with the permissions granted on each. |
/subscribers | Producer team | Every team consuming the APIs you publish. Approve, reject, revoke. |
Both views read the same subscription rows from the registry, filtered by which side of the relationship the viewer is on.
Subscribing
From the UI: Subscriptions → New → pick an API → select the operations you want to invoke → submit. The API's team admin sees the request appear in their /subscribers view and approves, rejects, or comes back with questions.
From the CLI: spec0 subscribe. Same backend endpoint, same approval flow. Useful when a service's CI bootstraps its dependencies declaratively.
State
PENDING ── admin approves ─▶ ACTIVE
│ │
└── admin rejects ─▶ DENIED │
│
ACTIVE ── consumer cancels ─▶ CANCELLED
ACTIVE ── producer revokes ─▶ REVOKEDDENIED, CANCELLED, REVOKED are terminal — re-subscribing creates a new row. Only ACTIVE subscriptions receive change notifications from the producer side (Events).
What the subscription captures
| Field | Meaning |
|---|---|
| Consumer team | The team that requested the subscription. |
| API | The team-owned API the subscription 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. |
| Subscription 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 subscriptions. A consumer that subscribed 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
Subscriptions 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 subscription 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 subscription is approved, Spec0 registers a corresponding client in your IAM provider and binds the IAM client ID to the subscription 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 → subscription ID → approved permissions — is auditable end-to-end inside Spec0.
Today, treat subscriptions 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 subscription state through the org-scoped MCP tools (search APIs, list APIs you depend on). Mutating subscriptions through MCP is intentionally not exposed — declaring a dependency is a deliberate human act with an approval flow, not an agent shortcut.
Where to go next
- APIs — what gets subscribed to.
- Events — change notifications that flow off active subscriptions.
- Teams — who can subscribe and who can approve.
spec0 subscribe— the CLI surface.
Teams
How users group, who owns which API, who approves subscriptions — the multi-tenant model behind every action in the platform.
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.