The URL is the password: how capability URLs work

What a capability URL actually is

A capability URL — sometimes called a bearer URL — is a link that carries its own authority. Instead of "prove who you are, then we'll check what you're allowed to do," the model is "if you hold this URL, you may do the one thing it grants." The secret is the URL. There's no username, no separate token, no session.

You use these constantly, probably without naming them:

• A password-reset link in your inbox — anyone with that link can set your password, which is exactly why it expires fast.
• A "share via link" document that says anyone with the link can view.
• A pre-signed S3 URL that grants temporary read access to one object.
• A webhook endpoint a third party POSTs to.

Lert's notification endpoint, https://lert.dev/p/your-id, is one of these. The your-id segment is a long, random, unguessable string. Holding it authorizes exactly one action: send a notification to the phone that generated it. Nothing else.

The entropy half

For "unguessable" to mean anything, the identifier has to be long and random enough that brute-forcing it is hopeless. A short or sequential ID (/p/1, /p/2) would be trivially enumerable — a fatal flaw. A properly generated token with 128+ bits of entropy is not something anyone iterates through; the search space dwarfs the number of requests any attacker could make before you'd notice and rotate. This part is the service's job, and it's a solved problem: generate enough random bytes, encode them URL-safe, done.

The secrecy half — where the real risks live

Because the URL is the credential, every place a URL can leak is a place your credential can leak. This is the honest downside, and it's worth knowing the vectors cold:

1. Logs

Web servers, reverse proxies, and API gateways love to log full request lines: POST /p/your-id. That's your secret sitting in a log file, possibly shipped to a third-party log aggregator, possibly retained for a year. The mitigation on the sending side: put the secret in the path or a header, and be aware of what your own infrastructure logs.

2. The Referer header

If a capability URL ever appears in a browser's address bar and that page links to a third party, the browser can send the full URL in the Referer header. This is a classic way share links leak. It's largely a concern for URLs you visit; a notification endpoint you only POST to from scripts is far less exposed — but don't paste it into a browser tab out of habit.

3. Client-side code and public repos

This is the big one for developers. If you hard-code the URL into front-end JavaScript, it ships to every visitor's browser — view-source and it's theirs. If you commit it to a public GitHub repo, crawlers will find it within minutes. Treat the URL exactly like an API key: environment variables, secrets managers, server-side only.

The failure mode of a capability URL is never "someone cracked the crypto." It's always "someone left it somewhere public." Human, not mathematical.

4. History, bookmarks, analytics

Browser history, synced bookmarks, and URL-capturing analytics tools can all quietly retain the secret. Again, mostly relevant if you treat the endpoint like a page instead of a secret.

# Right: read from the environment, server-side
curl -X POST "$LERT_URL" -d '{"title":"Job done"}'

# Wrong: hard-coded in a public repo or shipped to the browser
fetch("https://lert.dev/p/your-id", { method: "POST" })

Why it's genuinely fine for self-notifications

Here's the part the "isn't that insecure?" reflex misses: security is about the stakes of the granted action, not the shape of the credential. Ask what an attacker gains by stealing the URL. With Lert, the answer is: they can send you a notification. That's it. They can't read your data — there is none to read. They can't spend money, change your account, or pivot to anything else. The worst case is that a jerk buzzes your phone until you rotate the URL.

Compare that to a leaked AWS key or a Stripe secret, where the blast radius is your infrastructure or your bank account. The reason a heavyweight credential system exists is to contain heavyweight consequences. A self-notification has featherweight consequences, so a featherweight credential is a proportionate, sensible design — not a corner cut. Matching the credential to the stakes is good engineering.

Mitigation: rotation is a complete fix

Because the downside is bounded, the remedy is simple. If a notification URL leaks — you accidentally committed it, or the spam started — you regenerate it. A good single-endpoint service makes this one tap: a new random ID is minted and the old URL instantly stops working. There's no cascade to clean up, no data to consider compromised. Rotation isn't a patch over a weak design; for this threat model it's a total remedy.

Practical hygiene, in order of importance:

• Store the URL like any secret — env var or secrets manager, never in client code or a public repo.
• Don't paste it into a browser address bar or share it in a screenshot.
• Be aware of what your logging stack captures.
• Rotate the moment you suspect it leaked. It's free and instant.

When you'd want something stronger

Capability URLs are the wrong tool the instant the granted action carries real authority. Reach for a proper key-and-scope system when:

• The endpoint can read or write sensitive data, not just fire a fixed-shape notification.
• You need per-client revocation — cut off one integration without breaking the others.
• You need scopes — this key can do X but not Y.
• You need an audit trail tying each call to an identity.
• Anything financial, legal, or irreversible is downstream.

That's why Lert deliberately keeps the endpoint's power tiny. The capability model is safe because the capability is narrow. Widen what the URL can do and you'd have to widen the security around it too — at which point it stops being a one-request tool.

The takeaway

A capability URL isn't a security shortcut; it's a security decision that fits a specific shape of problem — a single, low-stakes, unguessable grant that you can throw away and remint at will. For "buzz my own phone," it's not just acceptable, it's the right call. Understand the leak vectors, treat the URL like the secret it is, and keep the rotate button in your back pocket. If you want the practical framing of why this makes notifications so frictionless, see the simplest way to send yourself a push.