What is a capability URL?

How it works

A capability URL contains a random token with enough entropy that enumeration is computationally infeasible (typically 128 bits or more). The server stores only a hash of the token; presenting the URL is presenting the credential. There is no account to authenticate against, which removes signup, key issuance, and session management from the protocol entirely.

The pattern is old and well-studied: it is how Google Docs "anyone with the link" sharing, password-reset links, unsubscribe links, and private RSS feeds work. The W3C documented the trade-offs in its "Good Practices for Capability URLs" note.

Security model and trade-offs

The strength and the weakness are the same fact: possession equals permission. That makes capability URLs exactly as secure as the channels they travel through.

• Strengths: no credential database to breach, no phishing surface (nothing to type), trivially delegable (send the link), and revocable by destroying or rotating the resource.
• Risks: URLs leak through browser history, server logs, Referer headers, screenshots, and pasted chat messages. A leaked capability is a leaked resource.
• Mitigations used in practice: HTTPS only, high entropy, hashing server-side, no-referrer policies, keeping the URL server-side in deployed apps, expiry windows, and a hard-delete kill switch for revocation.

Why AI agents changed the calculus

Capability URLs fit machine clients unusually well. An AI agent cannot complete a signup form, store a password manager entry, or wait for a human to paste an API key, but it can hold a URL, persist it to a file or its memory, and reuse it across sessions. That is why agent-facing services increasingly use capability URLs as the entire credential model: the integration cost drops to a single HTTP call.

TmpState is a worked example: creating a database returns a URL like https://tmpstate.dev/db/s-<30 random characters>, which is the only credential for that database. The server stores a SHA-256 hash of the capability, admin access rides the same URL, and revocation is deleting the database. The trade-offs above apply verbatim: the docs tell agents to keep the URL server-side and treat it like a private link.

curl tmpstate.dev
# {"db": "https://tmpstate.dev/db/s-...", ...}
# The db URL is the credential. Whoever holds it, has it.

When a capability URL is the right choice

• Sharing and delegation are the primary flows (documents, invites, demos).
• The client is a machine or agent that cannot do interactive auth.
• The resource is scoped and disposable, so a leak has a bounded blast radius.
• Not the right choice when: data is high-stakes and long-lived, per-user permissions are needed, or URLs must transit untrusted channels routinely - use real authentication there.