Capability Token Service

Inspiration

In my daily work building enterprise software and hunting for security vulnerabilities like parameter tampering and BOLA/IDOR, I constantly see the pitfalls of traditional stateful authorization. I wanted to build an authentication mechanism that is inherently tamper-proof and scalable.

I was inspired by Macaroons — capabilities that allow for decentralized delegation. The goal was to create a system where an AI agent could securely delegate a restricted subset of its own permissions to another agent without ever needing to contact the central issuing authority.

What it does

Capability Token Service is a lightweight HTTP API for issuing, delegating, verifying, and revoking macaroon-style capability tokens.

• Self-verifying: Each token carries its full root-to-leaf delegation chain, meaning the server needs zero database lookups to verify a token.
• Strict Scope-Narrowing: A parent can mint a child token, but only with a strict subset of its own scopes.
• Cascading Revocation: If a root or parent token is revoked, the system automatically invalidates the entire downstream delegation subtree.

How we built it

The core service is built with Python and FastAPI, utilizing Pydantic for strict request validation.

At the cryptographic level, it uses standard hmac and sha256 hashing to create a running chain of signatures. Each link's HMAC is keyed by the previous link's signature, securely binding the payload. The token is then base64url encoded for easy HTTP transport.

The application is containerized using a Dockerfile and deployed directly to Fly.io.

Challenges we ran into

One of the primary challenges was designing the cascading revocation system without relying on a bulky database. Because tokens are entirely stateless, I had to implement an efficient in-memory revocation set that tracks revoked signatures.

Another challenge was ensuring the SKILL.md documentation was written precisely enough for a blind AI agent to successfully chain the /issue, /delegate, and /verify endpoints without human intervention.

Accomplishments that we're proud of

I am incredibly proud of how robust the token verification logic is. It strictly prevents scope escalation and TTL (Time-To-Live) extensions during delegation.

Furthermore, seeing an AI agent autonomously read the dynamically served /skill.md endpoint and successfully execute the complex delegation flow over HTTP was a massive win.

What we learned

I deepened my understanding of decentralized authorization architectures and HMAC cryptographic chains.

Additionally, optimizing an API to be consumed purely by an LLM-driven agent required a paradigm shift in how I write documentation — prioritizing hyper-concrete curl examples and machine-stable error reasons over traditional human-readable fluff.

What's next for Capability Token Service

The next logical step is moving the in-memory revocation set to a fast, persistent key-value store like Redis to maintain state across instance restarts.

I also plan to introduce wildcard matching and regex support for scopes to allow for more complex and granular capability delegation.

Built With

• api
• authentication
• authorization
• docker
• fastapi
• fly.io
• hmac
• pydantic
• python
• security
• sha256