Skip to content

CONCEPT Cited by 1 source

Online-stateful token

An online-stateful token requires a database lookup at the token authority on every verification — in contrast to a signed, self-contained token (like a JWT) that a verifier can check with only the issuer's public key.

Macaroons are online-stateful:

"A Macaroon token starts with a random field (a nonce) and the first thing you do when verifying a token is to look that nonce up in a database. So one of the most important details of a Macaroon implementation is where that database lives." (Source: sources/2025-03-27-flyio-operationalizing-macaroons.)

Architectural consequences

  • Revocation works. Deleting / blacklisting the nonce kills the whole token lineage immediately — no waiting for expiration. Contrast JWTs where revocation is famously awkward.
  • The authority has to be reachable (or cached). Every verify implies either a round-trip or a cache hit.
  • The authority's database location matters a lot. Fly.io placed tkdb on isolated hardware, off the primary-API blast radius, precisely because every verify starts there.
  • Caching is load-bearing. With Macaroons specifically, the chained-HMAC construction makes verification caching natural and effective (>98% hit rate at Fly.io).

Contrast: offline / stateless tokens

JWTs (with static public keys) are offline-verifiable: any holder of the issuer's public key can check signatures without contacting the issuer. Trade-off: no revocation without stateful augmentation.

Seen in

Last updated · 200 distilled / 1,178 read