Docs/Macaroon Tokens

Macaroon Tokens

How SatGate uses macaroons for capability-based access control.

What are Macaroons?

Macaroons are bearer tokens with embedded caveats — conditions that must be satisfied for the token to be valid. Unlike JWTs, macaroons support attenuation: anyone holding a macaroon can add restrictions (narrow scope, reduce budget, shorten TTL) but can never remove them. This makes delegation safe by default.

SatGate uses macaroons as the native credential format. Every API request through the gateway carries a macaroon that encodes who the agent is, what it can do, and how much it can spend.

Caveat Types

scope = api:readAccess ControlRestricts which API operations the token can access. Supports wildcards: api:* grants all API scopes.

budget = 100EconomicMaximum credits this token can spend. Enforced in real-time by the gateway. When exhausted, requests return HTTP 402.

expires = 2026-03-01T12:00:00ZTemporalToken expiry timestamp. After this time, the token is rejected automatically.

ttl = 1hTemporalRelative expiry. Converted to an absolute timestamp at mint time.

tenant_id = abc-123IdentityBinds the token to a specific tenant. Used in multi-tenant deployments to isolate data and config.

subject = research-botIdentityIdentity binding. Links the token to the agent that requested it.

delegation = trueDelegationWhether this token can create child tokens. Set to false to prevent sub-delegation.

max_depth = 3DelegationMaximum delegation depth. Prevents unbounded delegation chains.

cost_center = engineeringGovernanceAccounting label for spend attribution. Appears in Shadow Report.

department = ai-researchGovernanceOrganizational label for spend attribution. Used in delegation tree reporting.

Delegation

Macaroons support hierarchical delegation. A parent token can mint child tokens with additional restrictions. Children can never exceed the parent's budget, scope, or TTL.

Root Token (admin)
  └─ scope = api:*,  budget = 1000,  ttl = 24h
     │
     ├─ Agent Alpha (delegated)
     │  └─ scope = api:read,  budget = 200,  ttl = 4h
     │     │
     │     └─ Sub-Agent (delegated)
     │        └─ scope = api:read:subset,  budget = 50,  ttl = 1h
     │
     └─ Agent Bravo (delegated)
        └─ scope = api:write,  budget = 500,  ttl = 12h

Cascade revocation: Revoking a parent token immediately invalidates all of its children. No propagation delay — the gateway checks revocation status on every request.

Macaroons vs JWTs

Feature	Macaroons	JWTs
Attenuation	✓ Add caveats anytime	✗ Immutable after signing
Delegation	✓ Native parent→child	✗ Requires new token from IdP
Revocation	✓ Instant cascade	~ Requires blocklist
Budget enforcement	✓ Embedded in caveats	✗ External system needed
Offline verification	~ Needs spend ledger	✓ Signature only
Ecosystem	~ Growing (Lightning, SatGate)	✓ Universal

SatGate Token Lifecycle

1.Mint — Agent presents workload identity (JWT). SatGate Mint exchanges it for a macaroon with budget, scope, and TTL caveats.

2.Use — Agent sends the macaroon as Authorization: Bearer on every request. Gateway verifies signature, checks caveats, deducts budget.

3.Delegate — Agent can create child tokens with tighter restrictions. Children inherit all parent caveats.

4.Enforce — Budget exhausted? HTTP 402. Token revoked? HTTP 401. Scope violation? HTTP 403. All enforced at the gateway.

5.Revoke — Admin revokes any token in the tree. All descendants are instantly invalidated. Zero propagation delay.