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.
| Property | Typical OAuth access token | Capability token (macaroon, Biscuit, UCAN) |
|---|---|---|
| Who can narrow it | Only the authorisation server, on request | Any holder, locally, without contacting the issuer |
| Where policy lives | Mostly in the resource server, keyed on scopes and claims | Partly in the token (caveats, checks, policies), evaluated with the server's own rules |
| Delegation chain visibility | Lost unless an actor claim or transaction token carries it | Built in: each attenuation is a block, caveat or linked delegation |
| Central dependency at use time | Introspection or JWKS fetch | Root secret (macaroons) or root public key or DID (Biscuit, UCAN) |
| Revocation | Short lifetime, introspection, token revocation endpoint | Short 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 = 3735928559ortime < 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_requeststep 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) orreject 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_idfact 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/reador/msg/send; a shorter command proves a longer one, so/crudcovers/crud/read. The top command/grants everything and the specification says it should be used sparingly. - Policy language: delegations carry a
polfield of predicate statements with jq-style selectors, for example restricting.fromto 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:
nbfis optional andexpis required in the payload, wherenullmeans 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:keyidentifiers, canonical DAG-CBOR encoding and canonical Varsig signatures so a third party cannot create a second valid signature. - Powerline: a delegation with
sub: nullautomatically 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
| Question | Macaroons | Biscuit | UCAN |
|---|---|---|---|
| Cryptography | Chained HMAC (symmetric) | Signature chain, Ed25519 default or ECDSA P-256 | Signed delegations and invocations, Ed25519 preferred, P-256, secp256k1 |
| Who can verify | Only holders of the root secret | Anyone with the root public key | Anyone who can resolve the DIDs in the chain |
| Restriction language | Caveat strings checked by verifier callbacks | Datalog checks in the token, policies in the authoriser | Command hierarchy plus predicate policy on invocation arguments |
| Holder binding | None (bearer) | None (bearer) | Audience DID and signed invocation |
| External attestations | Third-party caveats and discharge macaroons | Third-party blocks | Additional delegations in the proof chain |
| Stopping further delegation | Not built in; use caveats and short expiry | Sealed tokens | Narrow commands and policies; no wildcard / or Powerline |
| Revocation hooks | Service-defined (for example a caveat on a version number) | Per-block revocation identifiers | Revocation sub-specification, revocation invalidates derived tokens |
| Best fit | One service or a few sharing a key store, very low latency | Microservices and APIs that need rich policy and offline verification | Decentralised 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
- Pick one flow. Start with a single delegation path, for example orchestrator to read-only reporting tool, where a narrow token clearly reduces risk.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
| Signal | Why 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 identifiers | Direct evidence of token theft or a retry bug |
| Hits against revocation lists | Shows revoked tokens still circulating |
| Tokens presented from unexpected workloads or networks | Bearer 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: nulland 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
| Framework | Reference | How capability tokens help |
|---|---|---|
| NIST SP 800-53 Rev. 5 | AC-6 Least Privilege; AC-3 Access Enforcement | Per-task attenuated tokens enforce least privilege at each hop |
| NIST SP 800-53 Rev. 5 | IA-5 Authenticator Management; IA-9 Service Identification and Authentication | Root key protection, rotation and service-to-service verification |
| NIST SP 800-53 Rev. 5 | SC-23 Session Authenticity; AU-2 Event Logging | Signed invocations and replay checks; logged verification decisions |
| NIST CSF 2.0 | PR.AA-01; PR.AA-05 | Credentials for services managed; permissions enforced with least privilege |
| MITRE ATT&CK v20 | T1528 Steal Application Access Token; T1550.001 Application Access Token | Short 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
- UCAN Working Group: User Controlled Authorization Network (UCAN) Specification
- UCAN Working Group: UCAN Delegation Specification
- Eclipse Biscuit: Biscuit Specification
- Eclipse Biscuit: Introduction
- Eclipse Foundation: Eclipse Biscuit Project
- Google Research: Macaroons: Cookies with Contextual Caveats for Decentralized Authorization in the Cloud
- libmacaroons: Macaroons Library Documentation
- NIST: SP 800-53 Rev. 5
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