Skip to content

CONCEPT Cited by 2 sources

Macaroon token

Macaroon tokens are bearer tokens (like JWTs) that use a chained-HMAC construction allowing any holder to take an existing token and scope it down — add additional restrictions (caveats) — entirely on their own, without contacting the issuing authority.

Canonical Fly.io one-paragraph summary:

"Macaroon tokens are bearer tokens (like JWTs) that use a cute chained-HMAC construction that allows an end-user to take any existing token they have and scope it down, all on their own. You can minimize your token before every API operation so that you're only ever transmitting the least amount of privilege needed for what you're actually doing, even if the token you were issued was an admin token. And they have a user-serviceable plug-in interface!" (Source: sources/2025-03-27-flyio-operationalizing-macaroons.)

Construction (one-paragraph)

A Macaroon is: (1) a nonce identifying a root key in the authority's database; (2) a list of caveats (restrictions); (3) an HMAC chain where each caveat is hashed onto the previous tag. The final tag is computed using the authority's root key (known only to the authority). To attenuate the token, a caller appends a new caveat and rolls the HMAC forward using the current tag as the key — no root-key access required.

See concepts/chained-hmac-construction for the cryptographic detail.

Five wiki-relevant properties

  1. Offline attenuation. Scoping down a Macaroon does not require contacting the authority. Any holder can narrow the privilege before transmitting.
  2. Chainable verification. Verifying a more-specific Macaroon requires only that the parent's HMAC chain be valid — descendants don't need separate authority lookups. This enables very high verification cache hit rates.
  3. Online-stateful. Every verify starts by looking up the nonce in the authority's database. This is how revocation works (delete / blacklist the nonce → the whole token lineage dies), but it also means the authority must be reachable (or its decisions must be cached).
  4. Third-party caveats. A caveat can say "this token is only valid if accompanied by a discharge from authority X." This is how Fly.io bolts authentication (discharge from the auth service) onto an authorization-only token (concepts/authorization-vs-authentication-token).
  5. Bearer. Whoever holds the bytes can use them. Same risk profile as JWTs / session cookies.

Fly.io's practical experience

After two years as "the Internet's largest user of Macaroons," the user-facing pitch ("users can edit their own tokens", "email them to partners") has been lukewarm — "users don't really take advantage of token features." The internal wins have been the story: heavy offline attenuation as an infrastructure-side discipline, third-party caveats for privilege separation between services, and cacheability on the verification path.

Reference material

Seen in

Last updated · 200 distilled / 1,178 read