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:

1. 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.

1. 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.

1. 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.

1. 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.

1. 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.

1. 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.

1. 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.

1. 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

• What Is Autopoiesis
• What Is Capability-Based Security
• What Is a Confused Deputy
• What Is Context as Cursor
• What Is a Convergence Catalogue
• What Is a Falsification Surface
• What Is HATEOAS
• What Is the History of Link Protocols

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