Delegation Scope Design Guide

An API key leaks from a CI log. Rotation day becomes an outage day. Nobody can say which agent used which capability on whose behalf — the key was god-mode, shared, and immortal until someone noticed.

That model worked when the only holder was a server you owned. It does not work when the holder is an AI agent operating on a human’s behalf.

HUMΛN replaces API keys with delegation tokens: a signed cryptographic contract — this human (or org) grants this agent these specific scopes for this specific window, with these specific constraints. The MCP surface and API enforce them on every call.

Scroll-stopper: A token without expiry is an API key with extra steps.

So that builders mint least-privilege grants, revoke by session, and keep “AI did it” replaceable with “this principal under this grant.”

What a delegation actually is

Field	Meaning
from	The principal granting authority (DID — passport or org).
to	The principal receiving authority (the agent's DID).
scope	The set of capabilities granted, as a list of scope strings.
constraints	Optional bounds — rate limits, IP ranges, time windows, value caps.
expires_at	A hard expiry; tokens never live forever.

The token is signed with the granter's passport key. Verifiers check the signature and the revocation registry — they do not need a permanent “trust HUMΛN” phone-home for authenticity.

The MCP scope vocabulary

Scopes you’ll use day-to-day:

Scope	Grants	Doesn't grant
kb:read:public	Read Public-classified docs + Canon	Org-internal docs
kb:read:internal	Read Internal-classified docs	FoundersOnly
companion:chat	Multi-turn companion chat + preferences	KB ingest, arbitrary execution without other scopes
human_api:agents:invoke	POST /v1/agents/call / human.call	Per-capability scopes or the risk gate
humanos:read / humanos:write	Intent / HumanOS REST routes	Whatever the route policy does not cover
human_api:passports:read	Read passport data	Mutate passports
human_api:passports:write	Mutate passports	Cross-tenant
org:settings:read / org:settings:write	Org settings	Beyond that surface
cloud:admin:*	Internal HUMΛN team admin surfaces	Outside HUMΛN org

There are more (event emit, marketplace, signals). See Delegations concepts for the public vocabulary.

Note: There are no call:propose / call:execute delegation strings. human.call uses a mode field (propose vs execute).

Principle of least privilege

Start with the smallest grant that lets your agent do something useful:

# A read-only Cursor companion
human delegation mint \
  --to did:agent:my-cursor \
  --scope kb:read:public \
  --scope companion:chat \
  --duration 30d

It can answer questions and search the KB. It cannot do anything destructive. Need more? Expand the scope — don’t reach for a wildcard.

human.call is mode-aware (not two scopes)

• mode: "propose" — surface a plan or dry-run; UI can require approval before a later execute.
• mode: "execute" — perform the action; the API risk gate still enforces requires_approval on irreversible work.

For interactive tools (Cursor, Claude Code), default to propose first. For autonomous reversible work (cron summaries), execute may be appropriate when policy allows.

Constraints: the underrated lever

{
  "rate_limit": "60/min",
  "value_cap_usd": 100,
  "allowed_capabilities": ["calendar.events.create", "kb:search"],
  "ip_allowlist": ["10.0.0.0/8"]
}

Right of way and speed limit.

Revoking without breaking everything

Console Settings → MCP Access lists every active session. Revoke one and:

• The KV cache in the MCP Worker drops the session immediately.
• The API marks the session row revoked.
• Subsequent calls return 401 with revoked_at in problem details.
• Other agents keep working.

Revocation is per-session, not per-key.

Org-level vs user-level delegation

Most agents act for a specific user (from: did:passport:...). Workflows and scheduled jobs may act for the org (from: did:org:...). Same grant pattern; different audit trail (which org admin minted it).

When in doubt: user-level. Org-level should be rare and always carry an admin name in provenance.

Common mistakes

1. Granting * “just for testing.” Never stays that way. Mint scoped tokens even in dev.
2. Forgetting expires_at. See the scroll-stopper.
3. One delegation across multiple integrations. Hard to revoke one without breaking others. One agent → one delegation.
4. Using cloud:admin:* outside HUMΛN team. Gated; you’ll get 403.

Tooling

• human delegation mint / list / revoke <id>
• Console → Settings → Delegations
• Console → Settings → MCP Access — MCP sessions specifically

Market context (not category drift)

Enterprise auth vendors are converging on the same problem: agents must not borrow user sessions or embed static API keys. That validates the pain. HUMΛN’s differentiation is architectural — human-owned delegated authority with provenance-native proof (Authorization: Bearer + JWT), not “better OAuth for agents.”

Effective authority at invoke time: Agent Capability ∩ Delegation Scope ∩ Resource Policy ∩ Risk Boundary ∩ Human Consent.

Go deeper

• Product: Passport, Developers
• Docs: CLI identity, Delegations concepts
• Community: Passport & delegation as MCP primitives, Sandbox to production, Intent routing architecture