Access control

Every action you take in Spec0 — opening a page in the dashboard, publishing a spec from CI, calling a public API endpoint with a personal token — runs through the same access-control engine. This page is the contract: who can do what, under what conditions, and what to expect when a request is rejected.

The five-step decision

When you make a request, Spec0 runs through these steps in order. The first step that produces a verdict wins — later steps don't run.

Cross-organisation requests are structurally impossible — they fail at step 2, and the database-layer query filter (see ADR-0010) means even a buggy backend couldn't accidentally return another org's data.

Roles

Every user in your org carries one or more roles. Roles are how you grant permissions in bulk — instead of assigning api:view, team:view, subscription:view etc. one by one, you assign Org Member and the corresponding permissions come with it.

Spec0 staff also carry Platform Admin (backoffice console access) or Platform Super-Admin (every permission). These never apply to customer accounts.

Permissions

A permission is <resource>:<level>. Levels are hierarchical: admin includes manage includes view.

The platform also defines user:* and system:* permissions — those are reserved for Spec0 staff.

How team boundaries work

A few resources are team-scoped — APIs, mock servers, subscriptions. Even if you have api:manage, you can only modify APIs that your team owns. This means:

• A Team Member of Team A who has api:manage can publish new versions of Team A's APIs but cannot publish to Team B's APIs (denied at step 4: resource-specific rule).
• A user with no team assignment cannot perform any non-VIEW action on team-scoped resources, even if they have permissions.
• An Org Admin or Org Owner overrides this at step 3 — they can act on any team's resources within the org, no team membership required. This is by design and matches how org admins work in tools like GitHub or Linear.

Org-scoped resources (the org profile itself, member invitations, billing) don't have team boundaries — only org isolation and permission checks apply.

Accepted vs. rejected — examples

These walk through the five-step decision against real situations.

A team admin mints a service-account token for their own team.

1. Not super-admin → continue.
2. Same org ✓ → continue.
3. Has team:manage from Team Admin role, but not organisation:admin → continue.
4. Resource = team, action = manage. Resource rule: same-team check. userTeamId == resourceTeamId ✓ → continue.
5. Has team:manage permission ✓ → allowed.

The same team admin tries to mint a SAT for a different team.

1. Not super-admin → continue.
2. Same org ✓ → continue.
3. Not an org admin → continue.
4. Resource rule: same-team check. userTeamId ≠ resourceTeamId → denied at step 4.

An org admin mints a SAT for any team in their org.

1. Not super-admin → continue.
2. Same org ✓ → continue.
3. Has organisation:manage AND same org → allowed (skips step 4 entirely).

An org member of Org A views an API published by Org B (e.g. via a leaked URL).

1. Not super-admin → continue.
2. userOrgId ≠ resourceOrgId → denied at step 2. The Hibernate org filter additionally guarantees the read returns nothing even before authz runs.

A user with no team assignment tries to edit one of their org's APIs.

1. Not super-admin → continue.
2. Same org ✓ → continue.
3. Not an org admin → continue.
4. Resource rule: API is team-scoped, action is manage. User has no userTeamId → denied at step 4.

A CI service-account token (SAT) tries to publish a spec.

1. Not super-admin → continue.
2. Same org ✓ → continue.
3. SAT carries the team's permissions, not org-admin → continue.
4. SAT's userTeamId is the team it was minted for; spec's API belongs to the same team ✓ → continue.
5. Token's scopes include write:specs ✓ → allowed. (See Public API tokens for how scopes map to permissions.)

What you'll see when something is rejected

The HTTP response is always 403 Forbidden with this shape:

{
  "timestamp": "2026-05-02T10:42:00Z",
  "status": 403,
  "error": "Access Denied",
  "message": "Access denied",
  "reason": "User is not in same team as the API resource"
}

The reason field tells you which step rejected the request — useful for debugging. Common reasons:

Where to go next

• Teams — the multi-tenant model the access control runs against.
• APIs — what api:* permissions actually let you do.
• Subscriptions — subscription:* and the approval flow.
• Tokens — PAT vs SAT vs org API key, and how token scopes interact with the permissions on this page.