Skip to content

🐸 Rybbit - open-source and privacy-friendly alternative to Google Analytics that is 10x more intuitive.

feat(api): add organization API usage endpoint and integrate into existing components

Bill Yang0d0437cf1536
diff --git a/client/src/api/admin/endpoints/auth.ts b/client/src/api/admin/endpoints/auth.ts
index 8925a619f..d45604bbf 100644
--- a/client/src/api/admin/endpoints/auth.ts
+++ b/client/src/api/admin/endpoints/auth.ts
@@ -27,6 +27,23 @@ export function getOrganizationMembers(organizationId: string) {
return authedFetch<GetOrganizationMembersResponse>(`/organizations/${organizationId}/members`);
}
+export type GetOrgApiUsageResponse = {
+ /** False on self-hosted, where API requests are not metered. */
+ metered: boolean;
+ /** False when the counter could not be read; the quota is still enforced. */
+ available: boolean;
+ dailyUsed: number;
+ dailyLimit: number;
+ dailyRemaining: number;
+ resetsInSeconds: number;
+ burstLimit: number;
+ burstWindowSeconds: number;
+};
+
+export function getOrgApiUsage(organizationId: string) {
+ return authedFetch<GetOrgApiUsageResponse>(`/organizations/${organizationId}/api-usage`);
+}
+
export function updateMemberSiteAccess(
organizationId: string,
memberId: string,
diff --git a/client/src/api/admin/endpoints/index.ts b/client/src/api/admin/endpoints/index.ts
index 5e52672ce..f515a0b85 100644
--- a/client/src/api/admin/endpoints/index.ts
+++ b/client/src/api/admin/endpoints/index.ts
@@ -107,8 +107,8 @@ export { getSiteImports, createSiteImport, deleteSiteImport } from "./import";
export type { GetSiteImportsResponse, CreateSiteImportResponse } from "./import";
// Auth endpoints
-export { getOrganizationMembers } from "./auth";
-export type { GetOrganizationMembersResponse } from "./auth";
+export { getOrganizationMembers, getOrgApiUsage } from "./auth";
+export type { GetOrganizationMembersResponse, GetOrgApiUsageResponse } from "./auth";
// Teams endpoints
export {
diff --git a/client/src/api/admin/hooks/useOrgApiUsage.ts b/client/src/api/admin/hooks/useOrgApiUsage.ts
new file mode 100644
index 000000000..328f8e5a1
--- /dev/null
+++ b/client/src/api/admin/hooks/useOrgApiUsage.ts
@@ -0,0 +1,21 @@
+import { useQuery } from "@tanstack/react-query";
+import { getOrgApiUsage, GetOrgApiUsageResponse } from "../endpoints";
+
+// Today's API request count against the organization's daily quota. Kept
+// briefly fresh rather than cached indefinitely: the number moves whenever an
+// integration runs, and a stale reading is the one thing that would make the
+// card useless.
+export const useOrgApiUsage = (organizationId?: string) => {
+ return useQuery<GetOrgApiUsageResponse>({
+ queryKey: ["org-api-usage", organizationId],
+ queryFn: () => {
+ if (!organizationId) {
+ throw new Error("Organization ID is required");
+ }
+
+ return getOrgApiUsage(organizationId);
+ },
+ staleTime: 60_000,
+ enabled: !!organizationId,
+ });
+};
diff --git a/client/src/components/subscription/components/UsageCards.tsx b/client/src/components/subscription/components/UsageCards.tsx
index f7e2c514a..925c85e34 100644
--- a/client/src/components/subscription/components/UsageCards.tsx
+++ b/client/src/components/subscription/components/UsageCards.tsx
@@ -1,24 +1,27 @@
import { authClient } from "@/lib/auth";
import { useGetSitesFromOrg } from "@/api/admin/hooks/useSites";
import { useOrganizationMembers } from "@/api/admin/hooks/useOrganizationMembers";
+import { useOrgApiUsage } from "@/api/admin/hooks/useOrgApiUsage";
import { useStripeSubscription } from "../../../lib/subscription/useStripeSubscription";
interface UsageCardItem {
label: string;
current: number;
limit: number | null;
+ /** The count could not be read. Shows a placeholder instead of a false zero. */
+ unavailable?: boolean;
}
-function UsageCard({ label, current, limit }: UsageCardItem) {
+function UsageCard({ label, current, limit, unavailable }: UsageCardItem) {
const percentage =
- limit === null ? 0 : Math.min((current / limit) * 100, 100);
- const isExceeded = limit !== null && current >= limit;
+ limit === null || unavailable ? 0 : Math.min((current / limit) * 100, 100);
+ const isExceeded = !unavailable && limit !== null && current >= limit;
return (
<div className="rounded-lg border p-3 pb-0 overflow-hidden relative">
<div className="text-sm text-muted-foreground">{label}</div>
<div className="text-lg font-semibold mb-3">
- {current.toLocaleString()} /{" "}
+ {unavailable ? "β€”" : current.toLocaleString()} /{" "}
{limit === null ? "Unlimited" : limit.toLocaleString()}
</div>
<div className="relative h-1.5 -mx-3">
@@ -34,6 +37,13 @@ function UsageCard({ label, current, limit }: UsageCardItem) {
);
}
+// Tailwind only emits classes it can see as literals, so the column count maps
+// to a fixed class rather than being interpolated.
+const COLUMN_CLASSES: Record<number, string> = {
+ 3: "lg:grid-cols-3",
+ 4: "lg:grid-cols-4",
+};
+
export function UsageCards() {
const { data: subscription } = useStripeSubscription();
const { data: activeOrg } = authClient.useActiveOrganization();
@@ -41,9 +51,15 @@ export function UsageCards() {
const { data: sitesData } = useGetSitesFromOrg(organizationId);
const { data: membersData } = useOrganizationMembers(organizationId ?? "");
+ const { data: apiUsage } = useOrgApiUsage(organizationId);
if (!subscription) return null;
+ // Mirrors the server's gate in createApiKey: free and basic plans can't hold
+ // API keys, so a quota card would describe a budget they can't spend.
+ const planName = subscription.planName || "free";
+ const hasApiAccess = planName !== "free" && !planName.includes("basic");
+
const items: UsageCardItem[] = [
{
label: "Events used this month",
@@ -62,10 +78,22 @@ export function UsageCards() {
},
];
+ // Organization-owned keys only β€” personal keys are budgeted per user, so
+ // their usage isn't part of this number.
+ if (hasApiAccess && apiUsage?.metered) {
+ items.push({
+ label: "Org API requests today",
+ current: apiUsage.dailyUsed,
+ limit: apiUsage.dailyLimit,
+ unavailable: !apiUsage.available,
+ });
+ }
+
return (
<div
- className="grid gap-4"
- style={{ gridTemplateColumns: `repeat(${items.length}, minmax(0, 1fr))` }}
+ className={`grid grid-cols-1 sm:grid-cols-2 gap-4 ${
+ COLUMN_CLASSES[items.length] ?? "lg:grid-cols-4"
+ }`}
>
{items.map((item) => (
<UsageCard key={item.label} {...item} />
diff --git a/docs/content/docs/api/api-keys/create-org.mdx b/docs/content/docs/api/api-keys/create-org.mdx
index 56cab7a3e..5a8054e89 100644
--- a/docs/content/docs/api/api-keys/create-org.mdx
+++ b/docs/content/docs/api/api-keys/create-org.mdx
@@ -16,7 +16,7 @@ import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
POST /api/organizations/:organizationId/api-keys
```
-Creates an API key **owned by the organization itself**, rather than by your user account. The key authenticates as the organization (org-admin authority over its sites), so it survives member departures, and its plan gating, rate limits, and key-count limit all follow the owning organization's subscription. Organization keys are issued with the `rb_org_` prefix.
+Creates an API key **owned by the organization itself**, rather than by your user account. The key authenticates as the organization (org-admin authority over its sites), so it survives member departures, and its plan gating, [rate limits](/docs/api/getting-started#rate-limits-cloud-only), and key-count limit all follow the owning organization's subscription. Organization keys are issued with the `rb_org_` prefix.
<Callout type="warn">You must be an **owner or admin** of the target organization. This endpoint accepts your dashboard **session** or an **unrestricted (full-access) user API key** β€” scoped keys and organization keys are rejected, so an organization key cannot mint other keys.</Callout>
@@ -105,15 +105,15 @@ Returns the created API key object. The full `key` value carries the `rb_org_` p
type: 'string',
},
rateLimitEnabled: {
- description: 'Whether rate limiting is enabled for the key',
+ description: 'Unused legacy field. Per-key rate limiting is off; limits apply per credential owner (see [Rate Limits](/docs/api/getting-started#rate-limits-cloud-only))',
type: 'boolean',
},
rateLimitMax: {
- description: 'Requests allowed per window',
+ description: 'Unused legacy field. It is ignored β€” see [Rate Limits](/docs/api/getting-started#rate-limits-cloud-only) for the limits that actually apply',
type: 'number',
},
rateLimitTimeWindow: {
- description: 'Window length in milliseconds',
+ description: 'Unused legacy field. It is ignored β€” see [Rate Limits](/docs/api/getting-started#rate-limits-cloud-only) for the limits that actually apply',
type: 'number',
},
}}
@@ -290,9 +290,9 @@ var data = await response.Content.ReadAsStringAsync();
"expiresAt": "2026-07-25T12:00:00.000Z",
"createdAt": "2026-06-25T12:00:00.000Z",
"updatedAt": "2026-06-25T12:00:00.000Z",
- "rateLimitEnabled": true,
- "rateLimitMax": 200,
- "rateLimitTimeWindow": 60000
+ "rateLimitEnabled": false,
+ "rateLimitMax": 10,
+ "rateLimitTimeWindow": 86400000
}
```
diff --git a/docs/content/docs/api/api-keys/create.mdx b/docs/content/docs/api/api-keys/create.mdx
index 4b0517839..0cadbdbe3 100644
--- a/docs/content/docs/api/api-keys/create.mdx
+++ b/docs/content/docs/api/api-keys/create.mdx
@@ -84,15 +84,15 @@ Returns the created API key object.
type: 'string',
},
rateLimitEnabled: {
- description: 'Whether rate limiting is enabled for the key',
+ description: 'Unused legacy field. Per-key rate limiting is off; limits apply per credential owner (see [Rate Limits](/docs/api/getting-started#rate-limits-cloud-only))',
type: 'boolean',
},
rateLimitMax: {
- description: 'Requests allowed per window',
+ description: 'Unused legacy field. It is ignored β€” see [Rate Limits](/docs/api/getting-started#rate-limits-cloud-only) for the limits that actually apply',
type: 'number',
},
rateLimitTimeWindow: {
- description: 'Window length in milliseconds',
+ description: 'Unused legacy field. It is ignored β€” see [Rate Limits](/docs/api/getting-started#rate-limits-cloud-only) for the limits that actually apply',
type: 'number',
},
}}
@@ -268,13 +268,13 @@ var data = await response.Content.ReadAsStringAsync();
"expiresAt": "2026-07-25T12:00:00.000Z",
"createdAt": "2026-06-25T12:00:00.000Z",
"updatedAt": "2026-06-25T12:00:00.000Z",
- "rateLimitEnabled": true,
- "rateLimitMax": 200,
- "rateLimitTimeWindow": 60000
+ "rateLimitEnabled": false,
+ "rateLimitMax": 10,
+ "rateLimitTimeWindow": 86400000
}
```
-<Callout>On Rybbit Cloud, API keys require a Standard or Pro plan; free/basic plans receive HTTP 403. Rate limits are applied automatically based on your plan.</Callout>
+<Callout>On Rybbit Cloud, API keys require a Standard or Pro plan; free/basic plans receive HTTP 403. [Rate limits](/docs/api/getting-started#rate-limits-cloud-only) are charged to **you**, the owning user, and are shared by every personal key you hold across every organization you belong to β€” creating a key does not add budget, and a plan change applies to keys you already have. For a budget that belongs to the organization instead, create an [organization key](/docs/api/api-keys/create-org).</Callout>
</div>
</div>
diff --git a/docs/content/docs/api/api-keys/list.mdx b/docs/content/docs/api/api-keys/list.mdx
index 5fb4c2834..e88e1073a 100644
--- a/docs/content/docs/api/api-keys/list.mdx
+++ b/docs/content/docs/api/api-keys/list.mdx
@@ -116,15 +116,15 @@ Returns all API keys owned by the authenticated user, or by a specific organizat
type: 'string',
},
rateLimitEnabled: {
- description: 'Whether rate limiting is enabled',
+ description: 'Unused legacy field. Per-key rate limiting is off; limits apply per credential owner (see [Rate Limits](/docs/api/getting-started#rate-limits-cloud-only))',
type: 'boolean',
},
rateLimitMax: {
- description: 'Requests allowed per window',
+ description: 'Unused legacy field. It is ignored β€” see [Rate Limits](/docs/api/getting-started#rate-limits-cloud-only) for the limits that actually apply',
type: 'number | null',
},
rateLimitTimeWindow: {
- description: 'Window length in milliseconds',
+ description: 'Unused legacy field. It is ignored β€” see [Rate Limits](/docs/api/getting-started#rate-limits-cloud-only) for the limits that actually apply',
type: 'number | null',
},
requestCount: {
@@ -278,9 +278,9 @@ var data = await response.Content.ReadAsStringAsync();
"expiresAt": "2026-07-25T12:00:00.000Z",
"createdAt": "2026-06-25T12:00:00.000Z",
"updatedAt": "2026-06-25T12:00:00.000Z",
- "rateLimitEnabled": true,
- "rateLimitMax": 200,
- "rateLimitTimeWindow": 60000,
+ "rateLimitEnabled": false,
+ "rateLimitMax": 10,
+ "rateLimitTimeWindow": 86400000,
"requestCount": 42,
"remaining": null,
"lastRequest": "2026-06-25T13:30:00.000Z",
diff --git a/docs/content/docs/api/api-keys/update.mdx b/docs/content/docs/api/api-keys/update.mdx
index b90020950..e0fb07981 100644
--- a/docs/content/docs/api/api-keys/update.mdx
+++ b/docs/content/docs/api/api-keys/update.mdx
@@ -47,7 +47,7 @@ Updates mutable fields on an existing API key. The key is identified by its `key
required: false,
},
rateLimitEnabled: {
- description: 'Enable or disable rate limiting on the key',
+ description: 'Legacy per-key rate limit toggle. Has no effect β€” [rate limits](/docs/api/getting-started#rate-limits-cloud-only) are enforced per credential owner and follow that owner\'s plan',
type: 'boolean',
required: false,
},
@@ -97,15 +97,15 @@ Returns the updated API key object (without the secret key value).
type: 'string',
},
rateLimitEnabled: {
- description: 'Whether rate limiting is enabled',
+ description: 'Unused legacy field. Per-key rate limiting is off; limits apply per credential owner (see [Rate Limits](/docs/api/getting-started#rate-limits-cloud-only))',
type: 'boolean',
},
rateLimitMax: {
- description: 'Requests allowed per window',
+ description: 'Unused legacy field. It is ignored β€” see [Rate Limits](/docs/api/getting-started#rate-limits-cloud-only) for the limits that actually apply',
type: 'number | null',
},
rateLimitTimeWindow: {
- description: 'Window length in milliseconds',
+ description: 'Unused legacy field. It is ignored β€” see [Rate Limits](/docs/api/getting-started#rate-limits-cloud-only) for the limits that actually apply',
type: 'number | null',
},
}}
@@ -284,9 +284,9 @@ var data = await response.Content.ReadAsStringAsync();
"expiresAt": "2026-07-25T12:00:00.000Z",
"createdAt": "2026-06-25T12:00:00.000Z",
"updatedAt": "2026-06-26T12:00:00.000Z",
- "rateLimitEnabled": true,
- "rateLimitMax": 200,
- "rateLimitTimeWindow": 60000
+ "rateLimitEnabled": false,
+ "rateLimitMax": 10,
+ "rateLimitTimeWindow": 86400000
}
```
diff --git a/docs/content/docs/api/getting-started.mdx b/docs/content/docs/api/getting-started.mdx
index 1ace95294..7f9236555 100644
--- a/docs/content/docs/api/getting-started.mdx
+++ b/docs/content/docs/api/getting-started.mdx
@@ -79,15 +79,62 @@ Both kinds support restricting a key to specific permissions when you create it
### Rate Limits (Cloud Only)
-API key rate limits depend on your plan:
+Requests are limited in two ways: a **burst** limit that is the same on every plan, and a **daily quota** that depends on your plan.
-| Plan | Limit |
-|------|-------|
-| **Free / Basic** | API keys not available |
-| **Standard** | 20 requests per minute |
-| **Pro** | 200 requests per minute |
+| Plan | Burst | Daily quota |
+|------|-------|-------------|
+| **Free / Basic** | API keys not available | β€” |
+| **Standard** | 50 requests per 10 seconds | 5,000 requests per day |
+| **Pro** | 50 requests per 10 seconds | 25,000 requests per day |
-Self-hosted instances have no rate limits.
+The burst limit is a bucket of 50 requests that refills continuously at 5 requests per second. You can spend all 50 at once, then keep going at 5 per second β€” so short spikes are fine and there is no window boundary to line up with.
+
+The daily quota resets at **00:00 UTC**.
+
+Requests refused by the burst limit don't count against your daily quota.
+
+#### Which budget a request is charged to
+
+Limits apply per **credential owner**, never per key β€” creating more keys splits an existing budget rather than adding to it:
+
+| Credential | Budget |
+|------------|--------|
+| **Organization key** (`rb_org_`) | The organization's. All of an organization's keys share it. |
+| **Personal key** | Yours. All of your personal keys share one budget, across every organization you belong to. |
+| **OAuth token** (MCP) | Yours, the same budget as your personal keys. |
+
+A personal key's quota follows the most generous plan among the organizations you belong to.
+
+Self-hosted instances are not rate limited at all β€” neither tier applies, and no rate limit headers are sent.
+
+#### Reading your remaining budget
+
+Analytics and management endpoints report your current budget on every response, so you can pace a client without waiting to be rejected:
+
+| Header | Meaning |
+|--------|---------|
+| `X-RateLimit-Burst-Limit` / `-Remaining` | Burst bucket size and tokens left |
+| `X-RateLimit-Burst-Reset` | Seconds until the bucket is full again |
+| `X-RateLimit-Daily-Limit` / `-Remaining` | Daily quota and requests left today |
+| `X-RateLimit-Daily-Reset` | Seconds until 00:00 UTC |
+| `RateLimit-Limit` / `-Remaining` / `-Reset` | Whichever of the two is closest to running out |
+
+Treat these as advisory: a few endpoints resolve credentials outside the standard path and omit them. `Retry-After` on a `429` is always present.
+
+#### When you hit a limit
+
+A `429` names the limit you hit and tells you how long to wait, in seconds:
+
+```json
+{
+ "error": "Rate limit exceeded",
+ "scope": "daily",
+ "limit": 5000,
+ "retryAfter": 34200
+}
+```
+
+`scope` is `burst` or `daily`, and the same value is in the `Retry-After` header. The difference matters: a `burst` rejection clears in about a second, while a `daily` one lasts until the quota resets. Back off accordingly rather than retrying straight away.
---
diff --git a/docs/content/docs/api/live-feed.mdx b/docs/content/docs/api/live-feed.mdx
index 7b0bcf7f8..82f66a636 100644
--- a/docs/content/docs/api/live-feed.mdx
+++ b/docs/content/docs/api/live-feed.mdx
@@ -184,7 +184,7 @@ for (const e of events) {
</Tabs>
<Callout type="warn">
-**Mind the rate limits.** On Rybbit Cloud, API keys are capped per minute by plan (see [Rate Limits](/docs/api/getting-started#rate-limits-cloud-only)). A 10-second poll is 6 requests/minute β€” well within the Standard tier. If you add the live-count call, that's 12/minute. Lengthen the interval or drop the count call if you're close to your limit. Self-hosted instances have no limit.
+**Mind the daily quota.** On Rybbit Cloud, a continuous poll is measured against your plan's daily quota (see [Rate Limits](/docs/api/getting-started#rate-limits-cloud-only)), not just its per-second rate. A 10-second poll running around the clock is 8,640 requests/day β€” over the Standard quota of 5,000, and 17,280 with the live-count call added. Poll every 20-30 seconds, or only while someone is actually watching the page, and check `X-RateLimit-Daily-Remaining` to see where you stand. Self-hosted instances are not rate limited.
</Callout>
## Next steps
diff --git a/docs/src/app/[locale]/(home)/features/api/feature-data.tsx b/docs/src/app/[locale]/(home)/features/api/feature-data.tsx
index 92a772954..584ac0d84 100644
--- a/docs/src/app/[locale]/(home)/features/api/feature-data.tsx
+++ b/docs/src/app/[locale]/(home)/features/api/feature-data.tsx
@@ -144,7 +144,7 @@ export const faqItems: FAQItem[] = [
{
question: "What are the rate limits?",
answer:
- "On Rybbit Cloud, Standard plans get 20 requests per minute and Pro plans get 200. Self-hosted instances have no rate limits. API keys aren't available on the free tier.",
+ "On Rybbit Cloud, every plan can burst 50 requests per 10 seconds, and the daily quota depends on your plan: 5,000 requests a day on Standard, 25,000 on Pro. Limits apply per credential owner β€” an organization key draws on the organization's budget, and all of your personal keys share yours β€” so extra keys don't add budget. Self-hosted instances have no rate limits. API keys aren't available on the free tier.",
},
{
question: "Is the API stable?",
diff --git a/server/src/api/user/createApiKey.ts b/server/src/api/user/createApiKey.ts
index cc66f5a0c..52c09a519 100644
--- a/server/src/api/user/createApiKey.ts
+++ b/server/src/api/user/createApiKey.ts
@@ -5,7 +5,7 @@ import { auth } from "../../lib/auth.js";
import { getSessionFromReq } from "../../lib/auth-utils.js";
import { apiKeyPermissionsSchema } from "../../lib/scopes.js";
import { getSubscriptionInner } from "../stripe/getSubscription.js";
-import { API_RATE_LIMIT_WINDOW, IS_CLOUD, PRO_API_RATE_LIMIT, STANDARD_API_RATE_LIMIT } from "../../lib/const.js";
+import { IS_CLOUD } from "../../lib/const.js";
const createApiKeyBodySchema = z.object({
name: z.string().trim().min(1, "Name is required"),
@@ -16,9 +16,10 @@ const createApiKeyBodySchema = z.object({
});
/**
- * Creates an API key with plan-appropriate rate limits and optional scoped
- * permissions. On cloud: blocks free/basic, sets standard or pro limits.
- * On self-hosted: uses standard limits as default.
+ * Creates an API key with optional scoped permissions. On cloud: blocks
+ * free/basic plans. Rate limits are not stamped onto the key β€” they are
+ * resolved from the owner's current plan on every request (lib/apiRateLimit.ts),
+ * so an upgrade applies to keys that already exist.
*/
export async function createUserApiKey(
request: FastifyRequest<{ Body: { name: string; expiresIn?: number; permissions?: Record<string, string[]> } }>,
@@ -36,9 +37,6 @@ export async function createUserApiKey(
const { name, expiresIn, permissions } = parsed.data;
let planName: string | null = null;
- let rateLimitEnabled = false;
- let rateLimitMax: number | undefined;
- let rateLimitTimeWindow: number | undefined;
if (IS_CLOUD) {
const activeOrgId = (session.session as any).activeOrganizationId;
@@ -54,10 +52,6 @@ export async function createUserApiKey(
error: "API keys require a Standard or Pro plan. Please upgrade to create API keys.",
});
}
-
- rateLimitEnabled = true;
- rateLimitTimeWindow = API_RATE_LIMIT_WINDOW;
- rateLimitMax = planName.includes("pro") || planName === "custom" ? PRO_API_RATE_LIMIT : STANDARD_API_RATE_LIMIT;
}
const keyLimit = apiKeyLimitForPlan(planName);
@@ -68,9 +62,6 @@ export async function createUserApiKey(
body: {
name,
expiresIn: expiresIn ?? undefined,
- rateLimitEnabled,
- rateLimitTimeWindow,
- rateLimitMax,
userId: session.user.id,
...(permissions ? { permissions: permissions as Record<string, string[]> } : {}),
},
diff --git a/server/src/api/user/createOrgApiKey.ts b/server/src/api/user/createOrgApiKey.ts
index 281e33fa0..8b68af824 100644
--- a/server/src/api/user/createOrgApiKey.ts
+++ b/server/src/api/user/createOrgApiKey.ts
@@ -3,7 +3,7 @@ import { z } from "zod";
import { apiKeyLimitForPlan, createApiKeyWithinLimit } from "../../lib/apiKeyLimits.js";
import { auth } from "../../lib/auth.js";
import { ORG_API_KEY_CONFIG_ID } from "../../lib/bearerAuth.js";
-import { API_RATE_LIMIT_WINDOW, IS_CLOUD, PRO_API_RATE_LIMIT, STANDARD_API_RATE_LIMIT } from "../../lib/const.js";
+import { IS_CLOUD } from "../../lib/const.js";
import { apiKeyPermissionsSchema } from "../../lib/scopes.js";
import { getSubscriptionInner } from "../stripe/getSubscription.js";
@@ -49,9 +49,6 @@ export async function createOrgApiKey(
const { name, expiresIn, permissions } = parsed.data;
let planName: string | null = null;
- let rateLimitEnabled = false;
- let rateLimitMax: number | undefined;
- let rateLimitTimeWindow: number | undefined;
if (IS_CLOUD) {
const subscription = await getSubscriptionInner(organizationId);
@@ -62,10 +59,6 @@ export async function createOrgApiKey(
error: "API keys require a Standard or Pro plan. Please upgrade to create API keys.",
});
}
-
- rateLimitEnabled = true;
- rateLimitTimeWindow = API_RATE_LIMIT_WINDOW;
- rateLimitMax = planName.includes("pro") || planName === "custom" ? PRO_API_RATE_LIMIT : STANDARD_API_RATE_LIMIT;
}
const keyLimit = apiKeyLimitForPlan(planName);
@@ -80,9 +73,6 @@ export async function createOrgApiKey(
organizationId,
userId,
metadata: { createdBy: userId },
- rateLimitEnabled,
- rateLimitTimeWindow,
- rateLimitMax,
...(permissions ? { permissions: permissions as Record<string, string[]> } : {}),
},
})
diff --git a/server/src/api/user/getMyOrganizations.ts b/server/src/api/user/getMyOrganizations.ts
index 0d43d2ed9..94ed4fedb 100644
--- a/server/src/api/user/getMyOrganizations.ts
+++ b/server/src/api/user/getMyOrganizations.ts
@@ -2,13 +2,25 @@ import { FastifyRequest, FastifyReply } from "fastify";
import { db } from "../../db/postgres/postgres.js";
import { and, eq } from "drizzle-orm";
import { member, organization, sites, user } from "../../db/postgres/schema.js";
-import { getSessionFromReq, getUserIdFromRequest } from "../../lib/auth-utils.js";
+import { getSessionFromReq, getUserIdFromRequest, wasRateLimited } from "../../lib/auth-utils.js";
import { filterSitesByMemberAccess } from "../../lib/siteAccess.js";
export const getMyOrganizations = async (request: FastifyRequest, reply: FastifyReply) => {
try {
const userId = await getUserIdFromRequest(request);
if (!userId) {
+ // This route has no auth pre-handler, so a throttled credential resolves
+ // to no user. Reporting that as 401 would tell a caller their key is
+ // invalid when it is merely out of budget.
+ const throttled = wasRateLimited(request);
+ if (throttled) {
+ reply.header("Retry-After", throttled.retryAfterSeconds);
+ return reply.status(429).send({
+ error: "Rate limit exceeded",
+ scope: throttled.scope,
+ retryAfter: throttled.retryAfterSeconds,
+ });
+ }
return reply.status(401).send({ error: "Unauthorized" });
}
diff --git a/server/src/api/user/getOrgApiUsage.ts b/server/src/api/user/getOrgApiUsage.ts
new file mode 100644
index 000000000..cfa16887a
--- /dev/null
+++ b/server/src/api/user/getOrgApiUsage.ts
@@ -0,0 +1,70 @@
+import { FastifyReply, FastifyRequest } from "fastify";
+import { dailyQuotaResetSeconds, peekDailyUsage } from "../../lib/apiRateLimit.js";
+import { resolveDailyLimit } from "../../lib/apiRateLimitPolicy.js";
+import { API_BURST_LIMIT, API_BURST_WINDOW_MS, IS_CLOUD } from "../../lib/const.js";
+
+export interface OrgApiUsageResponse {
+ /** False on self-hosted, where API requests are not metered. */
+ metered: boolean;
+ /**
+ * False when the counter could not be read (Redis unavailable). The quota is
+ * still being enforced; only this reading is missing, and callers should say
+ * so rather than render a zero.
+ */
+ available: boolean;
+ dailyUsed: number;
+ dailyLimit: number;
+ dailyRemaining: number;
+ /** Seconds until the quota resets at 00:00 UTC. */
+ resetsInSeconds: number;
+ burstLimit: number;
+ burstWindowSeconds: number;
+}
+
+/**
+ * Today's API request usage for an organization's own API keys.
+ *
+ * Covers organization-owned keys only. Personal keys are budgeted per user
+ * (that is the bucket they are charged against), so their usage is not part of
+ * this number.
+ */
+export async function getOrgApiUsage(
+ request: FastifyRequest<{ Params: { organizationId: string } }>,
+ reply: FastifyReply
+) {
+ const { organizationId } = request.params;
+
+ if (!IS_CLOUD) {
+ return reply.send({
+ metered: false,
+ available: true,
+ dailyUsed: 0,
+ dailyLimit: 0,
+ dailyRemaining: 0,
+ resetsInSeconds: dailyQuotaResetSeconds(),
+ burstLimit: API_BURST_LIMIT,
+ burstWindowSeconds: API_BURST_WINDOW_MS / 1000,
+ } satisfies OrgApiUsageResponse);
+ }
+
+ try {
+ const [dailyLimit, dailyUsed] = await Promise.all([
+ resolveDailyLimit({ organizationId }),
+ peekDailyUsage(organizationId),
+ ]);
+
+ return reply.send({
+ metered: true,
+ available: dailyUsed !== null,
+ dailyUsed: dailyUsed ?? 0,
+ dailyLimit,
+ dailyRemaining: Math.max(dailyLimit - (dailyUsed ?? 0), 0),
+ resetsInSeconds: dailyQuotaResetSeconds(),
+ burstLimit: API_BURST_LIMIT,
+ burstWindowSeconds: API_BURST_WINDOW_MS / 1000,
+ } satisfies OrgApiUsageResponse);
+ } catch (error) {
+ request.log.error({ err: error, organizationId }, "Failed to read API usage");
+ return reply.status(500).send({ error: "Failed to fetch API usage" });
+ }
+}
diff --git a/server/src/api/user/index.ts b/server/src/api/user/index.ts
index 94be35394..96eff4ada 100644
--- a/server/src/api/user/index.ts
+++ b/server/src/api/user/index.ts
@@ -12,4 +12,5 @@ export { unsubscribeMarketing, oneClickUnsubscribeMarketing } from "./unsubscrib
// API Keys
export { createUserApiKey } from "./createApiKey.js";
export { createOrgApiKey } from "./createOrgApiKey.js";
+export { getOrgApiUsage } from "./getOrgApiUsage.js";
diff --git a/server/src/db/redis/apiRateLimit.integration.test.ts b/server/src/db/redis/apiRateLimit.integration.test.ts
new file mode 100644
index 000000000..6884453dc
--- /dev/null
+++ b/server/src/db/redis/apiRateLimit.integration.test.ts
@@ -0,0 +1,178 @@
+import RedisMock from "ioredis-mock";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { API_RATE_LIMIT_LUA } from "./apiRateLimitLua.js";
+
+// Behavioral tests for the rate limiter Lua, executed for real by ioredis-mock's
+// embedded Lua runtime. The interaction between the two tiers β€” which one denies
+// first, and which one gets charged when the other denies β€” only exists inside
+// the script, so TS-level mocks cannot cover it.
+
+const BURST_CAPACITY = 50;
+const BURST_REFILL_PER_SECOND = 5;
+const DAILY_LIMIT = 100;
+const DAILY_TTL = 90_000;
+
+const BURST_KEY = "rl:burst:org1";
+const DAILY_KEY = "rl:day:org1:20000";
+
+interface LimiterMockRedis {
+ apiRateLimit(...args: (string | number)[]): Promise<[number, number, number, number, number]>;
+ get(key: string): Promise<string | null>;
+ ttl(key: string): Promise<number>;
+ flushall(): Promise<unknown>;
+}
+
+let redis: LimiterMockRedis;
+
+function consume(opts: { dailyLimit?: number; observe?: boolean } = {}) {
+ return redis.apiRateLimit(
+ BURST_KEY,
+ DAILY_KEY,
+ BURST_CAPACITY,
+ BURST_REFILL_PER_SECOND,
+ opts.dailyLimit ?? DAILY_LIMIT,
+ DAILY_TTL,
+ opts.observe ? 1 : 0
+ );
+}
+
+async function consumeTimes(count: number, opts: { dailyLimit?: number; observe?: boolean } = {}) {
+ let last: [number, number, number, number, number] | undefined;
+ for (let i = 0; i < count; i++) {
+ last = await consume(opts);
+ }
+ return last!;
+}
+
+describe("apiRateLimit Lua script", () => {
+ beforeEach(async () => {
+ vi.useFakeTimers();
+ vi.setSystemTime(new Date("2024-05-01T12:00:00Z"));
+ const client = new RedisMock();
+ client.defineCommand("apiRateLimit", { numberOfKeys: 2, lua: API_RATE_LIMIT_LUA });
+ redis = client as unknown as LimiterMockRedis;
+ await redis.flushall();
+ });
+
+ afterEach(() => {
+ vi.useRealTimers();
+ });
+
+ it("admits a full bucket in one spike and reports the remaining tokens", async () => {
+ const [allowed, scope, burstRemaining, dailyRemaining] = await consume();
+
+ expect(allowed).toBe(1);
+ expect(scope).toBe(0);
+ expect(burstRemaining).toBe(BURST_CAPACITY - 1);
+ expect(dailyRemaining).toBe(DAILY_LIMIT - 1);
+
+ const [lastAllowed, lastScope, lastRemaining] = await consumeTimes(BURST_CAPACITY - 1);
+ expect(lastAllowed).toBe(1);
+ expect(lastScope).toBe(0);
+ expect(lastRemaining).toBe(0);
+ });
+
+ it("denies on the burst tier once the bucket is drained", async () => {
+ await consumeTimes(BURST_CAPACITY);
+
+ const [allowed, scope, burstRemaining, , retryAfterMs] = await consume();
+
+ expect(allowed).toBe(0);
+ expect(scope).toBe(1);
+ expect(burstRemaining).toBe(0);
+ expect(retryAfterMs).toBeGreaterThan(0);
+ expect(retryAfterMs).toBeLessThanOrEqual(1000 / BURST_REFILL_PER_SECOND);
+ });
+
+ it("refills the bucket continuously rather than at a window boundary", async () => {
+ await consumeTimes(BURST_CAPACITY);
+ expect((await consume())[0]).toBe(0);
+
+ // One second at 5 tokens/s buys 5 requests, not a whole new window.
+ vi.advanceTimersByTime(1000);
+
+ const admitted = [];
+ for (let i = 0; i < 6; i++) {
+ admitted.push((await consume())[0]);
+ }
+ expect(admitted).toEqual([1, 1, 1, 1, 1, 0]);
+ });
+
+ it("restores at most a full bucket no matter how long it sits idle", async () => {
+ await consumeTimes(BURST_CAPACITY);
+ vi.advanceTimersByTime(60 * 60 * 1000);
+
+ const [, , burstRemaining] = await consume();
+ expect(burstRemaining).toBe(BURST_CAPACITY - 1);
+ });
+
+ it("denies on the daily tier without charging the burst bucket", async () => {
+ // Drain the quota, refilling the burst bucket between spikes.
+ for (let batch = 0; batch < 2; batch++) {
+ await consumeTimes(BURST_CAPACITY);
+ vi.advanceTimersByTime(BURST_CAPACITY / BURST_REFILL_PER_SECOND * 1000);
+ }
+
+ const [allowed, scope, burstRemaining, dailyRemaining] = await consume();
+
+ expect(allowed).toBe(0);
+ expect(scope).toBe(2);
+ expect(dailyRemaining).toBe(0);
+ // The refused request must not cost a burst token: an exhausted quota would
+ // otherwise keep draining a budget the caller can no longer spend.
+ expect(burstRemaining).toBe(BURST_CAPACITY);
+ expect(await redis.get(DAILY_KEY)).toBe(String(DAILY_LIMIT));
+ });
+
+ it("reports the daily tier ahead of the burst tier when both are exhausted", async () => {
+ // Two full spikes with one refill between them lands on the quota and the
+ // empty bucket at the same instant.
+ await consumeTimes(BURST_CAPACITY);
+ vi.advanceTimersByTime((BURST_CAPACITY / BURST_REFILL_PER_SECOND) * 1000);
+ await consumeTimes(BURST_CAPACITY);
+
+ const [allowed, scope, burstRemaining] = await consume();
+
+ expect(allowed).toBe(0);
+ expect(burstRemaining).toBe(0);
+ // Both tiers would deny, but daily is the one worth reporting: it is the
+ // limit the caller has to wait hours rather than milliseconds for.
+ expect(scope).toBe(2);
+ });
+
+ it("does not charge the quota for a request the burst tier refused", async () => {
+ await consumeTimes(BURST_CAPACITY);
+ await consumeTimes(10);
+
+ // Only the admitted requests count toward the daily quota β€” a client stuck
+ // in a retry loop must not burn its whole day against a closed burst gate.
+ expect(await redis.get(DAILY_KEY)).toBe(String(BURST_CAPACITY));
+ });
+
+ it("expires the daily counter so the quota resets by key rollover", async () => {
+ await consume();
+ expect(await redis.ttl(DAILY_KEY)).toBeGreaterThan(0);
+ expect(await redis.ttl(DAILY_KEY)).toBeLessThanOrEqual(DAILY_TTL);
+ });
+
+ it("treats a daily limit of 0 as unlimited", async () => {
+ const [allowed, scope, , dailyRemaining] = await consume({ dailyLimit: 0 });
+
+ expect(allowed).toBe(1);
+ expect(scope).toBe(0);
+ expect(dailyRemaining).toBe(-1);
+ expect(await redis.get(DAILY_KEY)).toBeNull();
+ });
+
+ it("counts but never denies in observe mode", async () => {
+ await consumeTimes(BURST_CAPACITY, { observe: true });
+
+ const [allowed, scope] = await consume({ observe: true });
+
+ // The caller still learns it would have been denied, and the daily total
+ // keeps climbing so a shadow run measures real traffic.
+ expect(allowed).toBe(0);
+ expect(scope).toBe(1);
+ expect(await redis.get(DAILY_KEY)).toBe(String(BURST_CAPACITY + 1));
+ });
+});
diff --git a/server/src/db/redis/apiRateLimitLua.ts b/server/src/db/redis/apiRateLimitLua.ts
new file mode 100644
index 000000000..dcb1e213b
--- /dev/null
+++ b/server/src/db/redis/apiRateLimitLua.ts
@@ -0,0 +1,97 @@
+/**
+ * Two-tier API rate limiter: a token-bucket burst guard and a UTC-day quota,
+ * evaluated and committed in one atomic round trip.
+ *
+ * Both tiers are checked *before* either is charged, so a request refused on
+ * quota never also drains the burst bucket β€” otherwise a client stuck at its
+ * daily limit would keep paying burst tokens for requests it can't make, and
+ * `RateLimit-Remaining` would report a burst budget that no longer exists.
+ *
+ * `TIME` makes the script non-deterministic, which Redis permits alongside
+ * writes under effects replication (the default since 5.0). Reading the clock
+ * inside Redis rather than passing it from Node keeps every app instance on one
+ * clock, so skew between instances cannot refill a bucket early.
+ *
+ * KEYS[1] burst bucket, a hash of { tokens, ts }
+ * KEYS[2] daily counter for the current UTC day (the day is part of the key,
+ * so the reset is a natural key rollover rather than a scheduled wipe)
+ *
+ * ARGV[1] burst capacity (tokens)
+ * ARGV[2] burst refill rate (tokens per second)
+ * ARGV[3] daily limit, 0 = unlimited
+ * ARGV[4] TTL in seconds for the daily counter
+ * ARGV[5] 1 = observe only: account for the request but never deny it
+ *
+ * Returns { allowed, scope, burstRemaining, dailyRemaining, retryAfterMs }
+ * where scope is 0 = none, 1 = burst, 2 = daily and dailyRemaining is -1 when
+ * the daily tier is unlimited.
+ */
+export const API_RATE_LIMIT_LUA = `
+local capacity = tonumber(ARGV[1])
+local refill = tonumber(ARGV[2])
+local dailyLimit = tonumber(ARGV[3])
+local dailyTtl = tonumber(ARGV[4])
+local observe = tonumber(ARGV[5]) == 1
+
+local time = redis.call('TIME')
+local now = tonumber(time[1]) + tonumber(time[2]) / 1000000
+
+local dailyUsed = 0
+if dailyLimit > 0 then
+ dailyUsed = tonumber(redis.call('GET', KEYS[2])) or 0
+end
+local dailyExceeded = dailyLimit > 0 and dailyUsed >= dailyLimit
+
+local bucket = redis.call('HMGET', KEYS[1], 'tokens', 'ts')
+local tokens = tonumber(bucket[1])
+local ts = tonumber(bucket[2])
+if tokens == nil or ts == nil then
+ tokens = capacity
+else
+ tokens = math.min(capacity, tokens + (now - ts) * refill)
+end
+local burstExceeded = tokens < 1
+
+local allowed = not dailyExceeded and not burstExceeded
+
+-- Charge the request when it is allowed, and always in observe mode: shadow
+-- runs are only useful if their daily totals match the traffic that would have
+-- been counted under enforcement.
+if allowed or observe then
+ if not burstExceeded then
+ tokens = tokens - 1
+ end
+ redis.call('HSET', KEYS[1], 'tokens', tokens, 'ts', now)
+ -- Outlive a full refill so an idle owner's bucket expires instead of
+ -- lingering; a missing bucket is indistinguishable from a full one.
+ redis.call('PEXPIRE', KEYS[1], math.ceil(capacity / refill * 1000) + 1000)
+ if dailyLimit > 0 then
+ dailyUsed = redis.call('INCR', KEYS[2])
+ if dailyUsed == 1 then
+ redis.call('EXPIRE', KEYS[2], dailyTtl)
+ end
+ end
+end
+
+local scope = 0
+local retryAfterMs = 0
+if dailyExceeded then
+ scope = 2
+elseif burstExceeded then
+ scope = 1
+ retryAfterMs = math.ceil((1 - tokens) / refill * 1000)
+end
+
+local dailyRemaining = -1
+if dailyLimit > 0 then
+ dailyRemaining = math.max(dailyLimit - dailyUsed, 0)
+end
+
+return {
+ allowed and 1 or 0,
+ scope,
+ math.floor(math.max(tokens, 0)),
+ dailyRemaining,
+ retryAfterMs,
+}
+`;
diff --git a/server/src/db/redis/redis.ts b/server/src/db/redis/redis.ts
index 10789bc23..bccc2018b 100644
--- a/server/src/db/redis/redis.ts
+++ b/server/src/db/redis/redis.ts
@@ -1,5 +1,6 @@
import { Redis } from "ioredis";
import { createServiceLogger } from "../../lib/logger/logger.js";
+import { API_RATE_LIMIT_LUA } from "./apiRateLimitLua.js";
import { STICKY_RESOLVE_LUA } from "./stickyResolveLua.js";
const logger = createServiceLogger("redis");
@@ -156,6 +157,61 @@ export function stickyResolve(input: StickyResolveInput): Promise<[string, Stick
);
}
+// Dedicated connection for API-key rate limiting, isolated for the same reason
+// as `sessionRedis`: every authenticated API request runs this script, and a
+// shared connection would put it behind the heavier anomaly Lua call.
+export const apiRateLimitRedis = createRedisClient("api-rate-limit");
+
+apiRateLimitRedis.defineCommand("apiRateLimit", {
+ numberOfKeys: 2,
+ lua: API_RATE_LIMIT_LUA,
+});
+
+interface ApiRateLimitRedis extends Redis {
+ apiRateLimit(...args: (string | number)[]): Promise<[number, number, number, number, number]>;
+}
+
+export interface ApiRateLimitInput {
+ burstKey: string;
+ dailyKey: string;
+ burstCapacity: number;
+ /** Tokens restored per second; capacity/refillPerSecond is the drain time. */
+ burstRefillPerSecond: number;
+ /** 0 = unlimited (self-hosted). */
+ dailyLimit: number;
+ dailyTtlSeconds: number;
+ observeOnly: boolean;
+}
+
+export interface ApiRateLimitResult {
+ allowed: boolean;
+ /** 0 = within limits, 1 = burst tier, 2 = daily tier. */
+ scope: number;
+ burstRemaining: number;
+ /** -1 when the daily tier is unlimited. */
+ dailyRemaining: number;
+ retryAfterMs: number;
+}
+
+/**
+ * Charge one request against an owner's burst bucket and daily quota. Atomic
+ * across all workers and replicas; one round-trip.
+ */
+export async function apiRateLimitConsume(input: ApiRateLimitInput): Promise<ApiRateLimitResult> {
+ const [allowed, scope, burstRemaining, dailyRemaining, retryAfterMs] = await (
+ apiRateLimitRedis as ApiRateLimitRedis
+ ).apiRateLimit(
+ input.burstKey,
+ input.dailyKey,
+ input.burstCapacity,
+ input.burstRefillPerSecond,
+ input.dailyLimit,
+ input.dailyTtlSeconds,
+ input.observeOnly ? 1 : 0
+ );
+ return { allowed: allowed === 1, scope, burstRemaining, dailyRemaining, retryAfterMs };
+}
+
// Rolling-window counters for the bot anomaly scorer. Each counter is a sorted
// set: member -> observation, score -> time (ms). For event-rate counters the
// member is a unique per-event token (so cardinality == event count); for
diff --git a/server/src/index.ts b/server/src/index.ts
index a0c261dca..a9016b3bb 100644
--- a/server/src/index.ts
+++ b/server/src/index.ts
@@ -150,6 +150,7 @@ import {
createUserApiKey,
createUserInOrganization,
getMyOrganizations,
+ getOrgApiUsage,
getUserOrganizations,
listOrganizationMembers,
oneClickUnsubscribeMarketing,
@@ -489,6 +490,7 @@ async function userRoutes(fastify: FastifyInstance) {
fastify.post("/user/unsubscribe-marketing-oneclick", oneClickUnsubscribeMarketing); // Public - for List-Unsubscribe header
fastify.post("/user/api-keys", authOnlyNoScopedKeys, createUserApiKey);
fastify.post("/organizations/:organizationId/api-keys", orgAdminNoScopedKeys, createOrgApiKey);
+ fastify.get("/organizations/:organizationId/api-usage", orgOrgRead, getOrgApiUsage);
}
async function gscRoutes(fastify: FastifyInstance) {
diff --git a/server/src/lib/apiRateLimit.test.ts b/server/src/lib/apiRateLimit.test.ts
new file mode 100644
index 000000000..f4185b73e
--- /dev/null
+++ b/server/src/lib/apiRateLimit.test.ts
@@ -0,0 +1,140 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const apiRateLimitConsume = vi.fn();
+
+vi.mock("../db/redis/redis.js", () => ({ apiRateLimitConsume }));
+vi.mock("./const.js", async importOriginal => ({
+ ...(await importOriginal<typeof import("./const.js")>()),
+ IS_CLOUD: true,
+}));
+vi.mock("./logger/logger.js", () => ({
+ createServiceLogger: () => ({ warn: vi.fn(), info: vi.fn(), error: vi.fn(), debug: vi.fn() }),
+}));
+
+const { consumeApiRateLimit, dailyLimitForPlan } = await import("./apiRateLimit.js");
+const { API_BURST_LIMIT, PRO_API_DAILY_LIMIT, STANDARD_API_DAILY_LIMIT } = await import("./const.js");
+
+const redisResult = (overrides: Record<string, unknown> = {}) => ({
+ allowed: true,
+ scope: 0,
+ burstRemaining: 49,
+ dailyRemaining: 4999,
+ retryAfterMs: 0,
+ ...overrides,
+});
+
+describe("dailyLimitForPlan", () => {
+ it("gives Pro and custom plans the higher quota", () => {
+ expect(dailyLimitForPlan("pro")).toBe(PRO_API_DAILY_LIMIT);
+ expect(dailyLimitForPlan("pro-annual")).toBe(PRO_API_DAILY_LIMIT);
+ expect(dailyLimitForPlan("custom")).toBe(PRO_API_DAILY_LIMIT);
+ });
+
+ it("gives every other plan the standard quota", () => {
+ expect(dailyLimitForPlan("standard")).toBe(STANDARD_API_DAILY_LIMIT);
+ expect(dailyLimitForPlan("free")).toBe(STANDARD_API_DAILY_LIMIT);
+ expect(dailyLimitForPlan(null)).toBe(STANDARD_API_DAILY_LIMIT);
+ expect(dailyLimitForPlan(undefined)).toBe(STANDARD_API_DAILY_LIMIT);
+ });
+});
+
+describe("consumeApiRateLimit", () => {
+ beforeEach(() => {
+ apiRateLimitConsume.mockReset();
+ vi.useFakeTimers();
+ vi.setSystemTime(new Date("2024-05-01T23:00:00Z"));
+ });
+
+ afterEach(() => {
+ vi.useRealTimers();
+ });
+
+ it("keys the budget on the owner and the current UTC day", async () => {
+ apiRateLimitConsume.mockResolvedValue(redisResult());
+
+ await consumeApiRateLimit("org1", 5000);
+
+ expect(apiRateLimitConsume).toHaveBeenCalledWith(
+ expect.objectContaining({ burstKey: "rl:burst:org1", dailyKey: `rl:day:org1:${Math.floor(Date.UTC(2024, 4, 1, 23) / 86_400_000)}` })
+ );
+ });
+
+ it("reports a daily denial as retriable at the next UTC midnight", async () => {
+ apiRateLimitConsume.mockResolvedValue(redisResult({ allowed: false, scope: 2, dailyRemaining: 0 }));
+
+ const decision = await consumeApiRateLimit("org1", 5000);
+
+ expect(decision.allowed).toBe(false);
+ expect(decision.scope).toBe("daily");
+ expect(decision.retryAfterSeconds).toBe(3600);
+ expect(decision.dailyResetSeconds).toBe(3600);
+ });
+
+ it("rounds a sub-second burst denial up to one second", async () => {
+ apiRateLimitConsume.mockResolvedValue(
+ redisResult({ allowed: false, scope: 1, burstRemaining: 0, retryAfterMs: 200 })
+ );
+
+ const decision = await consumeApiRateLimit("org1", 5000);
+
+ // Retry-After is in whole seconds; rounding down to 0 would invite an
+ // immediate retry that is guaranteed to fail again.
+ expect(decision.scope).toBe("burst");
+ expect(decision.retryAfterSeconds).toBe(1);
+ });
+
+ it("falls back to in-process counters when Redis is unreachable", async () => {
+ apiRateLimitConsume.mockRejectedValue(new Error("redis down"));
+
+ const first = await consumeApiRateLimit("fallback-owner", 5000);
+ expect(first.allowed).toBe(true);
+ expect(first.burstRemaining).toBe(API_BURST_LIMIT - 1);
+
+ for (let i = 1; i < API_BURST_LIMIT; i++) {
+ await consumeApiRateLimit("fallback-owner", 5000);
+ }
+
+ // The burst ceiling still holds per instance β€” the tier that protects the
+ // database survives a Redis outage even though the accounting is degraded.
+ const denied = await consumeApiRateLimit("fallback-owner", 5000);
+ expect(denied.allowed).toBe(false);
+ expect(denied.scope).toBe("burst");
+ });
+
+ it("enforces the daily quota in the fallback too", async () => {
+ apiRateLimitConsume.mockRejectedValue(new Error("redis down"));
+
+ for (let i = 0; i < 3; i++) {
+ await consumeApiRateLimit("fallback-quota", 3);
+ }
+
+ const denied = await consumeApiRateLimit("fallback-quota", 3);
+ expect(denied.allowed).toBe(false);
+ expect(denied.scope).toBe("daily");
+ expect(denied.dailyRemaining).toBe(0);
+ });
+
+ it("treats a zero daily limit as unlimited in the fallback", async () => {
+ apiRateLimitConsume.mockRejectedValue(new Error("redis down"));
+
+ const decision = await consumeApiRateLimit("fallback-selfhosted", 0);
+
+ expect(decision.allowed).toBe(true);
+ expect(decision.dailyLimit).toBe(0);
+ });
+
+ // Declaration order matters: this trips the shared breaker, so it runs last.
+ it("stops calling Redis after a run of failures", async () => {
+ apiRateLimitConsume.mockRejectedValue(new Error("redis down"));
+
+ for (let i = 0; i < 5; i++) {
+ await consumeApiRateLimit("breaker-owner", 5000);
+ }
+ const callsDuringOutage = apiRateLimitConsume.mock.calls.length;
+ await consumeApiRateLimit("breaker-owner", 5000);
+
+ // Every request would otherwise pay the full Redis command timeout, adding
+ // a second of latency to the entire API for the length of an outage.
+ expect(apiRateLimitConsume.mock.calls.length).toBe(callsDuringOutage);
+ });
+});
diff --git a/server/src/lib/apiRateLimit.ts b/server/src/lib/apiRateLimit.ts
new file mode 100644
index 000000000..f5a15e7ff
--- /dev/null
+++ b/server/src/lib/apiRateLimit.ts
@@ -0,0 +1,250 @@
+import { apiRateLimitConsume, apiRateLimitRedis } from "../db/redis/redis.js";
+import {
+ API_BURST_LIMIT,
+ API_BURST_WINDOW_MS,
+ API_RATE_LIMIT_OBSERVE_ONLY,
+ IS_CLOUD,
+ PRO_API_DAILY_LIMIT,
+ STANDARD_API_DAILY_LIMIT,
+} from "./const.js";
+import { createServiceLogger } from "./logger/logger.js";
+
+const logger = createServiceLogger("api-rate-limit");
+
+const MS_PER_DAY = 86_400_000;
+const BURST_REFILL_PER_SECOND = API_BURST_LIMIT / (API_BURST_WINDOW_MS / 1000);
+// Long enough that the counter survives clock skew around the rollover, short
+// enough that yesterday's keys are gone well before they matter.
+const DAILY_TTL_SECONDS = 90_000;
+
+export type RateLimitScope = "burst" | "daily";
+
+export interface RateLimitDecision {
+ /** Whether the request may proceed. Always true in observe-only mode. */
+ allowed: boolean;
+ /** True when observe-only mode admitted a request the limits would have denied. */
+ wouldHaveDenied: boolean;
+ /** Which tier bound the request; null when it was within both. */
+ scope: RateLimitScope | null;
+ burstLimit: number;
+ burstRemaining: number;
+ /** Seconds until the burst bucket is full again. */
+ burstResetSeconds: number;
+ /** 0 when the daily tier is unlimited (self-hosted). */
+ dailyLimit: number;
+ dailyRemaining: number;
+ /** Seconds until the next UTC midnight. */
+ dailyResetSeconds: number;
+ /** Seconds until the binding tier admits another request. 0 when allowed. */
+ retryAfterSeconds: number;
+}
+
+/**
+ * The daily quota for a plan. Mirrors `apiKeyLimitForPlan`'s plan matching so
+ * the two limits can never disagree about what counts as Pro. Self-hosted is
+ * unlimited (0), as it has no plans and no shared infrastructure to protect.
+ */
+export function dailyLimitForPlan(planName: string | null | undefined): number {
+ if (!IS_CLOUD) {
+ return 0;
+ }
+ const plan = planName || "free";
+ return plan.includes("pro") || plan === "custom" ? PRO_API_DAILY_LIMIT : STANDARD_API_DAILY_LIMIT;
+}
+
+/** UTC day number. Part of the daily key, so the quota resets by key rollover. */
+function utcDay(now: number): number {
+ return Math.floor(now / MS_PER_DAY);
+}
+
+/**
+ * Today's request count for an owner, without charging one. Returns null when
+ * the counter can't be read, so callers can say "unavailable" rather than
+ * showing a confident zero.
+ */
+export async function peekDailyUsage(ownerId: string): Promise<number | null> {
+ const now = Date.now();
+ if (breakerIsOpen(now)) {
+ return null;
+ }
+ try {
+ const used = await apiRateLimitRedis.get(`rl:day:${ownerId}:${utcDay(now)}`);
+ return used === null ? 0 : Number(used);
+ } catch {
+ return null;
+ }
+}
+
+/** Seconds until the daily quota resets, for callers reporting usage. */
+export function dailyQuotaResetSeconds(): number {
+ return secondsUntilUtcMidnight(Date.now());
+}
+
+function secondsUntilUtcMidnight(now: number): number {
+ return Math.ceil(((utcDay(now) + 1) * MS_PER_DAY - now) / 1000);
+}
+
+/**
+ * Per-instance fallback used only while Redis is unreachable. It sees one
+ * instance's share of traffic, so N instances allow up to N times the limits β€”
+ * a deliberate trade: degraded accounting never blocks a legitimate request,
+ * and the burst ceiling still holds per instance, which is the tier that
+ * protects the database.
+ */
+interface FallbackState {
+ tokens: number;
+ ts: number;
+ day: number;
+ dailyUsed: number;
+}
+
+const fallbackState = new Map<string, FallbackState>();
+const FALLBACK_MAX_OWNERS = 10_000;
+
+// Redis commands time out after a second. Paying that on every request for the
+// length of an outage would add a second of latency to the whole API, so a run
+// of failures parks the limiter on the in-process path and it retries only
+// occasionally.
+const BREAKER_FAILURE_THRESHOLD = 5;
+const BREAKER_COOLDOWN_MS = 10_000;
+let consecutiveFailures = 0;
+let breakerOpenUntil = 0;
+
+function breakerIsOpen(now: number): boolean {
+ return now < breakerOpenUntil;
+}
+
+function recordRedisFailure(now: number): void {
+ consecutiveFailures += 1;
+ if (consecutiveFailures >= BREAKER_FAILURE_THRESHOLD) {
+ breakerOpenUntil = now + BREAKER_COOLDOWN_MS;
+ }
+}
+
+function recordRedisSuccess(): void {
+ consecutiveFailures = 0;
+ breakerOpenUntil = 0;
+}
+
+function pruneFallbackState(now: number): void {
+ if (fallbackState.size <= FALLBACK_MAX_OWNERS) {
+ return;
+ }
+ const today = utcDay(now);
+ for (const [owner, state] of fallbackState) {
+ // A full bucket carries no information, so an idle owner can be dropped.
+ if (state.day !== today || (state.tokens >= API_BURST_LIMIT && now - state.ts > API_BURST_WINDOW_MS)) {
+ fallbackState.delete(owner);
+ }
+ }
+ // If that freed nothing, evict least-recently-seen owners instead of clearing
+ // the map: wiping every counter at once would hand a full budget back to
+ // everybody, turning the memory bound into a way around the limiter.
+ if (fallbackState.size > FALLBACK_MAX_OWNERS) {
+ const byAge = [...fallbackState.entries()].sort((a, b) => a[1].ts - b[1].ts);
+ for (const [owner] of byAge.slice(0, fallbackState.size - FALLBACK_MAX_OWNERS)) {
+ fallbackState.delete(owner);
+ }
+ }
+}
+
+function consumeInProcess(ownerId: string, dailyLimit: number, now: number): RateLimitDecision {
+ pruneFallbackState(now);
+ const today = utcDay(now);
+ const state = fallbackState.get(ownerId);
+ const bucket: FallbackState =
+ !state || state.day !== today
+ ? { tokens: API_BURST_LIMIT, ts: now, day: today, dailyUsed: 0 }
+ : {
+ ...state,
+ tokens: Math.min(API_BURST_LIMIT, state.tokens + ((now - state.ts) / 1000) * BURST_REFILL_PER_SECOND),
+ ts: now,
+ };
+
+ const dailyExceeded = dailyLimit > 0 && bucket.dailyUsed >= dailyLimit;
+ const burstExceeded = bucket.tokens < 1;
+ const allowed = !dailyExceeded && !burstExceeded;
+
+ if (allowed || API_RATE_LIMIT_OBSERVE_ONLY) {
+ if (!burstExceeded) {
+ bucket.tokens -= 1;
+ }
+ bucket.dailyUsed += 1;
+ }
+ fallbackState.set(ownerId, bucket);
+
+ return buildDecision({
+ allowed,
+ scope: dailyExceeded ? 2 : burstExceeded ? 1 : 0,
+ burstRemaining: Math.floor(Math.max(bucket.tokens, 0)),
+ dailyRemaining: dailyLimit > 0 ? Math.max(dailyLimit - bucket.dailyUsed, 0) : -1,
+ retryAfterMs: burstExceeded ? Math.ceil(((1 - bucket.tokens) / BURST_REFILL_PER_SECOND) * 1000) : 0,
+ dailyLimit,
+ now,
+ });
+}
+
+function buildDecision(input: {
+ allowed: boolean;
+ scope: number;
+ burstRemaining: number;
+ dailyRemaining: number;
+ retryAfterMs: number;
+ dailyLimit: number;
+ now: number;
+}): RateLimitDecision {
+ const scope: RateLimitScope | null = input.scope === 2 ? "daily" : input.scope === 1 ? "burst" : null;
+ const dailyResetSeconds = secondsUntilUtcMidnight(input.now);
+ return {
+ allowed: input.allowed || API_RATE_LIMIT_OBSERVE_ONLY,
+ wouldHaveDenied: !input.allowed,
+ scope,
+ burstLimit: API_BURST_LIMIT,
+ burstRemaining: input.burstRemaining,
+ burstResetSeconds: Math.ceil((API_BURST_LIMIT - input.burstRemaining) / BURST_REFILL_PER_SECOND),
+ dailyLimit: input.dailyLimit,
+ dailyRemaining: Math.max(input.dailyRemaining, 0),
+ dailyResetSeconds,
+ retryAfterSeconds:
+ scope === "daily"
+ ? dailyResetSeconds
+ : scope === "burst"
+ ? Math.max(Math.ceil(input.retryAfterMs / 1000), 1)
+ : 0,
+ };
+}
+
+/**
+ * Charge one request against an owner's budget and report the outcome.
+ *
+ * `ownerId` is the credential's owner β€” an organization id for org keys, a user
+ * id for user keys β€” never the key id, so an org cannot widen its budget by
+ * minting more keys.
+ */
+export async function consumeApiRateLimit(ownerId: string, dailyLimit: number): Promise<RateLimitDecision> {
+ const now = Date.now();
+ if (breakerIsOpen(now)) {
+ return consumeInProcess(ownerId, dailyLimit, now);
+ }
+ try {
+ const result = await apiRateLimitConsume({
+ burstKey: `rl:burst:${ownerId}`,
+ dailyKey: `rl:day:${ownerId}:${utcDay(now)}`,
+ burstCapacity: API_BURST_LIMIT,
+ burstRefillPerSecond: BURST_REFILL_PER_SECOND,
+ dailyLimit,
+ dailyTtlSeconds: DAILY_TTL_SECONDS,
+ observeOnly: API_RATE_LIMIT_OBSERVE_ONLY,
+ });
+ recordRedisSuccess();
+ return buildDecision({ ...result, dailyLimit, now });
+ } catch (error) {
+ recordRedisFailure(now);
+ // Only the failure that trips the breaker is logged in full; the rest of an
+ // outage would just repeat it once per request.
+ if (consecutiveFailures === BREAKER_FAILURE_THRESHOLD) {
+ logger.warn({ err: error, ownerId }, "Redis rate limit failing; using in-process counters until it recovers");
+ }
+ return consumeInProcess(ownerId, dailyLimit, now);
+ }
+}
diff --git a/server/src/lib/apiRateLimitCharging.test.ts b/server/src/lib/apiRateLimitCharging.test.ts
new file mode 100644
index 000000000..9fde2998d
--- /dev/null
+++ b/server/src/lib/apiRateLimitCharging.test.ts
@@ -0,0 +1,138 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { INTERNAL_BEARER_HANDOFF_HEADER } from "./bearerAuth.js";
+
+// What a *request* costs. Budget is denominated in API requests, but several
+// guards resolve the same credential more than once per HTTP request, and the
+// MCP proxy injects requests carrying a handoff nonce. These tests pin down how
+// many units each of those shapes actually consumes.
+
+const decision = {
+ allowed: true,
+ wouldHaveDenied: false,
+ scope: null,
+ burstLimit: 50,
+ burstRemaining: 49,
+ burstResetSeconds: 1,
+ dailyLimit: 5_000,
+ dailyRemaining: 4_999,
+ dailyResetSeconds: 3_600,
+ retryAfterSeconds: 0,
+};
+
+const verifyApiKey = vi.fn();
+const consumeRateLimitForIdentity = vi.fn();
+
+// The handoff registry is module state, and resetModules gives auth-utils a
+// fresh copy of it β€” so the test has to register nonces through the same graph
+// auth-utils is reading from.
+async function loadModules(isCloud: boolean) {
+ vi.resetModules();
+ vi.doMock("./auth.js", () => ({
+ auth: { api: { verifyApiKey, getMcpSession: vi.fn(async () => null), getSession: vi.fn(async () => null) } },
+ }));
+ vi.doMock("./apiRateLimitPolicy.js", () => ({ consumeRateLimitForIdentity }));
+ vi.doMock("../db/postgres/postgres.js", () => ({ db: {} }));
+ vi.doMock("./const.js", async importOriginal => ({
+ ...(await importOriginal<typeof import("./const.js")>()),
+ IS_CLOUD: isCloud,
+ }));
+ const { checkApiKey } = await import("./auth-utils.js");
+ const { registerBearerHandoff, releaseBearerHandoff } = await import("./bearerAuth.js");
+ return { checkApiKey, registerBearerHandoff, releaseBearerHandoff };
+}
+
+// An organization key checked against its own organization resolves without
+// touching the database.
+const orgRequest = (extraHeaders: Record<string, string> = {}) =>
+ ({ headers: { authorization: "Bearer rb_org_key", ...extraHeaders }, query: {} }) as any;
+
+describe("rate limit charging per request", () => {
+ beforeEach(() => {
+ verifyApiKey.mockReset();
+ consumeRateLimitForIdentity.mockReset();
+ verifyApiKey.mockResolvedValue({ valid: true, key: { referenceId: "org_a", permissions: null, configId: "org" } });
+ consumeRateLimitForIdentity.mockResolvedValue(decision);
+ });
+
+ it("charges one unit no matter how many times a request resolves the credential", async () => {
+ const { checkApiKey } = await loadModules(true);
+ const req = orgRequest();
+
+ // A guard, then its fallback, then a handler calling getUserIdFromRequest.
+ await checkApiKey(req, { organizationId: "org_a" });
+ await checkApiKey(req, { organizationId: "org_a" });
+ await checkApiKey(req, { organizationId: "org_a" });
+
+ expect(consumeRateLimitForIdentity).toHaveBeenCalledTimes(1);
+ });
+
+ it("charges separate requests separately", async () => {
+ const { checkApiKey } = await loadModules(true);
+
+ await checkApiKey(orgRequest(), { organizationId: "org_a" });
+ await checkApiKey(orgRequest(), { organizationId: "org_a" });
+
+ expect(consumeRateLimitForIdentity).toHaveBeenCalledTimes(2);
+ });
+
+ it("reports the memoized decision on every resolution", async () => {
+ const { checkApiKey } = await loadModules(true);
+ const req = orgRequest();
+
+ const first = await checkApiKey(req, { organizationId: "org_a" });
+ const second = await checkApiKey(req, { organizationId: "org_a" });
+
+ expect(first.rateLimit).toEqual(decision);
+ expect(second.rateLimit).toEqual(decision);
+ });
+
+ it("does not charge again for the call the MCP gate already paid for", async () => {
+ const { checkApiKey, registerBearerHandoff, releaseBearerHandoff } = await loadModules(true);
+ const nonce = registerBearerHandoff("rb_org_key", {
+ status: "valid",
+ organizationId: "org_a",
+ statements: null,
+ rateLimit: decision,
+ });
+
+ const req = orgRequest({ [INTERNAL_BEARER_HANDOFF_HEADER]: nonce });
+ const result = await checkApiKey(req, { organizationId: "org_a" });
+ // The handler resolving the credential again must not turn into a charge.
+ await checkApiKey(req, { organizationId: "org_a" });
+
+ expect(consumeRateLimitForIdentity).not.toHaveBeenCalled();
+ expect(result.rateLimit).toEqual(decision);
+ releaseBearerHandoff(nonce);
+ });
+
+ it("charges the second injected request of a batched MCP call", async () => {
+ const { checkApiKey, registerBearerHandoff, releaseBearerHandoff } = await loadModules(true);
+ const nonce = registerBearerHandoff("rb_org_key", {
+ status: "valid",
+ organizationId: "org_a",
+ statements: null,
+ rateLimit: decision,
+ });
+
+ // Every tool call in one JSON-RPC batch reuses the same nonce, but each is
+ // its own injected request; only the first rides on the gate's charge.
+ await checkApiKey(orgRequest({ [INTERNAL_BEARER_HANDOFF_HEADER]: nonce }), { organizationId: "org_a" });
+ await checkApiKey(orgRequest({ [INTERNAL_BEARER_HANDOFF_HEADER]: nonce }), { organizationId: "org_a" });
+ await checkApiKey(orgRequest({ [INTERNAL_BEARER_HANDOFF_HEADER]: nonce }), { organizationId: "org_a" });
+
+ expect(consumeRateLimitForIdentity).toHaveBeenCalledTimes(2);
+ releaseBearerHandoff(nonce);
+ });
+
+ it("does not meter self-hosted instances at all", async () => {
+ const { checkApiKey } = await loadModules(false);
+
+ const result = await checkApiKey(orgRequest(), { organizationId: "org_a" });
+
+ // Self-hosted has no plans and must not take a Redis dependency on the
+ // authentication path.
+ expect(consumeRateLimitForIdentity).not.toHaveBeenCalled();
+ expect(result.valid).toBe(true);
+ expect(result.rateLimit).toBeUndefined();
+ });
+});
diff --git a/server/src/lib/apiRateLimitPolicy.ts b/server/src/lib/apiRateLimitPolicy.ts
new file mode 100644
index 000000000..513e0faa1
--- /dev/null
+++ b/server/src/lib/apiRateLimitPolicy.ts
@@ -0,0 +1,115 @@
+import { eq } from "drizzle-orm";
+import NodeCache from "node-cache";
+import { db } from "../db/postgres/postgres.js";
+import { member } from "../db/postgres/schema.js";
+import { consumeApiRateLimit, dailyLimitForPlan, type RateLimitDecision } from "./apiRateLimit.js";
+import { IS_CLOUD, PRO_API_DAILY_LIMIT } from "./const.js";
+import { createServiceLogger } from "./logger/logger.js";
+
+const logger = createServiceLogger("api-rate-limit");
+
+// Plans are resolved per request rather than stamped onto the key at creation,
+// which is what makes an upgrade take effect on keys that already exist. The
+// cache keeps that to one lookup per owner per minute; a plan change is visible
+// within the TTL.
+const PLAN_CACHE_TTL_SECONDS = 60;
+const planCache = new NodeCache({ stdTTL: PLAN_CACHE_TTL_SECONDS, checkperiod: 120 });
+
+// Last known good limit per owner, kept beyond the cache TTL. A lookup failure
+// falls back to this rather than to a fixed guess, so a Stripe or database blip
+// neither throttles a Pro customer nor promotes a Standard one.
+const lastKnownLimit = new Map<string, number>();
+const MAX_REMEMBERED_OWNERS = 50_000;
+
+async function dailyLimitForOrganization(organizationId: string): Promise<number> {
+ const { getSubscriptionInner } = await import("../api/stripe/getSubscription.js");
+ const subscription = await getSubscriptionInner(organizationId);
+ return dailyLimitForPlan(subscription?.planName);
+}
+
+/**
+ * A user in several organizations gets the most generous of their plans: the
+ * alternative would throttle a Pro customer because they also sit in someone
+ * else's free org. Every membership is considered β€” sampling a subset would
+ * make the answer depend on row order, so a Pro customer's quota could silently
+ * depend on which organizations happened to come back first.
+ */
+async function dailyLimitForUser(userId: string): Promise<number> {
+ const memberships = await db
+ .select({ organizationId: member.organizationId })
+ .from(member)
+ .where(eq(member.userId, userId));
+
+ if (memberships.length === 0) {
+ return dailyLimitForPlan(null);
+ }
+
+ const limits = await Promise.all(memberships.map(row => dailyLimitForOrganization(row.organizationId)));
+ return Math.max(...limits);
+}
+
+function rememberLimit(cacheKey: string, limit: number): void {
+ if (lastKnownLimit.size >= MAX_REMEMBERED_OWNERS && !lastKnownLimit.has(cacheKey)) {
+ // Map iteration is insertion-ordered, so this drops the oldest entry.
+ const oldest = lastKnownLimit.keys().next();
+ if (!oldest.done) {
+ lastKnownLimit.delete(oldest.value);
+ }
+ }
+ lastKnownLimit.set(cacheKey, limit);
+}
+
+/**
+ * The daily quota that applies to a credential, cached per owner.
+ *
+ * A lookup failure reuses this owner's last known quota, and only falls back to
+ * the Pro quota when there is none: a Stripe or database blip should not
+ * throttle a paying customer, but it also should not hand every Standard owner
+ * five times their budget. The burst tier β€” the one that actually protects the
+ * database β€” does not depend on plan resolution either way.
+ */
+export async function resolveDailyLimit(identity: { userId?: string; organizationId?: string }): Promise<number> {
+ if (!IS_CLOUD) {
+ return 0;
+ }
+ const cacheKey = identity.organizationId ? `org:${identity.organizationId}` : `user:${identity.userId}`;
+ const cached = planCache.get<number>(cacheKey);
+ if (cached !== undefined) {
+ return cached;
+ }
+
+ let limit: number;
+ try {
+ limit = identity.organizationId
+ ? await dailyLimitForOrganization(identity.organizationId)
+ : await dailyLimitForUser(identity.userId!);
+ rememberLimit(cacheKey, limit);
+ } catch (error) {
+ limit = lastKnownLimit.get(cacheKey) ?? PRO_API_DAILY_LIMIT;
+ logger.warn({ err: error, cacheKey, limit }, "Plan lookup failed for rate limit; using last known quota");
+ }
+
+ planCache.set(cacheKey, limit);
+ return limit;
+}
+
+/** Drop a cached plan so a subscription change applies immediately. */
+export function invalidateRateLimitPlanCache(ownerId: string): void {
+ planCache.del([`org:${ownerId}`, `user:${ownerId}`]);
+ lastKnownLimit.delete(`org:${ownerId}`);
+ lastKnownLimit.delete(`user:${ownerId}`);
+}
+
+/**
+ * Resolve the owner's quota and charge one request against it. Wired into the
+ * bearer resolver, so it runs exactly once per credential verification β€” the
+ * MCP proxy's handoff reuses that result rather than charging a second time.
+ */
+export async function consumeRateLimitForIdentity(identity: {
+ userId?: string;
+ organizationId?: string;
+}): Promise<RateLimitDecision> {
+ const ownerId = identity.organizationId ?? identity.userId!;
+ const dailyLimit = await resolveDailyLimit(identity);
+ return consumeApiRateLimit(ownerId, dailyLimit);
+}
diff --git a/server/src/lib/auth-middleware.test.ts b/server/src/lib/auth-middleware.test.ts
index a4bb75acd..5042deb86 100644
--- a/server/src/lib/auth-middleware.test.ts
+++ b/server/src/lib/auth-middleware.test.ts
@@ -194,3 +194,99 @@ describe("auth middleware scope enforcement", () => {
expect(response.statusCode).toBe(429);
});
});
+
+describe("auth middleware rate limit reporting", () => {
+ let app: FastifyInstance;
+
+ const limit = (overrides: Record<string, unknown> = {}) => ({
+ allowed: true,
+ wouldHaveDenied: false,
+ scope: null,
+ burstLimit: 50,
+ burstRemaining: 40,
+ burstResetSeconds: 2,
+ dailyLimit: 5000,
+ dailyRemaining: 4000,
+ dailyResetSeconds: 3600,
+ retryAfterSeconds: 0,
+ ...overrides,
+ });
+
+ beforeEach(async () => {
+ vi.clearAllMocks();
+ mocks.getSessionFromReq.mockResolvedValue(null);
+ mocks.getUserHasAccessToSite.mockResolvedValue(false);
+ mocks.getIsUserAdmin.mockResolvedValue(false);
+
+ app = Fastify();
+ app.get("/sites/:siteId/goals", { preHandler: [requireSiteAccess()] as any }, async () => ({ ok: true }));
+ await app.ready();
+ });
+
+ afterEach(async () => {
+ await app.close();
+ });
+
+ it("reports the remaining budget on a successful request", async () => {
+ mocks.checkApiKey.mockResolvedValue({ ...bearerResult(null), rateLimit: limit() });
+
+ const response = await app.inject({ method: "GET", url: "/sites/5/goals", headers: bearer });
+
+ expect(response.statusCode).toBe(200);
+ expect(response.headers["x-ratelimit-burst-remaining"]).toBe("40");
+ expect(response.headers["x-ratelimit-daily-limit"]).toBe("5000");
+ expect(response.headers["x-ratelimit-daily-remaining"]).toBe("4000");
+ });
+
+ it("points RateLimit-* at whichever tier is closest to exhaustion", async () => {
+ // 100/5000 daily left vs 40/50 burst: daily is the tier a client needs to
+ // pace itself against.
+ mocks.checkApiKey.mockResolvedValue({ ...bearerResult(null), rateLimit: limit({ dailyRemaining: 100 }) });
+
+ const response = await app.inject({ method: "GET", url: "/sites/5/goals", headers: bearer });
+
+ expect(response.headers["ratelimit-limit"]).toBe("5000");
+ expect(response.headers["ratelimit-remaining"]).toBe("100");
+ expect(response.headers["ratelimit-reset"]).toBe("3600");
+ });
+
+ it("names the tier and the wait on a daily rejection", async () => {
+ mocks.checkApiKey.mockResolvedValue({
+ valid: false,
+ role: null,
+ rateLimited: true,
+ statements: null,
+ rateLimit: limit({ allowed: false, scope: "daily", dailyRemaining: 0, retryAfterSeconds: 3600 }),
+ });
+
+ const response = await app.inject({ method: "GET", url: "/sites/5/goals", headers: bearer });
+
+ expect(response.statusCode).toBe(429);
+ expect(response.headers["retry-after"]).toBe("3600");
+ expect(response.json()).toMatchObject({ scope: "daily", limit: 5000, retryAfter: 3600 });
+ });
+
+ it("omits the daily headers when the quota is unlimited", async () => {
+ mocks.checkApiKey.mockResolvedValue({
+ ...bearerResult(null),
+ rateLimit: limit({ dailyLimit: 0, dailyRemaining: 0 }),
+ });
+
+ const response = await app.inject({ method: "GET", url: "/sites/5/goals", headers: bearer });
+
+ // Self-hosted has no quota; advertising "0 remaining" would read as blocked.
+ expect(response.headers["x-ratelimit-daily-limit"]).toBeUndefined();
+ expect(response.headers["ratelimit-limit"]).toBe("50");
+ });
+
+ it("sends no rate limit headers for session-authenticated requests", async () => {
+ mocks.checkApiKey.mockResolvedValue(invalidResult);
+ mocks.getUserHasAccessToSite.mockResolvedValue(true);
+ mocks.getSessionFromReq.mockResolvedValue({ user: { id: "user_1" } });
+
+ const response = await app.inject({ method: "GET", url: "/sites/5/goals" });
+
+ expect(response.statusCode).toBe(200);
+ expect(response.headers["ratelimit-limit"]).toBeUndefined();
+ });
+});
diff --git a/server/src/lib/auth-middleware.ts b/server/src/lib/auth-middleware.ts
index dcbec681b..6325130ba 100644
--- a/server/src/lib/auth-middleware.ts
+++ b/server/src/lib/auth-middleware.ts
@@ -51,11 +51,68 @@ const getOrganizationIdFromParams = (request: FastifyRequest): string | undefine
return params?.organizationId;
};
+/**
+ * Report the remaining budget on every bearer-authenticated response, not just
+ * on rejections β€” a client can only pace itself if it can see the budget before
+ * it runs out. `RateLimit-*` describes whichever tier is closest to exhaustion
+ * (per the IETF draft); the per-tier `X-RateLimit-*` headers always describe
+ * both, so a client never has to guess which one it just read.
+ */
+const applyRateLimitHeaders = (reply: FastifyReply, apiKeyResult: BearerAuthResult) => {
+ const limit = apiKeyResult.rateLimit;
+ if (!limit) {
+ return;
+ }
+
+ reply.header("X-RateLimit-Burst-Limit", limit.burstLimit);
+ reply.header("X-RateLimit-Burst-Remaining", limit.burstRemaining);
+ reply.header("X-RateLimit-Burst-Reset", limit.burstResetSeconds);
+
+ const dailyEnabled = limit.dailyLimit > 0;
+ if (dailyEnabled) {
+ reply.header("X-RateLimit-Daily-Limit", limit.dailyLimit);
+ reply.header("X-RateLimit-Daily-Remaining", limit.dailyRemaining);
+ reply.header("X-RateLimit-Daily-Reset", limit.dailyResetSeconds);
+ }
+
+ // When the limiter named a binding tier, report that one β€” otherwise a
+ // request denied on the daily quota (both tiers at zero, so neither ratio is
+ // smaller) would advertise a 10-second reset next to a Retry-After of hours.
+ const dailyIsTighter = limit.scope
+ ? limit.scope === "daily"
+ : dailyEnabled && limit.dailyRemaining / limit.dailyLimit < limit.burstRemaining / limit.burstLimit;
+ reply.header("RateLimit-Limit", dailyIsTighter ? limit.dailyLimit : limit.burstLimit);
+ reply.header("RateLimit-Remaining", dailyIsTighter ? limit.dailyRemaining : limit.burstRemaining);
+ reply.header("RateLimit-Reset", dailyIsTighter ? limit.dailyResetSeconds : limit.burstResetSeconds);
+};
+
+const sendRateLimited = (reply: FastifyReply, apiKeyResult: BearerAuthResult) => {
+ const limit = apiKeyResult.rateLimit;
+ applyRateLimitHeaders(reply, apiKeyResult);
+ if (limit) {
+ reply.header("Retry-After", limit.retryAfterSeconds);
+ }
+ return reply.status(429).send({
+ error: "Rate limit exceeded",
+ // Naming the tier is the difference between "back off for two seconds" and
+ // "you are done until tomorrow" β€” a client cannot tell them apart from a
+ // bare 429.
+ ...(limit?.scope
+ ? {
+ scope: limit.scope,
+ limit: limit.scope === "daily" ? limit.dailyLimit : limit.burstLimit,
+ retryAfter: limit.retryAfterSeconds,
+ }
+ : {}),
+ });
+};
+
// Attach the authenticated bearer principal. User keys become request.user
// like a session; org keys have no user (handlers that attribute a creator
// record null) β€” they set apiKeyOrganizationId instead, which the site-access
// resolver (getSitesUserHasAccessTo) maps to the org's full site set.
-const attachApiKeyUser = (request: FastifyRequest, apiKeyResult: BearerAuthResult) => {
+const attachApiKeyUser = (request: FastifyRequest, reply: FastifyReply, apiKeyResult: BearerAuthResult) => {
+ applyRateLimitHeaders(reply, apiKeyResult);
if (apiKeyResult.userId) {
request.user = { id: apiKeyResult.userId };
} else if (apiKeyResult.organizationId) {
@@ -99,12 +156,12 @@ export function requireAuth(scope?: RouteScope): AuthMiddleware {
if (!bearerScopeOk(apiKeyResult, scope)) {
return sendInsufficientScope(reply, scope!);
}
- attachApiKeyUser(request, apiKeyResult);
+ attachApiKeyUser(request, reply, apiKeyResult);
return;
}
if (apiKeyResult.rateLimited) {
- return reply.status(429).send({ error: "Rate limit exceeded" });
+ return sendRateLimited(reply, apiKeyResult);
}
return reply.status(401).send({ error: "Unauthorized" });
@@ -138,7 +195,7 @@ export function requireSiteAccess(scope?: RouteScope): AuthMiddleware {
const apiKeyResult = await checkApiKey(request, { siteId });
if (apiKeyResult.valid) {
if (bearerScopeOk(apiKeyResult, scope)) {
- attachApiKeyUser(request, apiKeyResult);
+ attachApiKeyUser(request, reply, apiKeyResult);
return;
}
scopeDenied = true;
@@ -153,7 +210,7 @@ export function requireSiteAccess(scope?: RouteScope): AuthMiddleware {
}
if (apiKeyResult.rateLimited) {
- return reply.status(429).send({ error: "Rate limit exceeded" });
+ return sendRateLimited(reply, apiKeyResult);
}
if (scopeDenied) {
return sendInsufficientScope(reply, scope!);
@@ -178,7 +235,7 @@ export function requireSiteAdminAccess(scope?: RouteScope): AuthMiddleware {
const apiKeyResult = await checkApiKey(request, { siteId });
if (apiKeyResult.valid && (apiKeyResult.role === "admin" || apiKeyResult.role === "owner")) {
if (bearerScopeOk(apiKeyResult, scope)) {
- attachApiKeyUser(request, apiKeyResult);
+ attachApiKeyUser(request, reply, apiKeyResult);
return;
}
scopeDenied = true;
@@ -202,7 +259,7 @@ export function requireSiteAdminAccess(scope?: RouteScope): AuthMiddleware {
}
if (apiKeyResult.rateLimited) {
- return reply.status(429).send({ error: "Rate limit exceeded" });
+ return sendRateLimited(reply, apiKeyResult);
}
if (scopeDenied) {
return sendInsufficientScope(reply, scope!);
@@ -227,7 +284,7 @@ export function allowPublicSiteAccess(scope?: RouteScope): AuthMiddleware {
const apiKeyResult = await checkApiKey(request, { siteId });
if (apiKeyResult.valid) {
if (bearerScopeOk(apiKeyResult, scope)) {
- attachApiKeyUser(request, apiKeyResult);
+ attachApiKeyUser(request, reply, apiKeyResult);
return;
}
scopeDenied = true;
@@ -244,7 +301,7 @@ export function allowPublicSiteAccess(scope?: RouteScope): AuthMiddleware {
}
if (apiKeyResult.rateLimited) {
- return reply.status(429).send({ error: "Rate limit exceeded" });
+ return sendRateLimited(reply, apiKeyResult);
}
if (scopeDenied) {
return sendInsufficientScope(reply, scope!);
@@ -270,7 +327,7 @@ export function requireOrgMember(scope?: RouteScope): AuthMiddleware {
const apiKeyResult = await checkApiKey(request, { organizationId });
if (apiKeyResult.valid) {
if (bearerScopeOk(apiKeyResult, scope)) {
- attachApiKeyUser(request, apiKeyResult);
+ attachApiKeyUser(request, reply, apiKeyResult);
return;
}
scopeDenied = true;
@@ -284,7 +341,7 @@ export function requireOrgMember(scope?: RouteScope): AuthMiddleware {
}
if (apiKeyResult.rateLimited) {
- return reply.status(429).send({ error: "Rate limit exceeded" });
+ return sendRateLimited(reply, apiKeyResult);
}
if (scopeDenied) {
return sendInsufficientScope(reply, scope!);
@@ -313,7 +370,7 @@ export function requireOrgAdminFromParams(scope?: RouteScope): AuthMiddleware {
const apiKeyResult = await checkApiKey(request, { organizationId });
if (apiKeyResult.valid && (apiKeyResult.role === "admin" || apiKeyResult.role === "owner")) {
if (bearerScopeOk(apiKeyResult, scope)) {
- attachApiKeyUser(request, apiKeyResult);
+ attachApiKeyUser(request, reply, apiKeyResult);
return;
}
scopeDenied = true;
@@ -323,7 +380,7 @@ export function requireOrgAdminFromParams(scope?: RouteScope): AuthMiddleware {
const session = await getSessionFromReq(request);
if (!session?.user?.id) {
if (apiKeyResult.rateLimited) {
- return reply.status(429).send({ error: "Rate limit exceeded" });
+ return sendRateLimited(reply, apiKeyResult);
}
if (scopeDenied) {
return sendInsufficientScope(reply, scope!);
diff --git a/server/src/lib/auth-utils.test.ts b/server/src/lib/auth-utils.test.ts
index b41b31802..5a9333cb4 100644
--- a/server/src/lib/auth-utils.test.ts
+++ b/server/src/lib/auth-utils.test.ts
@@ -13,6 +13,25 @@ vi.mock("./auth.js", () => ({
},
}));
+// The bearer resolver charges every verification against the rate limiter,
+// which would reach for Redis (and a plan lookup) on each of these tests. Stub
+// it out β€” the limiter has its own tests, and these are about scope carrying
+// and org resolution.
+vi.mock("./apiRateLimitPolicy.js", () => ({
+ consumeRateLimitForIdentity: vi.fn(async () => ({
+ allowed: true,
+ wouldHaveDenied: false,
+ scope: null,
+ burstLimit: 50,
+ burstRemaining: 49,
+ burstResetSeconds: 1,
+ dailyLimit: 5_000,
+ dailyRemaining: 4_999,
+ dailyResetSeconds: 3_600,
+ retryAfterSeconds: 0,
+ })),
+}));
+
// Replace the postgres-js connection with an in-memory PGlite database so the
// real drizzle queries in auth-utils run against real SQL.
vi.mock("../db/postgres/postgres.js", async () => {
diff --git a/server/src/lib/auth-utils.ts b/server/src/lib/auth-utils.ts
index 112702b81..10a6d9ad8 100644
--- a/server/src/lib/auth-utils.ts
+++ b/server/src/lib/auth-utils.ts
@@ -3,7 +3,10 @@ import { FastifyRequest } from "fastify";
import NodeCache from "node-cache";
import { db } from "../db/postgres/postgres.js";
import { member, memberSiteAccess, sites, user, team, teamMember, teamSiteAccess } from "../db/postgres/schema.js";
+import type { RateLimitDecision } from "./apiRateLimit.js";
+import { consumeRateLimitForIdentity } from "./apiRateLimitPolicy.js";
import { auth } from "./auth.js";
+import { IS_CLOUD } from "./const.js";
import {
consumeBearerHandoff,
extractBearerToken,
@@ -21,6 +24,56 @@ const bearerResolverDeps: BearerResolverDeps = {
getOAuthSession: token => auth.api.getMcpSession({ headers: new Headers({ authorization: `Bearer ${token}` }) }),
};
+// Several guards resolve the same credential more than once per HTTP request:
+// a guard runs checkApiKey and then its session fallback (or the handler's
+// getUserIdFromRequest) runs it again. Budget is denominated in API requests,
+// not in internal resolutions, so the charge is memoized on the request object
+// and every later resolution reuses that one decision.
+const REQUEST_RATE_LIMIT = Symbol.for("rybbit.rateLimitDecision");
+
+type RateLimitedRequest = FastifyRequest & { [REQUEST_RATE_LIMIT]?: RateLimitDecision };
+
+function getRequestRateLimit(req: FastifyRequest): RateLimitDecision | undefined {
+ return (req as RateLimitedRequest)[REQUEST_RATE_LIMIT];
+}
+
+function setRequestRateLimit(req: FastifyRequest, decision: RateLimitDecision): void {
+ (req as RateLimitedRequest)[REQUEST_RATE_LIMIT] = decision;
+}
+
+/**
+ * Whether this request was refused by the rate limiter. For handlers that
+ * resolve credentials without a guard and would otherwise report a throttled
+ * request as unauthenticated.
+ */
+export function wasRateLimited(req: FastifyRequest): RateLimitDecision | undefined {
+ const decision = getRequestRateLimit(req);
+ return decision && !decision.allowed ? decision : undefined;
+}
+
+/**
+ * Per-request resolver dependencies. Rate limiting is cloud-only: self-hosted
+ * instances have no plans, no shared infrastructure to protect, and must not
+ * gain a Redis dependency on the authentication path.
+ */
+function resolverDepsFor(req: FastifyRequest): BearerResolverDeps {
+ if (!IS_CLOUD) {
+ return bearerResolverDeps;
+ }
+ return {
+ ...bearerResolverDeps,
+ consumeRateLimit: async identity => {
+ const memoized = getRequestRateLimit(req);
+ if (memoized) {
+ return memoized;
+ }
+ const decision = await consumeRateLimitForIdentity(identity);
+ setRequestRateLimit(req, decision);
+ return decision;
+ },
+ };
+}
+
function resolveBearerTokenFromRequest(req: FastifyRequest): string | null {
// Priority: Authorization: Bearer header (recommended), then ?api_key= (testing).
const bearerToken = extractBearerToken(req.headers["authorization"]);
@@ -362,6 +415,8 @@ export interface BearerAuthResult {
/** Set instead of userId when the credential is an organization-owned key. */
organizationId?: string;
rateLimited?: boolean;
+ /** Budget state for this request, when a bearer credential was resolved. */
+ rateLimit?: RateLimitDecision;
/**
* Scope statements carried by the credential. null = unrestricted (legacy
* key with no permissions, or OAuth token with no custom scopes). Guards
@@ -385,13 +440,17 @@ export async function checkApiKey(
}
// Reuse the MCP gate's verification when this is an in-process proxy call, so
- // a tool call doesn't verify (and rate-limit) the key a second time.
- const identity =
- consumeBearerHandoff(req.headers[INTERNAL_BEARER_HANDOFF_HEADER], apiKey) ??
- (await resolveBearerIdentity(apiKey, bearerResolverDeps));
+ // a tool call doesn't verify (and rate-limit) the key a second time. The
+ // gate's charge covers this call; recording it here keeps a second resolution
+ // within the same request from charging again.
+ const handoffIdentity = consumeBearerHandoff(req.headers[INTERNAL_BEARER_HANDOFF_HEADER], apiKey);
+ if (handoffIdentity?.rateLimit) {
+ setRequestRateLimit(req, handoffIdentity.rateLimit);
+ }
+ const identity = handoffIdentity ?? (await resolveBearerIdentity(apiKey, resolverDepsFor(req)));
if (identity.status === "rate_limited") {
- return { valid: false, role: null, rateLimited: true, statements: null };
+ return { valid: false, role: null, rateLimited: true, rateLimit: identity.rateLimit, statements: null };
}
if (identity.status === "valid" && identity.organizationId) {
// Organization-owned key: valid only against its own organization (or a
@@ -403,14 +462,15 @@ export async function checkApiKey(
valid: true,
role: "admin",
organizationId: identity.organizationId,
+ rateLimit: identity.rateLimit,
statements: identity.statements,
};
}
- return { valid: false, role: null, statements: null };
+ return { valid: false, role: null, rateLimit: identity.rateLimit, statements: null };
}
if (identity.status === "valid" && identity.userId) {
const membership = await resolveBearerUserOrgRole(identity.userId, options);
- return { ...membership, statements: identity.statements };
+ return { ...membership, rateLimit: identity.rateLimit, statements: identity.statements };
}
return { valid: false, role: null, statements: null };
}
diff --git a/server/src/lib/auth.ts b/server/src/lib/auth.ts
index de4229da7..98169c180 100644
--- a/server/src/lib/auth.ts
+++ b/server/src/lib/auth.ts
@@ -16,7 +16,7 @@ import { invitation, member, memberSiteAccess, sites, user } from "../db/postgre
import { apiKeyLimitForPlan, countApiKeysForReference } from "./apiKeyLimits.js";
import { invalidateSitesAccessCache } from "./auth-utils.js";
import { ORG_API_KEY_CONFIG_ID } from "./bearerAuth.js";
-import { API_RATE_LIMIT_WINDOW, DISABLE_SIGNUP, IS_CLOUD, STANDARD_API_RATE_LIMIT } from "./const.js";
+import { DISABLE_SIGNUP, IS_CLOUD } from "./const.js";
import {
addContactToAudience,
sendChangeEmailVerification,
@@ -48,14 +48,16 @@ const orgRoles = {
member: orgAccessControl.newRole({ ...memberAc.statements }),
};
-// Default per-key rate limits; the create endpoints override them per plan.
-const apiKeyRateLimit = IS_CLOUD
- ? {
- enabled: true,
- timeWindow: API_RATE_LIMIT_WINDOW,
- maxRequests: STANDARD_API_RATE_LIMIT,
- }
- : { maxRequests: 10000, timeWindow: 86400000 };
+// Rate limiting moved out of the plugin and into lib/apiRateLimit.ts, which
+// enforces a burst tier and a daily quota per credential *owner* rather than a
+// fixed window per key β€” the plugin's limiter is keyed on the key row, so an
+// org could multiply its budget by minting more keys.
+//
+// Disabling it drops the read-modify-write on `requestCount`, but not every
+// write: the plugin still stamps `lastRequest` on each verification (it takes
+// the "skip" branch with a fresh timestamp), which is also what makes key
+// last-used times work.
+const apiKeyRateLimit = { enabled: false };
const pluginList = [
admin(),
diff --git a/server/src/lib/bearerAuth.test.ts b/server/src/lib/bearerAuth.test.ts
index 29b31f739..0b34ce0e5 100644
--- a/server/src/lib/bearerAuth.test.ts
+++ b/server/src/lib/bearerAuth.test.ts
@@ -1,4 +1,5 @@
import { describe, expect, it, vi } from "vitest";
+import type { RateLimitDecision } from "./apiRateLimit.js";
import {
consumeBearerHandoff,
extractBearerToken,
@@ -86,6 +87,80 @@ describe("resolveBearerIdentity", () => {
});
});
+describe("resolveBearerIdentity rate limiting", () => {
+ const decision = (overrides: Partial<RateLimitDecision> = {}): RateLimitDecision => ({
+ allowed: true,
+ wouldHaveDenied: false,
+ scope: null,
+ burstLimit: 50,
+ burstRemaining: 49,
+ burstResetSeconds: 1,
+ dailyLimit: 5000,
+ dailyRemaining: 4999,
+ dailyResetSeconds: 3600,
+ retryAfterSeconds: 0,
+ ...overrides,
+ });
+
+ it("charges the organization for an org-owned key, not the key itself", async () => {
+ const consumeRateLimit = vi.fn(async () => decision());
+ const identity = await resolveBearerIdentity(
+ "k",
+ deps({
+ verifyApiKey: async () => ({ valid: true, key: { referenceId: "org1", permissions: null, configId: "org" } }),
+ consumeRateLimit,
+ })
+ );
+
+ expect(consumeRateLimit).toHaveBeenCalledWith({ userId: undefined, organizationId: "org1" });
+ expect(identity.status).toBe("valid");
+ expect(identity.rateLimit?.dailyRemaining).toBe(4999);
+ });
+
+ it("charges OAuth access tokens on the same budget as API keys", async () => {
+ const consumeRateLimit = vi.fn(async () => decision());
+ const identity = await resolveBearerIdentity(
+ "k",
+ deps({ getOAuthSession: async () => ({ userId: "u1", accessTokenExpiresAt: future() }), consumeRateLimit })
+ );
+
+ expect(consumeRateLimit).toHaveBeenCalledWith({ userId: "u1", organizationId: undefined });
+ expect(identity.status).toBe("valid");
+ });
+
+ it("rejects a denied request and carries the retry-after through", async () => {
+ const identity = await resolveBearerIdentity(
+ "k",
+ deps({
+ verifyApiKey: async () => ({ valid: true, key: { referenceId: "u1", permissions: null } }),
+ consumeRateLimit: async () =>
+ decision({ allowed: false, wouldHaveDenied: true, scope: "daily", retryAfterSeconds: 3600 }),
+ })
+ );
+
+ expect(identity.status).toBe("rate_limited");
+ expect(identity.userId).toBeUndefined();
+ expect(identity.rateLimit?.scope).toBe("daily");
+ expect(identity.rateLimit?.retryAfterSeconds).toBe(3600);
+ });
+
+ it("admits the request when the limiter itself fails", async () => {
+ const identity = await resolveBearerIdentity(
+ "k",
+ deps({
+ verifyApiKey: async () => ({ valid: true, key: { referenceId: "u1", permissions: null } }),
+ consumeRateLimit: async () => {
+ throw new Error("redis down");
+ },
+ })
+ );
+
+ // A broken limiter must not lock out valid credentials.
+ expect(identity.status).toBe("valid");
+ expect(identity.rateLimit).toBeUndefined();
+ });
+});
+
describe("bearer handoff", () => {
it("returns the identity for a matching nonce and token", () => {
const identity = { status: "valid" as const, userId: "u1", statements: null };
@@ -110,4 +185,17 @@ describe("bearer handoff", () => {
releaseBearerHandoff(nonce);
expect(consumeBearerHandoff(nonce, "tok")).toBeNull();
});
+
+ it("covers only one call, so a JSON-RPC batch cannot ride on one charge", () => {
+ const identity = { status: "valid" as const, userId: "u1", statements: null };
+ const nonce = registerBearerHandoff("tok", identity);
+
+ expect(consumeBearerHandoff(nonce, "tok")).toBe(identity);
+ // A batched MCP request reuses one nonce for every tool call; the rest must
+ // fall through to real verification so they are charged.
+ expect(consumeBearerHandoff(nonce, "tok")).toBeNull();
+ expect(consumeBearerHandoff(nonce, "tok")).toBeNull();
+
+ releaseBearerHandoff(nonce);
+ });
});
diff --git a/server/src/lib/bearerAuth.ts b/server/src/lib/bearerAuth.ts
index fb34f6573..7195a07c7 100644
--- a/server/src/lib/bearerAuth.ts
+++ b/server/src/lib/bearerAuth.ts
@@ -1,4 +1,5 @@
import { randomUUID } from "node:crypto";
+import type { RateLimitDecision } from "./apiRateLimit.js";
import { parseOAuthScopes, statementsFromApiKeyPermissions, type ScopeStatements } from "./scopes.js";
/**
@@ -40,6 +41,16 @@ export type OAuthTokenLookup = {
export interface BearerResolverDeps {
verifyApiKey: (token: string) => Promise<ApiKeyVerification>;
getOAuthSession: (token: string) => Promise<OAuthTokenLookup>;
+ /**
+ * Charge one request against the owner's burst bucket and daily quota.
+ * Optional so tests and the MCP layer can resolve identities without a
+ * limiter; when absent, no request is charged. Returning null means the
+ * deployment is not metered (self-hosted), which is not a denial.
+ */
+ consumeRateLimit?: (identity: {
+ userId?: string;
+ organizationId?: string;
+ }) => Promise<RateLimitDecision | null>;
}
export type BearerIdentityStatus = "valid" | "invalid" | "rate_limited" | "verify_error";
@@ -53,6 +64,12 @@ export interface BearerIdentity {
organizationId?: string;
/** null = unrestricted (legacy key / full OAuth grant); enforced by callers. */
statements: ScopeStatements | null;
+ /**
+ * The rate-limit outcome for this request, carried so callers can report the
+ * remaining budget in response headers. Present on rate_limited identities
+ * too β€” that is where the retry-after comes from.
+ */
+ rateLimit?: RateLimitDecision;
}
export function isUsableOAuthToken(token: OAuthTokenLookup): token is NonNullable<OAuthTokenLookup> {
@@ -69,6 +86,30 @@ export function isUsableOAuthToken(token: OAuthTokenLookup): token is NonNullabl
* cheap DB query the caller does per route, and it never touches the rate
* limiter, so it does not need deduplicating.
*/
+/**
+ * Charge a resolved identity against its owner's budget, converting a denial
+ * into a rate_limited result. A limiter failure is never fatal: the identity
+ * passes through uncharged rather than locking out a valid credential.
+ */
+async function applyRateLimit(identity: BearerIdentity, deps: BearerResolverDeps): Promise<BearerIdentity> {
+ if (!deps.consumeRateLimit) {
+ return identity;
+ }
+ let decision: RateLimitDecision | null;
+ try {
+ decision = await deps.consumeRateLimit({ userId: identity.userId, organizationId: identity.organizationId });
+ } catch {
+ return identity;
+ }
+ if (!decision) {
+ return identity;
+ }
+ if (!decision.allowed) {
+ return { status: "rate_limited", statements: null, rateLimit: decision };
+ }
+ return { ...identity, rateLimit: decision };
+}
+
export async function resolveBearerIdentity(token: string, deps: BearerResolverDeps): Promise<BearerIdentity> {
let verifyError = false;
let verification: ApiKeyVerification | null = null;
@@ -83,9 +124,9 @@ export async function resolveBearerIdentity(token: string, deps: BearerResolverD
// referenceId is a user id or an organization id depending on which key
// configuration minted the key (legacy keys have a NULL configId = user).
if (verification.key.configId === ORG_API_KEY_CONFIG_ID) {
- return { status: "valid", organizationId: verification.key.referenceId, statements };
+ return applyRateLimit({ status: "valid", organizationId: verification.key.referenceId, statements }, deps);
}
- return { status: "valid", userId: verification.key.referenceId, statements };
+ return applyRateLimit({ status: "valid", userId: verification.key.referenceId, statements }, deps);
}
if (verification?.error?.code === "RATE_LIMITED") {
@@ -102,11 +143,14 @@ export async function resolveBearerIdentity(token: string, deps: BearerResolverD
}
if (isUsableOAuthToken(oauth)) {
- return {
- status: "valid",
- userId: oauth.userId as string,
- statements: parseOAuthScopes(typeof oauth.scopes === "string" ? oauth.scopes : null),
- };
+ return applyRateLimit(
+ {
+ status: "valid",
+ userId: oauth.userId as string,
+ statements: parseOAuthScopes(typeof oauth.scopes === "string" ? oauth.scopes : null),
+ },
+ deps
+ );
}
return { status: verifyError ? "verify_error" : "invalid", statements: null };
@@ -128,12 +172,14 @@ export const INTERNAL_BEARER_HANDOFF_HEADER = "x-rybbit-mcp-bearer";
interface HandoffEntry {
token: string;
identity: BearerIdentity;
+ /** A handoff covers exactly one REST call β€” see consumeBearerHandoff. */
+ spent: boolean;
}
const handoffs = new Map<string, HandoffEntry>();
export function registerBearerHandoff(token: string, identity: BearerIdentity): string {
const nonce = randomUUID();
- handoffs.set(nonce, { token, identity });
+ handoffs.set(nonce, { token, identity, spent: false });
return nonce;
}
@@ -154,5 +200,14 @@ export function consumeBearerHandoff(
if (!entry || entry.token !== token) {
return null;
}
+ // One handoff covers one REST call. The MCP request already paid for that
+ // call at the gate, but a single HTTP request can carry a whole JSON-RPC
+ // batch β€” reusing the nonce for all of them would let a client run any
+ // number of tool calls on one unit of budget. Later calls fall through to
+ // normal verification, which charges them.
+ if (entry.spent) {
+ return null;
+ }
+ entry.spent = true;
return entry.identity;
}
diff --git a/server/src/lib/const.ts b/server/src/lib/const.ts
index e7f1147ad..2e112fa86 100644
--- a/server/src/lib/const.ts
+++ b/server/src/lib/const.ts
@@ -37,10 +37,26 @@ export const BASIC_MEMBER_LIMIT = 1;
export const STANDARD_SITE_LIMIT = 5;
export const STANDARD_MEMBER_LIMIT = 3;
-// API key rate limits per plan (requests per window)
-export const API_RATE_LIMIT_WINDOW = 60_000; // 1 minute
-export const STANDARD_API_RATE_LIMIT = 20; // 20 req/min
-export const PRO_API_RATE_LIMIT = 200; // 200 req/min
+// API rate limits. Two tiers with distinct jobs:
+//
+// burst β€” identical for every plan, because this is the infrastructure guard.
+// It bounds instantaneous request rate per credential owner so no
+// single caller can stampede ClickHouse. A full bucket drains in one
+// spike; it then refills continuously at capacity/window (5 req/s).
+// daily β€” the plan lever, on a UTC calendar day so it resets predictably and
+// reads like the monthly event quota users already understand.
+//
+// Enforced per *owner* (the organization for org keys, the user for user keys),
+// not per key, so minting extra keys cannot multiply an org's budget.
+export const API_BURST_LIMIT = 50; // 50 requests
+export const API_BURST_WINDOW_MS = 10_000; // per 10s => 5 req/s sustained, 50 in one spike
+export const STANDARD_API_DAILY_LIMIT = 5_000;
+export const PRO_API_DAILY_LIMIT = 25_000;
+
+// Count usage and report what would have been blocked, but let every request
+// through. Deploy in this mode first to size the daily limits against real
+// traffic before they start rejecting anyone.
+export const API_RATE_LIMIT_OBSERVE_ONLY = process.env.API_RATE_LIMIT_OBSERVE_ONLY === "true";
// Maximum number of API keys per owner (a user or an organization)
export const STANDARD_API_KEY_LIMIT = 5;
diff --git a/server/src/mcp/auth.ts b/server/src/mcp/auth.ts
index 0353304f5..594dff113 100644
--- a/server/src/mcp/auth.ts
+++ b/server/src/mcp/auth.ts
@@ -24,7 +24,9 @@ export interface McpAuthContext {
export class McpAuthenticationError extends Error {
constructor(
message: string,
- public readonly statusCode: 401 | 429 | 503
+ public readonly statusCode: 401 | 429 | 503,
+ /** Seconds to wait before retrying; drives Retry-After on 429/503. */
+ public readonly retryAfterSeconds?: number
) {
super(message);
this.name = "McpAuthenticationError";
@@ -42,6 +44,15 @@ const defaultDependencies: McpAuthenticatorDependencies = {
const { auth } = await import("../lib/auth.js");
return auth.api.getMcpSession({ headers: new Headers({ authorization: `Bearer ${bearerToken}` }) });
},
+ consumeRateLimit: async identity => {
+ const { IS_CLOUD } = await import("../lib/const.js");
+ // Self-hosted is not metered, and the auth path must not depend on Redis.
+ if (!IS_CLOUD) {
+ return null;
+ }
+ const { consumeRateLimitForIdentity } = await import("../lib/apiRateLimitPolicy.js");
+ return consumeRateLimitForIdentity(identity);
+ },
};
/**
@@ -71,8 +82,19 @@ export function createMcpAuthenticator(dependencies: McpAuthenticatorDependencie
scopes: identity.statements,
identity,
};
- case "rate_limited":
- throw new McpAuthenticationError("API key rate limit exceeded", 429);
+ case "rate_limited": {
+ const limit = identity.rateLimit;
+ // A daily-quota rejection is not retriable for hours; telling a client
+ // to come back in 60s would just have it hammer a closed door.
+ const detail = limit?.scope
+ ? ` (${limit.scope} limit${limit.scope === "daily" ? ` of ${limit.dailyLimit}/day` : ""})`
+ : "";
+ throw new McpAuthenticationError(
+ `API key rate limit exceeded${detail}`,
+ 429,
+ limit?.retryAfterSeconds
+ );
+ }
case "verify_error":
throw new McpAuthenticationError("Rybbit could not verify the API key", 503);
default:
diff --git a/server/src/mcp/index.ts b/server/src/mcp/index.ts
index f1f4bebf4..821fa4e7a 100644
--- a/server/src/mcp/index.ts
+++ b/server/src/mcp/index.ts
@@ -71,7 +71,10 @@ export async function mcpRoutes(fastify: FastifyInstance, options: McpRouteOptio
);
reply.header("Access-Control-Expose-Headers", "WWW-Authenticate");
} else {
- reply.header("Retry-After", error.statusCode === 429 ? "60" : "30");
+ reply.header(
+ "Retry-After",
+ String(error.retryAfterSeconds ?? (error.statusCode === 429 ? 60 : 30))
+ );
}
return reply.status(error.statusCode).send({
jsonrpc: "2.0",