Macaroons, Biscuit and UCAN

Compare three real attenuable-credential designs — macaroons, Biscuit and UCAN — on how each performs attenuation and caveats, whether it can be verified offline and by third parties, and the documented trade-offs of each. They are related but NOT equivalent.

Track

Engineering

Module

3 · Cryptographic delegation

Prerequisites

Scope attenuation · Delegation chains · Signed short-lived credentials

All three of these are attempts at the same high-level goal: a credential that can be narrowed as it travels, so a holder can pass on strictly less authority than it received, without asking the original issuer. That is attenuation (Module 3.2) made into a concrete token format. The reason there are three — and not one — is that the goal leaves real design choices open, and each project answered them differently. Those answers determine who can verify a token, whether a shared secret is needed, and how expressive the constraints can be.

The single most important distinction is cryptographic: macaroons are built on symmetric HMAC, while Biscuit and UCAN are built on public-key signatures. That one choice ripples through everything else — most of all, whether a party who shares no secret with the issuer can still verify the token.

Macaroons (Birgisson et al., Google, 2014) are bearer tokens whose integrity comes from an HMAC chain: the token starts from a secret root key, and each caveat is added by HMAC-ing the running signature with the new caveat. Anyone holding the macaroon can append a caveat (attenuate) offline, because appending only requires the current signature, not the root key. But verification requires the root secret, so the verifier is typically the same party (or domain) that issued it. First-party caveats are predicates the verifier checks itself; third-party caveats are discharged by separate "discharge macaroons" obtained from a named third party, which is macaroons' mechanism for involving other parties despite the symmetric core.

Biscuit (originated at Clever Cloud) and UCAN (User Controlled Authorization Networks, developed in the Fission / DIF community) both use public-key cryptography, so the root authority is a public key and any party holding it can verify — no shared secret. Biscuit attaches an authorization language based on Datalog: blocks carry facts, rules and checks, and appended blocks can only add restrictions. UCAN expresses capabilities as resource + ability + caveats and builds delegation chains by referencing parent tokens as proofs, with each delegation independently signed by a DID key and validated so the child never exceeds the parent. Both formats have evolved across versions (Biscuit's signing scheme changed between v1 and v2; UCAN began JWT-based and later restructured its encoding), so pin to a specific spec version in practice.

Caveat / block / check

A restriction added to a token. Macaroons call them caveats (opaque predicates); Biscuit uses Datalog checks inside blocks; UCAN uses caveats scoping a capability. In all three, adding one can only narrow authority.

Offline attenuation

Narrowing a token without contacting the issuer. All three support it; macaroons need only the current token, Biscuit/UCAN sign the new restriction with the attenuating party's key.

Third-party verifiability

Can a party sharing no secret with the issuer verify the token? Macaroons: no in general (HMAC needs the root secret). Biscuit/UCAN: yes (public-key).

Discharge macaroon

A separate macaroon proving a third-party caveat is satisfied — macaroons' way of involving other parties without public-key crypto.

Authorization language

How constraints are expressed and evaluated. Biscuit uses Datalog; macaroons use application-defined predicate checks; UCAN uses structured capability+caveat semantics.

The honest comparison is a table of differences, not a ranking. Each row is a design axis where the three diverge.

macaroons vs Biscuit vs UCAN (documented differences)
axis                 Macaroons              Biscuit                 UCAN
-----------------    ------------------     -------------------     --------------------
crypto core          symmetric HMAC         public-key signatures   public-key signatures
                     (root SECRET)          (root PUBLIC key)       (DID keys)
verify needs         the root secret        issuer's PUBLIC key     issuer's PUBLIC key
third-party          not in general;        yes                     yes
 verifiable?         (needs shared secret)  (public-key)            (public-key)
offline attenuation  yes (append caveat,    yes (append signed      yes (delegate, signed
                      no key needed)         block)                  by delegator key)
constraint model     opaque predicates      Datalog facts/rules/    capability (resource+
                     (1st/3rd-party caveat)  checks                  ability)+caveats
multi-party / 3rd    discharge macaroons    3rd-party blocks        delegation chain via
 parties             (extra tokens)                                 referenced proofs
identity model       (app-defined)          keypairs                DIDs
maturity note        2014 paper + libs;     evolving spec, several  evolving spec; format
                     widely cited            versions                changed across versions

Read the table as "pick the trust model first." If every verifier already shares the root secret (one service verifying its own tokens), macaroons are simple and fast. If verifiers must check tokens without any shared secret — across teams, services or organizations — you need the public-key designs, and then you choose between Biscuit's Datalog expressiveness and UCAN's DID/capability-chain model.

1. 1Establish who must verify. Same party/domain that issues? Symmetric (macaroons) is viable. Unrelated parties with no shared secret? You need public-key (Biscuit or UCAN).
2. 2Check your third-party needs. If authorization depends on assertions from other parties, compare macaroons' discharge tokens vs Biscuit third-party blocks vs UCAN referenced proofs.
3. 3Decide how expressive constraints must be. Rich policy logic favours Biscuit's Datalog; capability-centric resource/ability modelling favours UCAN; simple predicate checks suit macaroons.
4. 4Consider identity integration. UCAN builds on DIDs; Biscuit on raw keypairs; macaroons leave identity to the application.
5. 5Weigh maturity and ecosystem for your stack, and pin a specific spec version — all three (especially Biscuit and UCAN) have changed meaningfully across versions.
6. 6Regardless of choice, still verify end-to-end (Module 3.3), enforce attenuation as subset (Module 3.2), and prefer short lifetimes (Module 3.4).

synthetic — the same narrowing in each style
# Macaroon (symmetric): holder appends caveats offline; verifier needs root SECRET.
m = macaroon(root_secret, id="vault:A")
m = add_first_party_caveat(m, "path = vault:A/reports/q3.pdf")
m = add_first_party_caveat(m, "op = read")
m = add_first_party_caveat(m, "exp < T")
# verify(m, root_secret): recompute HMAC chain + check each caveat predicate.

# Biscuit (public-key + Datalog): append a block; verify with root PUBLIC key.
#   block adds checks:
#     check if resource("vault:A/reports/q3.pdf");
#     check if operation("read");
#     check if time($t), $t < T;
# verify(biscuit, root_public_key, authorizer_facts): run Datalog, all checks must pass.

# UCAN (public-key + DID chain): delegate a narrowed capability, signed by delegator DID.
#   capability: { with: "vault:A/reports/q3.pdf", can: "store/read" }
#   each delegation references its parent as proof; child <= parent is enforced.
# verify(ucan): walk proof chain to a trusted DID, check each hop attenuates.

# Same GOAL (read one file, read-only, until T). Different trust models and checks.

The intent is identical; the machinery is not. The macaroon verifier must hold the root secret; the Biscuit and UCAN verifiers need only a public key, which is precisely why only the latter two suit cross-organization verification.

For agent systems these formats are concrete options for carrying attenuated, delegable authority between agents and tools. Within a single trust domain where one service both issues and verifies, macaroons' simplicity and offline attenuation are attractive. For multi-agent or multi-organization settings — where an executor must verify authority it did not issue, possibly offline and across a trust boundary — the public-key designs (Biscuit, UCAN) fit the cross-domain verifiability requirement from Module 3.5, because no shared secret has to cross the boundary.

Whichever you adopt, the earlier modules still govern correctness: attenuation must be enforced as a real subset check, chains must be verified end-to-end against a trust anchor with bounded depth and no cycles, and short lifetimes remain the pragmatic answer to the revocation problem these bearer-style tokens all share. The format is the mechanism; the discipline is what makes it safe.

• ▸Do not treat them as equivalent. Macaroons' symmetric core means the verifier needs the root secret — a genuinely different trust model from Biscuit/UCAN, not a minor detail.
• ▸All three are broadly bearer-style: a stolen token is usable by whoever holds it. Bind to a holder key where the format allows, keep lifetimes short, and do not rely on revocation lists as the primary control.
• ▸Caveats/checks must fail closed. A constraint a verifier does not understand or cannot evaluate must reject the token, or attenuation silently widens.
• ▸Spec and version drift is real: Biscuit and UCAN have changed formats/schemes across versions; pin a version and track its security guidance rather than assuming stability.
• ▸Expressive policy (Biscuit Datalog, UCAN capability semantics) adds power and implementation/complexity risk — more surface to get wrong in the authorizer.
• ▸Macaroons' third-party caveats require extra discharge tokens and coordination; the convenience of offline attenuation does not extend freely to multi-party trust.
• ▸Across all three: cryptographic authorization is not a safe agent decision. These formats bound authority; they do not supply judgement.

Expected direction: Case 1 (same party issues and verifies, offline attenuation) fits macaroons: symmetric HMAC is fine because the verifier already holds the root secret, and holders can append caveats offline. Case 2 (cross-organization verification with no shared secret) needs a public-key design — Biscuit or UCAN — because verification must use only the issuer's public key. The deciding property is the crypto core: symmetric HMAC (macaroons) requires the verifier to share the root secret, so it is not third-party verifiable; public-key signatures (Biscuit, UCAN) are verifiable by anyone holding the public key.

What is the single most important difference between macaroons and Biscuit/UCAN?

Crypto core: macaroons use symmetric HMAC, so the verifier needs the root secret and they are not third-party verifiable in general; Biscuit and UCAN use public-key signatures, so any holder of the public key can verify without a shared secret.

How does each express attenuation/constraints?

Macaroons: appended caveats (opaque first-party predicates, plus third-party caveats via discharge macaroons). Biscuit: appended blocks of Datalog facts/rules/checks. UCAN: narrowed capabilities (resource+ability+caveats) delegated down a signed proof chain. All can only narrow.

Is a valid token from any of these a sufficient basis for an agent to act?

No. It proves authority was granted and correctly attenuated, but not that acting is correct or safe. Cryptographic authorization is distinct from a sound agent decision, in all three formats.