Security

Rate limits

One table of labelled rules for the whole API, rather than a limit written at each route. A limit written at the route is a limit somebody has to remember, and nothing in a handler says "this one needed one and has none".

How a request is matched

Every request produces a list of labels, from the most specific to the least. The first rule that matches one of them wins.

POST /api/v1/orders
→ "POST /api/v1/orders" the route and the method
→ "/api/v1/orders" the route, any method
→ "*:create" the class of action
→ "/api/v1/" a prefix
→ "/api/" a shorter prefix

So one rule can say "every create, twenty in five seconds", and a route nobody thought about is still bounded by the prefix at the end. That last part is the whole argument for a table: the set of routes keeps growing, and the set somebody remembered to limit does not.

Specificity decides, not position in the file. Writing the catch-all first is the obvious mistake and it would silently give every route the loosest limit you have; it does not.

The classes

ClassWhat it covers
*:authAnything under /auth/, plus /login, /register, /password, /totp, /passkeys, /magic-link, /sso/ and an invitation preview. Matched on the path, so a new passkey endpoint is covered the day it is written.
*:createPOST. The expensive one: an id, a row, often a mail or a job.
*:update *:deletePUT/PATCH, and DELETE.
*:list *:readGET without and with a path parameter. A list scans, sorts and counts; a row is one index lookup.

The default table

// internal/ratelimit/rules.go
func Default() Rules {
return Rules{
{Label: "*:auth", MaxRequests: 10, Window: 10 * time.Second},
{Label: "*:create", MaxRequests: 20, Window: 5 * time.Second},
{Label: "*:update", MaxRequests: 30, Window: 5 * time.Second},
{Label: "*:delete", MaxRequests: 20, Window: 5 * time.Second},
{Label: "/api/v1/batch", MaxRequests: 3, Window: time.Second},
{Label: "/api/", MaxRequests: 300, Window: 10 * time.Second, Audience: AudienceGuest},
{Label: "/api/", MaxRequests: 600, Window: 10 * time.Second, Audience: AudienceAuth},
}
}

Edit it. It is ordinary Go in your own repository, which is the point: a limit that lives in a dashboard is a limit nobody reviews, and one that lives in a handler is a limit nobody finds. Development multiplies every number by twenty rather than removing the rules, because a limit nobody exercises in development is a limit that surprises somebody in production.

The credential rule has no audience, deliberatelyThe middleware runs before each route's own authentication, so the only thing it can know about a caller is whether the request carries credentials, not whether they are real. Split *:auth by audience and a credential-stuffing client sends one junk bearer token and buys the signed-in budget. Nothing about a sign-in route needs a relaxation for people who are already signed in.

Turning one off

Set MaxRequests to zero. A rule at zero is off, and the match stops there rather than falling through to a broader rule, which would silently reinstate a limit somebody deliberately removed.

// An inbound webhook you do not control the volume of.
{Label: "POST /api/v1/webhooks/inbound", MaxRequests: 0},

What the caller sees

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 287
HTTP/1.1 429 Too Many Requests
Retry-After: 7
{"error":{"code":"RATE_LIMITED","message":"Too many requests. Try again in 7 seconds."}}

The headers go out whether or not the request was allowed, so a client that can see its budget can slow down before it is stopped. Retry-After is there because a client told only "no" retries immediately, which is the same request again.

Who is counted

The user id when the request has one, so a signed-in caller behind a shared office address gets their own budget rather than the building's. The client address otherwise, which is all a guest has.

This is a floor, not a ceiling

The counters are in process and per instance, so behind three replicas a caller gets three times the budget. That is deliberate: it needs no Redis and it cannot fail open. Sentinel keeps its counters in shared storage and is what bounds the total across replicas. Both are mounted, and where both apply the stricter refuses first.

Validation runs over the table so a typo is found at start-up: *:craete is not a class, a rule with a limit and no window never resets, and two rules with the same label and audience mean the second can never be reached.