Wiki · Concept · Last reviewed June 25, 2026

Macaroons

Macaroons are authorization credentials that carry contextual caveats, letting authority be narrowed after issuance before a delegated credential is presented to a service.

Category: Concept Updated: June 25, 2026 Tags: macaroons, authorization, caveats, delegation, bearer credentials, AI agents, least privilege

Definition

Macaroons were introduced in the 2014 NDSS paper Macaroons: Cookies with Contextual Caveats for Decentralized Authorization in the Cloud by Arnar Birgisson, Joe Gibbs Politz, Ulfar Erlingsson, Ankur Taly, Michael Vrable, and Mark Lentczner. Google Research describes them as flexible authorization credentials for cloud services that support decentralized delegation between principals.

The core idea is attenuation. A bearer token usually carries whatever authority the issuer placed in it. A macaroon holder can add caveats that narrow when, where, by whom, or for what purpose the credential may be used. The holder cannot remove earlier caveats without invalidating the credential.

For agent systems, that makes macaroons useful as a design pattern even when a deployment uses a different token format. Delegated authority should become narrower as it moves from a user to an agent, then to a tool, then to a subtask.

How It Works

The paper's construction uses chained message authentication codes, commonly HMACs. A service creates a macaroon with an identifier and a cryptographic signature derived from a secret key. When a caveat is added, the macaroon's signature is updated through the chain, so later verification can detect tampering.

A first-party caveat is checked by the target service itself. Examples include expiry time, request path, maximum transaction size, allowed method, tenant boundary, or required device state. A third-party caveat requires another service to issue a discharge macaroon proving that an external condition has been satisfied.

The result is a credential that remains bearer-like in use but becomes attenuable in handling. A service can mint broad authority for a trusted caller; that caller can hand a narrower version to another process without returning to the issuer for every subdelegation.

Agent Context

Agent delegation often fails by overbroad credential reuse. A user authorizes a platform, the platform gives a worker a session token, and the worker can do more than the actual task required. Macaroons point toward a better shape: each handoff can add caveats that make the next credential smaller.

A research agent might receive a credential limited to one corpus, one project, read-only access, and a short lifetime. A coding agent might receive a credential limited to one repository branch, no secrets directory, and no deployment action. A procurement agent might receive a credential limited to quote preparation but not purchase submission.

Macaroons do not decide whether an action is wise. They help encode bounds on authority. The application still needs policy, identity, logging, revocation, and human-facing controls.

Governance Risks

The first risk is bearer-token replay. A macaroon can be attenuated, but whoever holds a valid macaroon can present it unless the deployment adds binding, transport protection, short lifetimes, or other replay defenses. Caveats reduce scope; they do not make secret handling optional.

The second risk is caveat ambiguity. The macaroon mechanism does not standardize every caveat language. If one service interprets project=alpha differently from another, attenuation becomes a formatting ritual instead of a real restriction.

The third risk is revocation. Caveats can impose expiry and context checks, but a long-lived delegated credential still needs revocation strategy, issuer key rotation, denial lists, or stateful checks for high-impact workflows.

Governance Pattern

Source Discipline

Use the paper PDF, Google Research publication page, and NDSS 2014 record for the paper title, authors, venue, date, and central technical claims: chained MAC construction, bearer-credential deployment, caveats, decentralized delegation, and contextual confinement.

Do not present macaroons as a complete agent-governance system. They are a credential mechanism. User intent, task policy, data classification, monitoring, appeal, incident response, and social legitimacy remain outside the token.

Spiralist Reading

Spiralism reads macaroons as a discipline of shrinking power as it travels.

The credential should not become a wandering master key. Each delegation should carry a visible scar: a caveat that says what the next holder may not do, when the permission ends, and which authority must confirm the condition.

Open Questions

Sources

Return to Wiki