Auth Endpoints — Public Contract¶
Per-endpoint contract for the authentication surface — what each route does at the API edge, what rate-limit bucket it consumes, and what a 429 response looks like to a client. This is the public-facing contract. For the implementation (middleware, Redis keys, IP blocker, suspicious-activity heuristics), see Security → Rate Limiting. For the full per-route reference (request bodies, response shapes, error codes), see Swagger / OpenAPI. For the service-level breakdown (what each route delegates to), see Backend → Auth service.
Rate-limit buckets per endpoint¶
Each limit is per client IP unless marked per address, and applies to the listed route. Counters use a fixed window backed by Redis. The Cloudflare edge also rate-limits the credential endpoints per IP before requests reach the API.
| Endpoint | Limit | Window | Bucket |
|---|---|---|---|
POST /api/v1/auth/register |
5 | 1 hour | RegisterLimit() |
POST /api/v1/auth/login |
10 | 15 minutes | LoginLimit() |
POST /api/v1/auth/google-login |
10 | 15 minutes | LoginLimit() |
POST /api/v1/auth/apple-login |
10 | 15 minutes | LoginLimit() |
POST /api/v1/auth/webauthn/login/begin |
10 | 15 minutes | LoginLimit() |
POST /api/v1/auth/webauthn/login/finish |
10 | 15 minutes | LoginLimit() |
POST /api/v1/auth/otp/send |
10 | 15 minutes | OTPLimit() (shared with verify) |
POST /api/v1/auth/otp/send (per address) |
5 | 1 hour | OTPSendAccountLimit() |
POST /api/v1/auth/otp/verify |
10 | 15 minutes | OTPLimit() |
POST /api/v1/auth/reset-password |
5 | 1 hour | ResetPasswordLimit() |
Every route under /api/v1/* (baseline) |
600 | 1 minute | APILimit() |
Bucket presets are defined in backend/internal/middleware/rate_limiter.go.
How the buckets stack
APILimit() is wired on the /api/v1 group, so every API request counts against the 600/min/IP baseline. Targeted limits (register, login, reset-password) are layered on top of the baseline for those specific endpoints — a registration attempt counts against both the 5/hour register bucket and the 600/min baseline. Routes under /ws (WebSocket) and webhook endpoints are not in the baseline.
Counters are per-IP, not per-user
Multiple users behind a single NAT share a counter. A shared office network can exhaust the bucket for everyone if one person bursts on the login endpoint. The trade-off is intentional: rate limiting runs before authentication, so it has no user identity to key on.
Response when limited¶
HTTP/1.1 429 Too Many Requests
Retry-After: 900
Content-Type: application/json
{
"error": {
"code": "RATE_LIMITED",
"message": "too many login attempts, please try again later"
}
}
The message varies per bucket; the code is always RATE_LIMITED. A 429 from the Cloudflare edge has no JSON body, so clients treat any 429 as rate-limited whatever the body.
Retry-After¶
Retry-After: <seconds> is set to the window duration for the bucket that fired:
| Bucket | Retry-After |
|---|---|
APILimit() |
60 |
LoginLimit() |
900 |
OTPLimit() |
900 |
RegisterLimit() |
3600 |
OTPSendAccountLimit() |
3600 |
ResetPasswordLimit() |
3600 |
Clients should:
- Honour the header — wait at least that many seconds before retrying.
- Surface a generic "try again later" message to the user; showing the countdown is fine.
- Not retry the same request automatically. These limits exist to defeat scripted attacks, and silent retries defeat the purpose.
Sending a one-time code¶
POST /auth/otp/send and POST /auth/email/change answer with:
| Status | Code | When |
|---|---|---|
200 |
Code sent. password_reset also answers 200 for an address with no account, so reset never reveals one. |
|
400 |
VALIDATION_FAILED |
The email is not a valid address. |
409 |
email_already_exists |
Signup or email change to an address that already has an account, including suspended accounts and ones pending deletion. |
429 |
RATE_LIMITED |
Per-IP or per-address send limit (see above). |
503 |
OTP_SEND_FAILED |
The code was issued but the email provider rejected it. Retryable; the provider error is logged, not returned. |
Signup reveals that an address is taken because creating the account would refuse it anyway; the per-IP and per-address limits above bound how fast anyone can probe. Password login does not reveal it (an unknown email gets the same 401 as a wrong password).
Rejected requests (400) and blocks (403)¶
A 429 does not escalate to a block. Separately, a request that looks like an attack probe (SQL-injection strings, path traversal, an oversized query) gets 400 with code REQUEST_REJECTED. Five of those from one client IP within 10 minutes block it for 15 minutes, escalating to 1 hour and then 24 hours for repeat offenders; a blocked client gets 403 with code CLIENT_BLOCKED and Retry-After. See Security → IP Blocker for the patterns; blocks lift on their own when they expire.
Failure mode¶
If Redis is unavailable, the credential buckets (register, login, OTP, reset-password) fail closed with 503 and Retry-After, so an outage is not a brute-force window. The APILimit() baseline and the IP blocker fail open, so the rest of the API stays up.
Authenticated routes¶
Routes behind JWTAuth aren't rate-limited per-route today. The defense layers are:
- The unauthenticated auth endpoints' rate limits keep brute-force off the doorstep.
- The global IP blocker rejects attack-shaped requests and blocks repeat offenders regardless of route.
- Authenticated callers carry a
user_id— abuse on those routes is investigated and dealt with via admin action rather than per-IP throttling.
If a future authenticated endpoint needs per-user throttling, key the bucket on user_id from the JWT context rather than IP — wrappers for this live next to LoginLimit() in rate_limiter.go.