# Delegation scope vocabulary

**Canon:** kb/20 §Passport Identity, kb/101 §API Design Standards, kb/22 §HumanOS.

This article is the canonical scope reference for HUMΛN MCP delegations. AI clients should construct **minimal** delegation requests — only the scopes the integration actually needs.

## Format

A scope is a colon-separated string: `<resource>:<action>:<modifier>`.

- `<resource>` — the API surface (`kb`, `companion`, `humanos`, `human_api`, `org`, `cloud`, `signals`, `events`, `workforce`).
- `<action>` — the operation (`read`, `write`, `chat`, `call`, `mint`, `revoke`, `ack`, `emit`, …). **Note:** `human.call` uses a JSON **`mode`** field (`propose` \| `execute`); those words are not separate scope strings.
- `<modifier>` — optional qualifier (`public`, `internal`, `org`, `*`, etc.).

## One canonical scope vocabulary (no Console / Platform split)

There is **one** canonical vocabulary for every route family — there is no longer a "Console / Command Plane shorthand" that bridges into the platform API at the boundary. The API enforces the same canonical strings whether the request hits `/v1/control-plane/...`, `/v1/agents`, `/v1/workflows`, or any other surface (source of truth: `apps/api/src/lib/required-scope-policies.ts`).

| Surface | Canonical scopes | Typical path prefix |
|---|---|---|
| **Agents** | `human_api:agents:read`, `human_api:agents:manage`, `human_api:agents:invoke`, `human_api:agents:autonomy:write` | `/v1/agents`, `/v1/control-plane/agents` |
| **Incidents** | `incidents:read`, `incidents:write` | `/v1/control-plane/incidents` |
| **Devices** | `devices:read` | `/v1/control-plane/devices` |
| **HumanOS / Workflows** | `humanos:read`, `humanos:write`, `humanos:admin` | `/v1/workflows`, `/v1/intent`, `/v1/builder` |
| **Audit** | `audit:read`, `audit:admin` | `/v1/control-plane/audit` |
| **Cloud Admin** | `cloud:admin:global` (super-scope) ⊃ `cloud:admin:billing` \| `cloud:admin:infra` \| `cloud:admin:analytics` \| `cloud:admin:support` | `/v1/control-plane/cloud-admin` |

**Pre-debut cleanup:** the legacy CP-shorthand (`agents:read`, `agents:manage`, `agents:autonomy:write`, `cp_incidents:read`, `cp_incidents:write`, `cp_devices:read`, `companion:control-plane:read`) and every `anyOf`-style "either-namespace" bridge were removed in one shipping wave. Mint canonical scopes everywhere — the Console, hosted MCP Worker, third-party clients, and CLI all speak the same vocabulary.

**Cloud Admin hierarchy:** the middleware understands that `cloud:admin:global` satisfies any `cloud:admin:<sub>` requirement, so policies declare the most specific scope they need (e.g. `cloud:admin:billing` for `/cloud-admin/billing`). A holder of `cloud:admin:global` is admitted automatically.

**Workflows:** `GET /v1/workflows` and `GET /v1/workflows/:id/dag|stats` require **`humanos:read`**; `POST .../pause|resume|trigger` requires **`humanos:write`**.

## KB scopes

| Scope | Grants | Constrains |
|---|---|---|
| `kb:read:public` | Read 58 Public docs + Canon RAG corpus + public AI articles. | No Internal/Partner/Founders. |
| `kb:read:internal` | Read Internal-classified docs (HUMΛN team or admin-granted slice). | No Founders. |
| `kb:read:partner` | Read ExternalPartner docs scoped to the partner's DID. | No Internal/Founders. |
| `kb:read:org` | Read the org's installed KB (Confluence/Notion/Drive). | Only the org's KB. |
| `kb:read:personal` | Read the user's personal KB. | Only the user's KB. |
| `kb:write:org` | Ingest into the org's KB. | Only with admin grant. |

## Companion scopes

| Scope | Grants | Constrains |
|---|---|---|
| `companion:chat` | Multi-turn `human.ask` and `human.companion.chat`, **and** read/write of Companion preferences (`GET`/`PUT`/`DELETE` `/v1/companion/preferences` and related observe/pending/ack routes). Cursor-style rules live here — there is **no** separate `companion:preferences:write` scope string today. | No KB ingest, no arbitrary HumanOS execution without other scopes. |

## HumanOS / capability scopes

| Scope | Grants | Constrains |
|---|---|---|
| `humanos:read` / `humanos:write` | HumanOS / intent REST (`/v1/intent`, `/v1/builder`, **`/v1/workflows`** list + dag/stats read; workflow pause/resume/trigger write). Tier 2 `human.intent` uses **`humanos:write`**. | Granular; mint what your client actually calls. |

### `human.call` is **mode-aware**, not two delegation scopes

There are **no** separate delegation scopes named `call:propose` or `call:execute`. The `human.call` tool takes a **`mode`** argument (`"propose"` \| `"execute"`). The hosted Worker and API both require **`human_api:agents:invoke`** for `POST /v1/agents/call`. The risk gate, plan tier (e.g. hosted Worker `minPlan`), and each capability’s requirements decide what runs; irreversible work still honors `requires_approval`. Mint **`human_api:agents:invoke`** plus whatever narrower scopes your integration reads from API errors as `required_scope`.

## API resource scopes

| Scope | Grants | Constrains |
|---|---|---|
| `human_api:passports:read` | Read passport data. | No mutation. |
| `human_api:passports:write` | Mutate passports. | Cannot cross tenants. |
| `human_api:agents:invoke` | Invoke `POST /v1/agents/call` (`human.call` MCP tool). | Does not replace scopes required by the target capability. |
| `human_api:capability_graph:read` | Capability graph query/search (`human.capability.discover` and related REST). | No grants or proofs. |
| `human_api:delegations:write` | Mint and revoke delegations. | Bound to the granter's authority. |
| `org:settings:read` | Read org settings. | Single org. |
| `org:settings:write` | Modify org settings. | Single org, requires org admin. |
| `signals:read` | Read pending signals. | Scoped to the user/org. |
| `signals:write` | Acknowledge signals. | Same. |
| `events:emit` | Emit custom events. | Bound to the calling agent's DID. |
| `workforce:read` / `workforce:write` | Read/mutate workforce tasks. | Scoped. |

## Internal-only scopes (HUMΛN team)

These exist for HUMΛN's own team. AI clients outside HUMΛN should never request them — the API will reject the mint.

| Scope | Surface |
|---|---|
| `cloud:admin:billing` | `billing_config` read/write. |
| `cloud:admin:infra` | Infra-style admin operations (e.g. cache flush) as enforced on the API. |
| `cloud:admin:support` | Tenant lookup. |
| `cloud:admin:global` | Tenant suspend, high-blast operations. |

## Constraints (orthogonal to scope)

A delegation can also carry constraints that further bound the grant:

- `expires_at` — hard expiry, ISO 8601 timestamp. Always present.
- `rate_limit` — e.g. `60/min`. Enforced at the API edge.
- `value_cap_usd` — cap on cumulative USD value the delegation can authorize.
- `allowed_capabilities` — explicit allowlist of capability IDs.
- `ip_allowlist` — CIDR ranges.
- `org_filter` — restrict the delegation to a specific org DID.

## Constructing a minimal delegation

For a Cursor read-only assistant:
```
kb:read:public companion:chat
```

For a workflow-builder agent that uses `human.call` in **propose** mode (surface plans, no execute):
```
kb:read:public companion:chat human_api:agents:invoke
```
(Execute paths still need the right capability scopes and often a higher plan tier — see `human.call` **mode** above.)

For an autonomous, scoped workflow runner that may call **`human.call` in `execute` mode**:
```
companion:chat human_api:agents:invoke workforce:write
```
(Add every scope the underlying capabilities require; treat API `403` + `required_scope` as the source of truth.)
plus constraints:
```
{ "rate_limit": "60/min", "value_cap_usd": 100, "expires_at": "2026-05-28T00:00:00Z" }
```

## Anti-patterns

- **`*`** — no wildcard scopes are minted by default. Don't ask.
- **Long-lived delegations.** Default to ≤30 days; renew on demand.
- **Mixing user and org delegations.** One agent → one delegation.
- **Reusing one delegation across multiple integrations.** Hard to revoke without breaking peers.

## How to mint

```bash
human delegation mint \
  --to did:agent:<agent_did> \
  --scope "kb:read:public companion:chat" \
  --expires-in 30d \
  --constraints '{ "rate_limit": "60/min" }'
```

The token is printed once; store it in the AI client's secret store.