Join our Newsletter — 33% off our NHI Course
Home› Guides› Capability Tokens Guide: Macaroons, Biscuits and UCAN for…
Guide Authorisation

Capability Tokens Guide: Macaroons, Biscuits and UCAN for Offline Attenuation

PDF for newsletter subscribers · free to read online

← All guides
By NHI Mgmt Group, edited by Lalit Choda Updated 11 November 2026 16 min read
On this page

Most service and agent tokens can only be narrowed by going back to the server that issued them, so in practice they are passed along at full strength. Capability tokens change that: the holder can derive a weaker token locally, with no call to the issuer, and hand only that weaker token to the next service, script or AI agent. Three formats dominate the field: macaroons (Google research, 2014), Eclipse Biscuit and the User Controlled Authorization Network (UCAN) specification. This guide explains how each one attenuates authority, how they differ on verification, revocation and replay, and how to deploy them safely for workloads and agent delegation. It is written for architects and engineers designing authorisation between services, and for identity teams assessing whether capability tokens belong in their agent platform. Formats are covered in order of publication.

Key takeaways

  • Attenuation is offline and one way. In all three formats a holder can add restrictions without the issuer, and nobody can remove a restriction without breaking the cryptography.
  • Verification model is the main design choice. Macaroons use chained HMACs, so only the party holding the root secret can verify; Biscuit and UCAN use public key signatures, so any service with the right public key or DID can verify.
  • They are still credentials. Macaroons and Biscuit are bearer tokens; UCAN names an audience and signs invocations, but a stolen key or a stolen broad token is still a breach. Short expiry and narrow root grants matter more than the format.
  • Revocation needs a plan. Offline verification means no central check by default. Biscuit exposes revocation identifiers and UCAN defines a revocation sub-specification, but someone has to distribute and check the revocation list.
  • Agent delegation is the strongest use case. A planner agent can hand a sub-agent a token limited to one command, one resource and a few minutes, which shrinks the blast radius of prompt injection and tool misuse.

What a capability token is, and how it differs from OAuth scopes

A capability token is a credential that carries its own authority: possession of the token (plus, in some formats, the matching key) is what grants access, and the token itself says what may be done. The general model is covered in the Capability-Based Security Guide; this page is about three concrete token formats.

The defining property is offline attenuation. An OAuth access token is minted by an authorisation server and is opaque or fixed for the client: to get a narrower token the client must call the server again, for example with token exchange (see the OAuth Token Exchange and Delegation Guide). A capability token lets the holder append a restriction, such as "read only", "only account 42" or "expires in five minutes", and the result is still valid but strictly weaker. The libmacaroons documentation states the property directly: it is easy to add a caveat and impossible to remove one.

PropertyTypical OAuth access tokenCapability token (macaroon, Biscuit, UCAN)
Who can narrow itOnly the authorisation server, on requestAny holder, locally, without contacting the issuer
Where policy livesMostly in the resource server, keyed on scopes and claimsPartly in the token (caveats, checks, policies), evaluated with the server's own rules
Delegation chain visibilityLost unless an actor claim or transaction token carries itBuilt in: each attenuation is a block, caveat or linked delegation
Central dependency at use timeIntrospection or JWKS fetchRoot secret (macaroons) or root public key or DID (Biscuit, UCAN)
RevocationShort lifetime, introspection, token revocation endpointShort lifetime plus revocation identifiers or revocation records that verifiers must check

Macaroons: chained HMACs and contextual caveats

Macaroons were introduced by Birgisson, Politz, Erlingsson, Taly, Vrable and Lentczner in the paper "Macaroons: Cookies with Contextual Caveats for Decentralized Authorization in the Cloud" at NDSS 2014. They are bearer credentials built from nested, chained MACs such as HMAC, and their caveats restrict when, where, by whom and for what purpose a request may be authorised.

How the chain works

  • Minting: the service creates a macaroon from a root secret, a location hint and an identifier. The signature is an HMAC under the root secret.
  • First-party caveats: each added caveat (for example account = 3735928559 or time < 2027-01-01T00:00) produces a new signature computed by keying an HMAC with the previous signature. A holder can append caveats but cannot recover an earlier signature, so caveats cannot be stripped.
  • Third-party caveats: a caveat can require proof from another service, such as an authentication service saying "the user is Alice". The holder fetches a discharge macaroon from that third party, and the libmacaroons prepare_for_request step binds the discharge to the root macaroon so it cannot be reused with another one. Without binding, verification fails.
  • Verification: the verifier recomputes the chain from the root secret and checks every caveat against the request context, either as exact matches or through general predicate callbacks. Unknown caveats fail.

The consequence of symmetric cryptography is that only a service holding the root secret can verify a macaroon. That suits a single service or a tightly coupled set of services sharing a key store, and it keeps verification very fast. It does not suit open ecosystems where many independent verifiers need to check the same token without receiving the secret. Macaroons also carry no built-in proof of possession, so a leaked macaroon works for whoever holds it until a caveat (usually time) stops it.

Biscuit: public key chains and Datalog policies

Biscuit is now an Eclipse Foundation project (Eclipse Biscuit, incubating, Apache 2.0 licence). Its specification describes it as a bearer token that supports offline attenuation, can be verified by any system that knows the root public key, and uses an authorisation language based on logic programming. Tokens are serialised as Protocol Buffers and are designed to be small enough for an HTTP cookie.

  • Blocks: the first block is the authority block with the rights granted by the issuer. Each later block adds checks that reduce the token's scope. A holder can add a block but cannot remove one without invalidating the signature chain.
  • Key chain: each block carries the serialised Datalog, the next public key and a signature by the previous key. The token holds the private key for the last public key so the holder can sign one more block; attenuation uses ephemeral key pairs meant to be destroyed after use.
  • Sealing: a token can be sealed, which signs the last block with the last private key and prevents further attenuation. Seal tokens at the point where no further delegation should happen.
  • Checks: written as check if, check all (from Datalog v3.1) or reject if (from v3.3). Every check in the token and in the authoriser must succeed. Expiry is expressed as a check on the current time.
  • Allow and deny policies: defined only in the authoriser, tested in order after all checks pass. If no policy matches, authorisation fails, so the default is deny.
  • Third-party blocks: a block signed by an external party with its own key, used to add a fact that only that party can vouch for, such as group membership, similar in purpose to a macaroon third-party caveat.
  • Algorithms: Ed25519 is the default; ECDSA over secp256r1 with SHA-256 is also supported, with deterministic signatures (RFC 6979) recommended. The algorithm can differ between blocks.
  • Revocation identifiers: the authoriser generates a revocation_id fact for each block, derived from the block signature, which the service can compare against a deny list.

Datalog lets a token say things such as "this token may only read resources owned by user 1234" and the service add its own facts (the requested resource, the operation, the time) at request time. The trade-off is that policy now spans two places: the token and the authoriser. Teams need to test both together and keep the authoriser's policies under change control.

UCAN: DIDs, delegation chains and signed invocations

The UCAN specification (Version 1.0.0, maintained by the UCAN working group on GitHub, checked 11 November 2026) describes a trustless, local-first, user-originated authorisation scheme with public key verifiable, delegable capabilities. It adopts a certificate capability model related to SPKI, represents principals as decentralised identifiers (DIDs) and splits the detail into Delegation, Invocation, Promise and Revocation sub-specifications.

  • Capability: the association of a subject, a command and a policy. The subject is the DID that owns the resource. Commands are lowercase slash paths such as /crud/read or /msg/send; a shorter command proves a longer one, so /crud covers /crud/read. The top command / grants everything and the specification says it should be used sparingly.
  • Policy language: delegations carry a pol field of predicate statements with jq-style selectors, for example restricting .from to one address. Policies constrain the arguments of the eventual invocation.
  • Attenuation rule: each delegation must restate or diminish the capabilities it received.
  • Issuer and audience: every UCAN is signed by the issuer DID (iss) and names the recipient DID (aud), which must check that it is the audience. Invocations are signed requests to use a delegated capability, so an intercepted delegation alone is not enough to act.
  • Time bounds and nonce: nbf is optional and exp is required in the payload, where null means never expires; the specification recommends always setting an expiry. A nonce is required.
  • Replay prevention: required. Every invocation must have a unique content identifier (CID), and the executor checks it against a store of unexpired UCAN hashes.
  • Cryptography and encoding: Ed25519 (preferred), P-256 or secp256k1 signatures, did:key identifiers, canonical DAG-CBOR encoding and canonical Varsig signatures so a third party cannot create a second valid signature.
  • Powerline: a delegation with sub: null automatically passes on all future delegations, for example across a user's own devices. The Delegation specification warns it is very powerful and must not be the root delegation.

The UCAN specification states plainly that it has no special protection against person-in-the-middle attacks and strongly recommends delegating only to trusted, authenticated agents over secure channels. Validation happens at execution time, so expiry and revocation are checked when the capability is actually used.

Choosing a format

QuestionMacaroonsBiscuitUCAN
CryptographyChained HMAC (symmetric)Signature chain, Ed25519 default or ECDSA P-256Signed delegations and invocations, Ed25519 preferred, P-256, secp256k1
Who can verifyOnly holders of the root secretAnyone with the root public keyAnyone who can resolve the DIDs in the chain
Restriction languageCaveat strings checked by verifier callbacksDatalog checks in the token, policies in the authoriserCommand hierarchy plus predicate policy on invocation arguments
Holder bindingNone (bearer)None (bearer)Audience DID and signed invocation
External attestationsThird-party caveats and discharge macaroonsThird-party blocksAdditional delegations in the proof chain
Stopping further delegationNot built in; use caveats and short expirySealed tokensNarrow commands and policies; no wildcard / or Powerline
Revocation hooksService-defined (for example a caveat on a version number)Per-block revocation identifiersRevocation sub-specification, revocation invalidates derived tokens
Best fitOne service or a few sharing a key store, very low latencyMicroservices and APIs that need rich policy and offline verificationDecentralised or local-first apps, cross-organisation and agent-to-agent delegation keyed to DIDs
  • Small team, single API: a well-scoped, short-lived OAuth or JWT access token is usually simpler. Capability tokens earn their keep once there is real delegation between services or agents.
  • Many internal services, one platform team: Biscuit fits, because a central issuer keeps the private root key and every service verifies with the public key.
  • Agents acting across organisations or devices: UCAN fits, because principals are DIDs and each hop is signed. Pair it with the Verifiable Credentials Guide if the agent also needs to prove attributes.
  • Already on an OAuth platform: keep OAuth at the edge and use capability tokens or transaction tokens inside, rather than replacing the authorisation server.

Capability tokens for AI agents

An agent orchestrator that hands every sub-agent and tool the same broad token gives a prompt-injected sub-agent the orchestrator's full authority. Capability tokens let the orchestrator mint a child token per task: one command, one resource, a few minutes, and, for Biscuit, sealed so it cannot be passed on. The Delegation Chains and Attenuated Authority for AI Agents guide covers the wider design, including OAuth token exchange and transaction tokens; the points below are specific to capability formats.

  • Mint at the tool boundary, not in the prompt: attenuation should be done by deterministic code in the orchestrator or a token broker. Never let the model write the caveats or Datalog.
  • Bind to the task: include a task or transaction identifier as a caveat, check or policy argument, so logs connect every tool call to the user request that caused it.
  • Destructive actions need their own grant: keep delete, transfer and production write commands out of default agent tokens. The PocketOS database deletion happened because an agent found an account-scoped API token created for an unrelated purpose and used it to delete production data and backups; a token limited to one environment and one command would have failed closed.
  • Keep root keys away from agents: the root secret (macaroons) or root private key (Biscuit) belongs in a key management service or HSM with the issuer, never in the agent runtime. See the Secrets Management Guide.

How to implement

  1. Pick one flow. Start with a single delegation path, for example orchestrator to read-only reporting tool, where a narrow token clearly reduces risk.
  2. Define the root grant narrowly. Even the root token should name a service, an operation set and an expiry. Avoid wildcard commands, Powerline delegations and authority blocks that grant everything.
  3. Protect the root key. Generate and hold the root secret or private key in a KMS or HSM, rotate it on a schedule, and document how verifiers learn the new public key or DID.
  4. Build the verifier first, in audit mode. Run the new token check alongside the existing authorisation decision, log both results, and compare them for two to four weeks before enforcing.
  5. Add attenuation in the delegating component. Library calls such as adding a caveat, appending a Biscuit block or issuing a UCAN delegation should be wrapped in one internal function that enforces expiry limits and a maximum chain depth.
  6. Add replay and revocation checks. For UCAN, keep the store of unexpired invocation CIDs the specification requires. For Biscuit, check revocation identifiers against a deny list. For macaroons, include a version or generation caveat that you can bump to invalidate a class of tokens.
  7. Enforce, then expand. Switch the pilot flow to enforce, keep the old path as a feature-flagged fallback for rollback, then extend to more tools and agents.

Detection and measurement

Log every verification decision with the token or block identifiers, chain depth, caveats or checks evaluated, the subject or audience, the requested operation and the result. Never log the full token: Biscuit and macaroons are bearer credentials, and Biscuit tokens contain the private key needed for the next attenuation. See the JWT and Session Tokens in Code and Logs Guide for redaction patterns.

SignalWhy it matters
Verification failures by reason (expired, caveat unmet, unknown caveat, bad signature)Bad signatures suggest tampering or key mismatch; unmet caveats can show an agent trying to exceed its grant
Replayed invocation CIDs or reused token identifiersDirect evidence of token theft or a retry bug
Hits against revocation listsShows revoked tokens still circulating
Tokens presented from unexpected workloads or networksBearer tokens used outside their intended path, mapped to ATT&CK T1550.001 (Application Access Token) after theft via T1528 (Steal Application Access Token)

Useful metrics:

  • Median and 95th percentile token lifetime for delegated (non-root) tokens, against your target, for example under 15 minutes.
  • Percentage of agent tool calls made with an attenuated child token rather than the parent token.
  • Number of root grants using wildcard commands, Powerline or unrestricted authority blocks (target: zero outside documented exceptions).
  • Median time from a revocation decision to the revocation reaching every verifier.
  • Days since last root key rotation, per issuer.

Common failure patterns

  • Broad root, narrow intentions: the authority block or root macaroon grants everything and teams rely on every holder to attenuate. One holder that forgets passes on full power. Make the root narrow.
  • Treating attenuation as revocation: adding a caveat to your own copy does nothing to copies already handed out. Revocation needs identifiers, a list and verifiers that check it.
  • Root key in the wrong place: a macaroon root secret shared with every service, or a Biscuit private key in an application config file, lets anyone with that file mint unlimited tokens. The Storm-0558 key breach shows what a stolen signing key does to any token system.
  • Unknown caveats accepted: a custom verifier that ignores caveats it does not understand turns attenuation into decoration. Unknown restrictions must fail closed.
  • No expiry on delegated tokens: UCAN allows exp: null and macaroons have no built-in expiry. Long-lived delegated tokens behave like leaked API keys.
  • Logging tokens in full: bearer capability tokens in logs or traces are as reusable as passwords.

Framework mapping

FrameworkReferenceHow capability tokens help
NIST SP 800-53 Rev. 5AC-6 Least Privilege; AC-3 Access EnforcementPer-task attenuated tokens enforce least privilege at each hop
NIST SP 800-53 Rev. 5IA-5 Authenticator Management; IA-9 Service Identification and AuthenticationRoot key protection, rotation and service-to-service verification
NIST SP 800-53 Rev. 5SC-23 Session Authenticity; AU-2 Event LoggingSigned invocations and replay checks; logged verification decisions
NIST CSF 2.0PR.AA-01; PR.AA-05Credentials for services managed; permissions enforced with least privilege
MITRE ATT&CK v20T1528 Steal Application Access Token; T1550.001 Application Access TokenShort expiry, narrow scope and holder binding limit what a stolen token can do

Practitioner checklist

  • Identify delegation paths where a service or agent passes its own token to another component today.
  • Choose one format per use case and record why (verifier model, policy needs, DID support).
  • Make root grants narrow and time-bound; ban wildcard commands and Powerline in production policy.
  • Keep root secrets and private keys in a KMS or HSM with documented rotation.
  • Wrap all attenuation in one internal library that enforces maximum lifetime and chain depth.
  • Seal Biscuit tokens, or omit further delegation rights, at the last intended hop.
  • Implement replay detection and a revocation list that every verifier checks.
  • Run verifiers in audit mode before enforcing, with a feature-flagged rollback path.
  • Redact tokens from logs and traces; log identifiers and decisions only.
  • Review the token issuer and verifier configuration in every agent platform security review.

Standards and references

Related NHI Mgmt Group resources: Capability-Based Security Guide · Delegation Chains and Attenuated Authority for AI Agents · OAuth Transaction Tokens (Txn-Tokens) Guide · DPoP Guide · Agent Identity and Access Guide

PDF for subscribers

Take this guide with you

Every section, table and checklist in one PDF, with links to the sources and related guides. Subscribe to our weekly NHI & AI Identity Journal and we’ll email you a download link.

Free weekly newsletter

Subscribe to the NHI & AI Identity Journal

The latest on NHI and Agentic AI security – articles, research, breaches, news and events every week.

Bonus 33% off our NHI Course when you subscribe.

NHIMG Editorial Note
Researched and written by the NHI Mgmt Group editorial team using AI tools, under the editorial direction of Lalit Choda. Facts are drawn from the sources listed on this page and checked by our automated quality process. Last updated 11 November 2026. Spotted an error? Use our contact page.
NHI Mgmt Group, the independent authority on Non-Human Identity, IAM and Agentic AI security. nhimg.org

PDF Downloads for Newsletter Subscribers

Get the guide

Enter your details and we’ll email you a download link.

The full guide is free to read online. The PDF is a thank you for subscribing.

Fill in all fields marked * and tick the PDF box to continue.