Rate limiting in plugins
Custom rate limit rules are defined via a `rateLimit` array containing objects with: `pathMatcher` (function that receives path and returns boolean), `limit` (maximum request count), and `window` (time window in seconds).
Better Auth · Concepts · all subjects
rate limiting
19 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.
Rate limiter default settings in production
By default, in production mode, the rate limiter is set to a window of 60 seconds and a maximum of 100 requests.
Rate limiter disabled in development mode
Rate limiting is disabled in development mode by default. To enable it in development, set the 'enabled' property to true in the rateLimit configuration.
Server-side requests exempt from rate limiting
Server-side requests made using auth.api are not affected by rate limiting. Rate limits only apply to client-initiated requests.
Rate limit configuration via betterAuth
Rate limiting can be customized by passing a rateLimit object to the betterAuth function with properties: window (time window in seconds) and max (max requests in the window).
Built-in rate limit rules for authentication endpoints
Better Auth provides custom rules for specific paths: /sign-in/email is limited to 3 requests within 10 seconds. Plugins also define custom rules, for example the twoFactor plugin has /two-factor/verify limited to 3 requests within 10 seconds.
IP address header configuration for rate limiting
Rate limiting uses the connecting IP address to track requests. The default header checked is x-forwarded-for. If using a different header, specify it via the advanced.ipAddress.ipAddressHeaders configuration.
Trusted proxies for X-Forwarded-For chain verification
By default, Better Auth does not trust comma-separated forwarded IP chains since the leftmost X-Forwarded-For token is client-controlled behind an appending proxy. Use advanced.ipAddress.trustedProxies to list proxy addresses; Better Auth walks the chain right to left, skips trusted hops, and takes the first untrusted address as the client.
IPv6 address normalization in rate limiting
Better Auth automatically normalizes IPv6 addresses to prevent bypass attacks where different representations of the same IPv6 address are used. For example, 2001:db8::1 and 2001:0db8:0000:0000:0000:0000:0000:0001 are treated as the same address for rate limiting purposes.
IPv4-mapped IPv6 address conversion
IPv4-mapped IPv6 addresses (e.g., ::ffff:192.0.2.1) are automatically converted to their IPv4 form (192.0.2.1) to prevent attackers from bypassing rate limits by switching between IPv4 and IPv6 representations.
IPv6 subnet rate limiting default
By default, IPv6 addresses are rate limited per /64 subnet, not per individual address. ISPs and cloud providers assign IPv6 prefixes typically /64 for residential users per RFC 6177, so per-address rate limiting would allow clients to rotate through many source addresses without exhaustion.
IPv6 subnet prefix length configuration
The ipv6Subnet option can override the default /64 prefix length for IPv6 rate limiting. Common prefix lengths: 128 (individual address, most restrictive), 64 (default, /64 subnet), 56 (residential ISP allocation per RFC 6177), 48 (/48 subnet), 32 (/32 subnet). Any integer from 0 to 128 is accepted.
IPv4 rate limiting always per-address
IPv6 subnet configuration only affects IPv6 addresses. IPv4 addresses are always rate limited individually.
Custom rate limit rules for specific paths
Custom rate limit rules can be set for specific paths using the rateLimit.customRules configuration. Rules can be static objects with window and max properties, or async functions that return window and max values. Wildcard paths like '/two-factor/*' are supported.
Disable rate limiting for specific paths
Rate limiting can be disabled for a specific path by setting it to false in the customRules, or by returning false from a custom rule function.
Rate limit storage options
By default, rate limit data is stored in memory. Alternative storage options include: 'database' (stores in database with optional modelName parameter, defaults to 'rateLimit'), 'secondary-storage' (if configured), or customStorage (custom implementation with get and set async methods).
Database migration for rate limit storage
When using database storage for rate limiting, run 'npx auth@latest migrate' to create the rate limit table. If using Prisma, Drizzle, or another ORM, run 'npx auth@latest generate' first, then apply the schema using the ORM's migration tool.
Rate limit error response header
When a request exceeds the rate limit, Better Auth returns an X-Retry-After response header containing the number of seconds until the user can make another request.
Rate limit error handling on client
Rate limit errors (HTTP 429) can be handled on the client using Better Auth client's fetchOptions with an onError callback that checks response.status and the X-Retry-After header. Error handling can be done globally via createAuthClient or per-request.