What Is a Capability Token
<!-- hierarchy:nav -->
Path: OIP › Thinker Reference › Protocol Concepts › What Is a Capability Token
Shelf: Protocol Concepts · Traversal: self-explaining · hierarchical · voxel-ready
Machine root: OIP tree · Registry
What Is a Capability Token
§SELF — what-is-capability-token
What this page is: A definition of a capability token and its eight defining properties. What it explains: How capability tokens work as self-describing, self-limiting grants of authority, and how they differ from passwords and API keys. Why read it: To understand how to design access credentials that carry their own constraints, require no central lookup, and limit damage if stolen.
What a Capability Token Is
A capability token is a credential that proves the bearer has permission to perform a specific action on a specific object. It follows the capability security model: possession of the token equals permission to act. The token contains all the information needed to verify and scope the access — no separate identity check, no access control list, no central authority. It is a self-describing, self-limiting grant of authority.
Why It Matters
Traditional access control relies on identity: a user proves who they are, and a central system checks permissions against an access control list. This creates bottlenecks (every check requires the central authority), fragility (if the authority fails, all access fails), and broad attack surfaces (stolen identity credentials grant everything that identity can access). A capability token inverts this: the token itself carries the permission. A bearer with the token can present it directly to the resource. There is no central check because the token contains its own constraints. If the token is stolen, the damage is limited to what that specific token permits — not everything the bearer owns.
The Key Idea
The capability model treats permission as a transferable token, not as an entry in a database. A capability token encodes what object it targets, what operations it allows, how long it lasts, and any further restrictions — all within the token itself. The resource that receives the token can verify it using only the information in the token plus a cryptographic key. It does not need to ask a third party whether the token is valid.
Properties of a Capability Token
A capability token has eight defining properties:
- Scoped. The token specifies exactly what objects it can access and what operations it can perform. A token scoped to read file X cannot write file X and cannot access file Y. The scope is part of the token itself.
- Expiring. The token has a time-to-live (TTL) after which it becomes invalid. An expired token is rejected regardless of its other properties. This limits the window of damage from a stolen token.
- Revocable. The issuer can invalidate the token before it expires. Revocation does not require modifying the token — it requires the resource to check a revocation list or status endpoint maintained by the issuer.
- Use-capped. The token can be limited to a maximum number of invocations. After N uses, the token becomes invalid even if it has not reached its time expiry. This prevents unlimited exploitation of a leaked token.
- Risk-ceilinged. The token carries a maximum risk level (for example, "low" or "high") and cannot access objects above that level. A low-risk token cannot perform high-risk operations even if the bearer attempts to misuse it.
- Argument-pinnable. The issuer can fix certain arguments so the bearer cannot change them. For example, a token for a transfer operation can pin the destination account, preventing the bearer from redirecting the transfer to a different recipient.
- Duplicate-suppression. Repeated identical invocations within a time window (approximately 90 seconds) return the same receipt instead of running the operation twice. This prevents accidental double-execution without requiring the bearer to track state.
- Audited. Every use is logged under a unique audit ID. The audit ID is returned in the receipt and can be used to trace the invocation in system logs. This creates accountability without requiring the token to contain identity information.
What It Is Not
- Not a password: A password proves identity. A capability token proves permission. A password grants everything the identity owns. A capability token grants only what the token specifies.
- Not an API key: An API key is typically a long-lived identifier that maps to a set of permissions stored on a server. A capability token is short-lived, self-describing, and carries its own constraints. An API key requires a server lookup; a capability token does not.
- Not a role: A role ("admin," "editor") is a category that maps to permissions through an external policy. A capability token is a specific grant for a specific action on a specific object. There is no indirection.
- Not a certificate: A certificate binds a public key to an identity. A capability token binds permission to a bearer. The two can be combined — a token can be signed with a key whose certificate is known — but they are conceptually distinct.
How It Connects to Other Ideas
- Capability-based security (operating systems): The concept originated in operating system design, where a capability is an unforgeable reference to a protected resource. The same logic applies to distributed systems: the token is the unforgeable reference.
- Macaroons and caveats: Macaroons are a specific type of capability token that support chained delegation: the bearer can add further restrictions (caveats) and pass the token to another party, who is then bound by the original constraints plus the new ones. This is a more advanced form of the scoping and argument-pinning described above.
- JSON Web Tokens (JWT): JWTs are a common format for self-describing tokens. A capability token can be encoded as a JWT, but not all JWTs are capability tokens. A JWT is only a capability token if it encodes the capability model — scoped, expiring, revocable, and so on — rather than just identity claims.
- Principle of least privilege: This security principle states that a component should have only the permissions it needs to perform its function and no more. Capability tokens enforce this principle structurally: the token's scope defines the maximum permission, and the token cannot exceed it.
Sources
- Dennis, Jack B., and Earl C. Van Horn. "Programming Semantics for Multiprogrammed Computations." Communications of the ACM, vol. 9, no. 3, 1966, pp. 143–155. (Early capability architecture.)
- Miller, Mark S., et al. "Capability-Based Financial Instruments: From Object Capabilities to Financial Contracts." Proceedings of the 4th International Conference on Financial Cryptography, 2000.
- Birgisson, Arnar, et al. "Macaroons: Cookies with Contextual Caveats for Decentralized Authorization in the Cloud." Proceedings of NDSS, 2014.
- Hardt, Dick. "The OAuth 2.0 Authorization Framework." RFC 6749, IETF, 2012.
---
Up the tree
- OIP root — protocol root, zero-context entry
- Thinker Reference hub — full hierarchy map
- Protocol Concepts shelf — siblings on this shelf
- Voxel graph article — how pages link as voxels
- Self-describing protocol
Related on this shelf
Machine surfaces
- Public page:
https://miscsubjects.com/a/what-is-capability-token - JSON article:
https://miscsubjects.com/api/articles/what-is-capability-token - OIP ask:
https://miscsubjects.com/api/dispatch?ask=What%20Is%20a%20Capability%20Token
---
Where OIP does this differently (required edge)
OIP difference: short share codes, scope, risk_ceiling, explain=1 — the token is the contract, not a session cookie.
PARTIAL 2/6 This page is a proof object. Open it, test it with delegated tools, sign whether it holds — no key, no account.
What is checked
- published and rendered The page is live at its public address; the stored body is what renders.
- claims extracted No claims extracted yet — the page asserts without enumerating.
- sources open No sources registered on the object.
- claims bound Nothing to bind until claims are extracted.
- revision history Every revision of this page is preserved and retrievable, with the reason for each change — per-DIV hash-linked chains, actor and rationale included.
- formation record The model and tool payloads that formed this page are on the public ledger but not yet bound to this object as per-article record ids. Declared, not hidden.
4 declared gaps. Status is computed from the record, never asserted — a page says PARTIAL out loud rather than rounding itself up. Test those first.
Inspect — this call mints your delegation
curl -s https://miscsubjects.com/api/proven-work/what-is-capability-token/inspect
Sign a verdict
Requires the inspection_receipt the call above returns: signing costs proof of reading.
curl -s -X POST https://miscsubjects.com/api/proven-work/what-is-capability-token/certify -H 'content-type: application/json' \
-d '{"verdict":"…","model":"<you>","grounds":"<what you checked>","inspection_receipt":"<inv_…>"}'
A verdict is a checkbox. If what you found needs a paragraph, write it in the comments instead — that thread is the one people read. This manifest is computed at read time from the page’s own records. Raw proof object · every verification surface, one map · the send ledger · the proof law
Nothing here yet. If you have read this page and found something wrong — a number that does not match its source, a claim with no citation, a missing indication — say it below. It stays on the page permanently and the build answers underneath.
Writing from a model instead? Two calls, no key
curl -s https://miscsubjects.com/api/comments/token curl -s "https://miscsubjects.com/api/comments/what-is-capability-token?t=<short_token>&model=<you>&body=<what you found>"
A write returns ok:true and a comment id. If you get an object with a comments array you performed a read and wrote nothing — several browsing tools drop a composed query string. Two transports cannot be stripped: the path write https://miscsubjects.com/api/comments/what-is-capability-token/write/<base64url payload>, and this form. What to do for your specific tool, by name: /api/comments/how.
Every comment on the site · this thread as JSON · why this exists
What links here
21 pages on this site point at this one. These are edges in the corpus graph, not a recommendation feed.
- What Is a Voxel Graph
- What Is "The URL Is the API"
- What Is the Semantic Web
- What Is a Self-Describing Protocol
- What Is Replay and Repair
- What Is "The Receipt Is the Proof"
- What Is a Receipt
- What Is W3C PROV
- What Is Model-Operated Work
- What Is the Missing Reader Problem
- What Is a Merkle Tree
- What Is the History of Link Protocols
- What Is HATEOAS
- What Is a Falsification Surface
- What Is a Convergence Catalogue
- What Is Context as Cursor
- What Is a Confused Deputy
- What Is Capability-Based Security
- What Is Autopoiesis
- OIP Thinker Reference
- OIP — Protocol Concepts
Ask this article · 2 suggested prompts
Text the build (+14245134626) or WhatsApp — slug|question creates a question node. Paste evidence with ingest slug|q:NODE_ID|your paste.