Engineering · 2026-11-19
Rate Limiting by Identity: Keys, Limits and Headers
By J. W. Bouckaert
An address is a crowd
RFC 6269, on the issues raised by IP address sharing, describes the per-address limiter in one paragraph. A server that "sees too many requests from the same IPv4 address in a short period of time" may "put that address in a penalty box for a certain time during which requests are denied". Behind carrier-grade NAT the same address is shared by many subscribers, and two things go wrong. Many logins from one address become normal traffic. And "one user who fails a number of login attempts may block out other users who have not made any previous attempts but who will now fail on their first attempt." The RFC's conclusion: "In the presence of widespread large-scale address sharing, penalty box solutions to service abuse simply will not work."
A limiter keyed only on address punishes every customer behind the same shared address for one customer's retries, and it does little against an attacker who rotates addresses.
Choices HTTP leaves open
RFC 6585 defines 429 Too Many Requests and is explicit that the counting is the server's choice: the specification "does not define how the origin server identifies the user, nor how it counts requests." A server "might identify the user by its authentication credentials, or a stateful cookie." The response "MAY include a Retry-After header", which RFC 9110 defines as either an HTTP date or "a number of seconds to delay", and "Responses with the 429 status code MUST NOT be stored by a cache."
So the standards give you a status code and a back-off hint. The key you count on is a design decision.
Choosing the key
| Key | Fair across shared addresses | Contains abuse from one tenant | Contains address rotation | Works before authentication |
|---|---|---|---|---|
| Source address | No | No | No | Yes |
| Credential (API key or tenant) | Yes | Yes | Yes | No |
| Credential plus address | Yes, per pair | Yes | Partly | No |
| Subject identifier (account, phone, email) | Yes | Yes | Yes | Only where the request names a subject |
Three rules come out of that table.
- Authenticated endpoints count on the credential. The tenant is the party with a contract and a quota, so its limit is the one that should bind.
- Unauthenticated endpoints count on the subject the request names. A password reset or recovery confirmation names an account or an address. Limiting attempts per subject stops one target being hammered from many sources, and a per-address limit beside it slows one source working through many targets.
- The stored key must not be personal data. A limiter table keyed on raw addresses, phone numbers or emails is a store of personal identifiers. Key it with a keyed hash.
Failure behavior
A distributed limiter depends on a shared counter, and the counter can fail. There are two answers, and each fits a different endpoint.
- Fail open with a mark. For an authentication path, a counter outage should not become a customer-facing outage. Serve the request on a local counter, log it, and mark any denial made that way, so nobody reads the verdict as distributed.
- Fail closed. For an abuse ceiling, such as a free allotment, a counter outage that lifts the ceiling is the abuse. Refuse.
PasskeyBridge request limits
The signal ingest endpoint counts per tenant and source address pair. The key is the tenant id plus a keyed digest of the address, HMAC-SHA-256 under a server-held pepper, so the counter table holds no address. A request whose source address cannot be determined gets its own one-off bucket, so unknown traffic cannot pool into a shared counter that one caller could exhaust for everyone.
The limit itself belongs to the tenant. An explicit per-tenant setting wins; otherwise the plan default applies, per minute:
| Plan | Requests per minute |
|---|---|
| Starter | 60 |
| Pro | 300 |
| Enterprise | 600 |
| Enterprise dedicated | 1,200 |
Counting runs in two layers. A local fixed window answers first; it is a best-effort damper for bursts that land on one process, and before authentication it holds each source address to 1,200 a minute, the highest plan limit. A database-backed atomic counter then enforces the tenant's limit across instances and is the layer that holds. A denial returns 429 with Retry-After: 60, X-RateLimit-Limit set to the limit actually enforced, and X-RateLimit-Remaining: 0.
When the shared counter does not answer, the two failure modes above are both in use. Ingest serves the request on the local counter and logs the failure at error level, and a 429 decided that way carries X-RateLimit-Degraded: true, so the client can see the denial was local. The 30-day ceiling on free sandbox traffic fails closed: if the counter does not answer, the request is refused.
Unauthenticated paths key on the subject. Account recovery confirmation is limited to 10 attempts per hour per source address digest and 5 per hour per keyed digest of the email address, and either limit refuses the attempt.
The rate limits and quotas guide lists the limits per endpoint and the headers to read. For what an identity pipeline should do when it is the one being flooded, see backpressure in identity pipelines.
A checklist
- Authenticated endpoints count on the credential; the address is at most a second key.
- Recovery and reset endpoints count on the subject, with an address limit beside it.
- Every stored key is a keyed digest.
- Each limiter has a written failure mode, open or closed, chosen per endpoint.
- A denial made without the shared counter is marked for the client.
Retry-Afteris set, and 429 responses are never cached.
Frequently Asked Questions
Why is rate limiting by IP address unfair?
RFC 6269 explains that when an address is shared by many subscribers, one user's failed logins can lock out others on their first attempt, and that penalty-box solutions do not work in the presence of large-scale address sharing.
What should a 429 response include?
RFC 6585 says the response should explain the condition and may include Retry-After, which RFC 9110 defines as an HTTP date or a number of seconds. A 429 response must not be stored by a cache.
What are PasskeyBridge's default rate limits?
Per minute by plan: Starter 60, Pro 300, Enterprise 600, Enterprise dedicated 1,200, unless a tenant has an explicit limit. Ingest counts per tenant and keyed source address digest.
What happens when PasskeyBridge's shared rate-limit counter is unavailable?
Ingest serves the request on a local counter and logs the failure, and a 429 decided that way carries X-RateLimit-Degraded: true. The 30-day ceiling on free sandbox traffic fails closed and refuses the request.