api-key/rate-limit

7 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 limiting applies to API key validation

Rate limiting is applied whenever an API key is validated, including when verifying via /api-key/verify endpoint and when using API keys for session creation (if enableSessionForAPIKeys is enabled). Each API key has its own rate limit settings. When rate limiting is disabled globally or per-key, requests are still allowed but lastRequest is updated for tracking purposes.

Rate limit sliding window mechanism

API key rate limiting uses a sliding window approach: on first request, requestCount is set to 1; for subsequent requests within timeWindow, requestCount is incremented; if requestCount reaches rateLimitMax, the request is rejected with RATE_LIMITED error code and includes a tryAgainIn value in milliseconds; if time since last request exceeds timeWindow, the window resets with requestCount reset to 1 and lastRequest updated.

Customizing rate limit options per API key

When creating an API key with auth.api.createApiKey(), you can customize rate limit options in the body: rateLimitEnabled (boolean), rateLimitTimeWindow (milliseconds), and rateLimitMax (requests per window). These options can only be customized on the server auth instance. If rateLimitTimeWindow or rateLimitMax is null, rate limiting is disabled for that key.

Remaining count and refill mechanism for API keys

The remaining count is the number of requests left before the API key is disabled. If remaining is null, there is no cap to key usage. Otherwise, remaining is decremented by 1 on each use. If remaining reaches 0, the API key is disabled and removed. The refillInterval and refillAmount are set to null by default (no automatic refill). When both are set, the remaining count is reset to refillAmount (not incremented) whenever the API key is used and the interval since last refill exceeds refillInterval.

API key expiration configuration

When an API key is created, expiresAt is set to null by default, meaning the API key will never expire. If expiresIn is set during creation, the API key will expire after that time period.

Rate limit counter increment with enableSessionForAPIKeys

When enableSessionForAPIKeys is enabled, the API key is validated once per request and rate limiting is applied accordingly. If you manually verify an API key and then fetch a session separately, both operations will increment the rate limit counter (double increment). Using enableSessionForAPIKeys avoids this double increment problem.

API Key plugin rateLimit option

The rateLimit option customizes rate-limiting with nested options: enabled (boolean, default true) enables or disables rate limiting; timeWindow (number) specifies the duration in milliseconds where each request is counted, and once maxRequests is reached the request will be rejected until the timeWindow has passed; maxRequests (number) specifies the maximum amount of requests allowed within a window, and once reached the request will be rejected until the timeWindow has passed.

Give your agent this brain