Start with authority, not labels
Authorization answers what a request may do. Authentication answers who or what is making it. Many API designs authenticate a client with a key, then ask a server-side policy system whether that client may read a particular record. This is convenient for teams and administration, but it makes identity, policy lookup, and resource naming part of every request.
A capability takes another route. The reference itself is authority for a defined action or object. The idea appears in operating systems, object-capability research, and distributed systems. Miller and colleagues explain the distinction and common misconceptions in Capability Myths Demolished. A capability is not merely a random string with a fashionable name. The security property comes from unforgeability plus a rule that possession grants only the authority attached to that reference.
Both designs can be secure. Both can also fail when secrets leak, scopes are too broad, transport is weak, or revocation is missing. The useful comparison is operational: what the credential names, where permission lives, how delegation works, and how a lost credential is stopped.
| Question | API key model | Capability model |
|---|---|---|
| Primary meaning | Identifies a caller or application. | Authorises access to a scoped resource. |
| Policy | Often looked up centrally. | Attached to or implied by the reference. |
| Delegation | Usually requires another identity or policy. | Can pass a narrower capability. |
| Failure mode | Leaked key may reach many resources. | Leaked cap exposes its granted scope. |
What an API key is good at
API keys are a practical fit for a service that needs account-level quotas, dashboards, billing, usage attribution, and central revocation. A team can issue one key per integration, attach it to a project, and disable it without changing every resource URL. The key can be paired with IP rules, signing, scopes, or a second factor.
The weakness is often accidental scope. A key intended for one script may be accepted across an entire API. If it appears in a source repository, request log, browser bundle, or support ticket, the blast radius depends on the policy attached to the identity. Rotation can also be disruptive when every worker shares one long-lived value.
API keys should be treated as secrets. OWASP’s Secrets Management Cheat Sheet recommends reducing exposure, controlling access, rotating secrets, and monitoring their use. The word capability does not remove these disciplines.
What a capability changes
A capability can encode a narrow right such as read this object, write this name, or use this box. A recipient does not need a user account in the receiving system. The sender can delegate the smallest useful permission, and the recipient can present it in an HTTP Authorization header:
curl https://out.svc.nz/demo-box/input.json/latest \
-H "Authorization: Capability <scoped-capability>"
svc.nz treats every PUT as a new version and exposes a public, human-readable object shape. That makes a capability useful for a file, a handoff, or an agent input without requiring a server-side account relationship between the two parties. The capability is still a bearer secret. Do not paste a live one into a URL, commit it, or place it in an issue.
Capabilities also make delegation easier to reason about. If a system can derive a read-only or name-limited authority, a sender can hand that smaller right to another process. In capability-security literature this is sometimes called attenuation. Revocation remains a design problem, so expiry and rotation matter. A capability that never expires and cannot be replaced is difficult to recover after a leak.
Header transport and scope
HTTP’s Authorization field is the natural transport for either an API key or a capability. MDN’s Authorization reference describes it as credentials for authenticating a user agent with a server. Header transport does not protect a secret from a compromised endpoint, shell history, or an over-permissive proxy, but it avoids putting credentials in the resource identifier itself.
Least privilege is the central practical test. Ask whether a leaked credential can read every object, write every name, alter policy, or only fetch one version. A box capability in svc.nz can be shared for a defined transfer, while a more durable integration should be held by a secret manager or a carefully controlled worker. Use separate write and read permissions when the workflow allows it.
svc.nz is currently a private trial, so its legal and trust pages are part of the decision. The service is a small byte primitive, not an identity provider, SIEM, or full secrets-management platform. It helps when the desired authority is simple and explicit.
It is also useful to separate naming from authority. A public object address can appear in a build record or task message, while the capability remains in protected runtime configuration. That split gives operators a safer way to inspect routing and a clearer way to audit access. It does not make a copied capability harmless, so expiry, rotation, redaction, and narrow scope remain essential.
FAQ
Is a capability token a password?
It is a bearer authority and should be protected like a password. The useful difference is that its intended scope can be narrower than an account credential.
Can capabilities be revoked?
Yes, through expiry, rotation, or an issuer-side deny mechanism. A design must specify the revocation method before capabilities are used for long-lived access.
Are capabilities anonymous?
They can be used without a named account, but possession is still meaningful. Logs, timing, and surrounding context may reveal activity even when no identity is attached.
Should an API key be sent in a URL?
No. Use a header, keep TLS enabled, redact logs, and avoid copying credentials into places that retain URLs.
Sources
Miller et al., Capability Myths Demolished; RFC 9110 Authorization; OWASP Secrets Management; MDN Authorization header.