Skip to content

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:

  1. Honour the header — wait at least that many seconds before retrying.
  2. Surface a generic "try again later" message to the user; showing the countdown is fine.
  3. 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.