⚡ Project management that doesn't become the project. Boards, Gantt charts, and GitHub integration. Self-host it or use Kaneo Cloud.
TypeScript honoissue-managementissue-trackerjira-alternativekanbanlinear-alternativemcpproject-managementreactself-hostedtypescript
fix(api): answer rate-limited API keys with 429
Andrej6e36ec2ea6d5
diff --git a/apps/api/src/index.ts b/apps/api/src/index.tsindex f9d94f44f..a0c7f8aa3 100644--- a/apps/api/src/index.ts+++ b/apps/api/src/index.ts@@ -71,6 +71,7 @@ import telegramIntegration from "./telegram-integration";import timeEntry from "./time-entry";import user from "./user";import getAvatar from "./user/controllers/get-avatar";+import { apiKeyRejection } from "./utils/api-key-rejection";import { authenticateApiRequest } from "./utils/authenticate-api-request";import {authorizeAssetAccess,@@ -86,7 +87,11 @@ import { normalizeApiServerUrl } from "./utils/openapi-spec";import { seedDefaultWorkspaceRoles } from "./utils/seed-default-workspace-roles";import { drainSignInEmails } from "./utils/sign-in-email-tasks";import { validateWorkspaceAccess } from "./utils/validate-workspace-access";-import { verifyApiKey } from "./utils/verify-api-key";+import {+ type ApiKeyRateLimit,+ rateLimitHeaders,+} from "./utils/rate-limit-headers";+import { readApiKeyRateLimit, verifyApiKey } from "./utils/verify-api-key";import workflowRule from "./workflow-rule";import workspace from "./workspace";import {@@ -126,6 +131,7 @@ type ApiVariables = {userId: string;userEmail: string;apiKey?: ApiKey;+ apiKeyRateLimit?: ApiKeyRateLimit | null;};};@@ -208,6 +214,12 @@ export function createApp() {"*",cors({credentials: true,+ exposeHeaders: [+ "Retry-After",+ "X-RateLimit-Limit",+ "X-RateLimit-Remaining",+ "X-RateLimit-Reset",+ ],origin: (origin) => {// Reflecting an arbitrary origin alongside credentials lets any site// read authenticated responses, so it stays a development convenience.@@ -231,6 +243,15 @@ export function createApp() {const api = new OpenAPIHono<ApiVariables>();+ api.use("*", async (c, next) => {+ await next();+ const rateLimit = c.get("apiKeyRateLimit");+ if (!rateLimit) return;+ for (const [name, value] of Object.entries(rateLimitHeaders(rateLimit))) {+ c.header(name, value);+ }+ });+api.get("/health", (c) => {return c.json({ status: "ok" });});@@ -398,13 +419,11 @@ export function createApp() {api.use("/auth/*", async (c, next) => {const apiKeyHeader = c.req.header("x-api-key")?.trim();- if (- apiKeyHeader &&- !(await verifyApiKey(apiKeyHeader, { consume: false }))- ) {- throw new HTTPException(401, { message: "Unauthorized" });- }- return next();+ if (!apiKeyHeader) return next();+ const apiKeyResult = await verifyApiKey(apiKeyHeader, { consume: false });+ if (apiKeyResult?.status !== "valid") throw apiKeyRejection(apiKeyResult);+ await next();+ c.set("apiKeyRateLimit", await readApiKeyRateLimit(apiKeyHeader));});api.openapi(@@ -564,6 +583,34 @@ export function createApp() {scheme: "bearer",description: "API key or session token (Bearer)",});+ const apiKeyRateLimited = api.openAPIRegistry.registerComponent(+ "responses",+ "ApiKeyRateLimited",+ {+ description:+ "The API key exceeded its rate limit or usage quota. Wait the number of seconds in Retry-After before retrying. The X-RateLimit headers are sent only when the rate limit was hit.",+ headers: {+ "Retry-After": {+ description:+ "Seconds to wait before retrying. Omitted when an exhausted usage quota never refills.",+ schema: { type: "integer" },+ },+ "X-RateLimit-Limit": {+ description: "Requests the API key may make per window.",+ schema: { type: "integer" },+ },+ "X-RateLimit-Remaining": {+ description: "Requests left in the current window.",+ schema: { type: "integer" },+ },+ "X-RateLimit-Reset": {+ description: "Unix time in seconds when the current window resets.",+ schema: { type: "integer" },+ },+ },+ content: { "text/plain": { schema: { type: "string" } } },+ },+ );organizationRoutes(api.openAPIRegistry);api.get("/openapi", (c) => {@@ -587,9 +634,9 @@ export function createApp() {});// Every authenticated route sits behind the same app-wide- // authenticateApiRequest middleware, so the shared 401 is injected here- // rather than repeated on all ~120 route definitions. Routes that opt out- // of auth declare `security: []` and are skipped.+ // authenticateApiRequest middleware, so the shared 401 and 429 are injected+ // here rather than repeated on all ~120 route definitions. Routes that opt+ // out of auth declare `security: []` and are skipped.const httpMethods = ["get","post",@@ -619,6 +666,7 @@ export function createApp() {operation.responses["401"] ??= {description: "Missing or invalid credentials",};+ operation.responses["429"] ??= apiKeyRateLimited.ref;}}@@ -690,14 +738,15 @@ export function createApp() {return auth.handler(new Request(c.req.raw, { headers }));}- if (!(await verifyApiKey(bearerToken, { consume: false }))) {- throw new HTTPException(401, { message: "Unauthorized" });- }+ const apiKeyResult = await verifyApiKey(bearerToken, { consume: false });+ if (apiKeyResult?.status !== "valid") throw apiKeyRejection(apiKeyResult);// Better Auth API key plugin validates from x-api-key by default.headers.set("x-api-key", bearerToken);- return auth.handler(new Request(c.req.raw, { headers }));+ const response = await auth.handler(new Request(c.req.raw, { headers }));+ c.set("apiKeyRateLimit", await readApiKeyRateLimit(bearerToken));+ return response;}return auth.handler(c.req.raw);diff --git a/apps/api/src/utils/api-key-rejection.ts b/apps/api/src/utils/api-key-rejection.tsnew file mode 100644index 000000000..748d4151e--- /dev/null+++ b/apps/api/src/utils/api-key-rejection.ts@@ -0,0 +1,44 @@+import { HTTPException } from "hono/http-exception";+import {+ type ApiKeyDenial,+ apiKeyDenialHeaders,+ retryAfterSeconds,+} from "./rate-limit-headers";++function tooManyRequests(message: string, headers: Record<string, string>) {+ return new HTTPException(429, {+ message,+ res: new Response(message, { status: 429, headers }),+ });+}++export function apiKeyRejection(denial: ApiKeyDenial | null, now = new Date()) {+ if (!denial) return new HTTPException(401, { message: "Unauthorized" });+ return tooManyRequests(+ denial.status === "rate_limited"+ ? "Rate limit exceeded"+ : "API key usage limit exceeded",+ apiKeyDenialHeaders(denial, now),+ );+}++export function betterAuthLimitRejection(body: unknown, now = new Date()) {+ const { code, details } = (body ?? {}) as {+ code?: unknown;+ details?: { tryAgainIn?: unknown };+ };+ if (code === "USAGE_EXCEEDED")+ return apiKeyRejection({ status: "usage_exceeded", retryAt: null }, now);+ const tryAgainIn = details?.tryAgainIn;+ return tooManyRequests(+ "Rate limit exceeded",+ typeof tryAgainIn === "number"+ ? {+ "Retry-After": retryAfterSeconds(+ new Date(now.getTime() + tryAgainIn),+ now,+ ),+ }+ : {},+ );+}diff --git a/apps/api/src/utils/authenticate-api-request.ts b/apps/api/src/utils/authenticate-api-request.tsindex 5b8a4230a..700a313c8 100644--- a/apps/api/src/utils/authenticate-api-request.ts+++ b/apps/api/src/utils/authenticate-api-request.ts@@ -3,6 +3,7 @@ import { APIError } from "better-auth/api";import type { Context } from "hono";import { HTTPException } from "hono/http-exception";import { auth } from "../auth";+import { apiKeyRejection, betterAuthLimitRejection } from "./api-key-rejection";import { verifyApiKey } from "./verify-api-key";// User is tagged on Sentry's isolation scope; the per-request isolation@@ -24,6 +25,9 @@ async function getSession(headers: Headers) {try {return await auth.api.getSession({ headers });} catch (error) {+ if (error instanceof APIError && error.statusCode === 429) {+ throw betterAuthLimitRejection(error.body);+ }if (isAuthRejection(error)) {return null;}@@ -61,6 +65,26 @@ function parseBearerToken(authHeader: string | undefined): {};}+type VerifiedApiKey = Extract<+ Awaited<ReturnType<typeof verifyApiKey>>,+ { status: "valid" }+>;++function setApiKeyContext(c: Context, { key, rateLimit }: VerifiedApiKey) {+ c.set("userId", key.userId);+ c.set("userEmail", "");+ c.set("user", null);+ c.set("session", null);+ c.set("apiKey", {+ id: key.id,+ userId: key.userId,+ enabled: key.enabled,+ permissions: key.permissions,+ });+ c.set("apiKeyRateLimit", rateLimit);+ attachUserToScope(key.userId);+}+export async function authenticateApiRequest(c: Context): Promise<void> {const { token, malformed } = parseBearerToken(c.req.header("Authorization"));if (malformed) {@@ -70,41 +94,22 @@ export async function authenticateApiRequest(c: Context): Promise<void> {const apiKeyHeader = c.req.header("x-api-key")?.trim();if (!token && apiKeyHeader) {const apiKeyResult = await verifyApiKey(apiKeyHeader);- if (!apiKeyResult?.valid || !apiKeyResult.key) {- throw new HTTPException(401, { message: "Unauthorized" });+ if (apiKeyResult?.status !== "valid") {+ throw apiKeyRejection(apiKeyResult);}- const key = apiKeyResult.key;- c.set("userId", key.userId);- c.set("userEmail", "");- c.set("user", null);- c.set("session", null);- c.set("apiKey", {- id: key.id,- userId: key.userId,- enabled: key.enabled,- permissions: key.permissions,- });- attachUserToScope(key.userId);+ setApiKeyContext(c, apiKeyResult);return;}if (token) {const apiKeyResult = await verifyApiKey(token);- if (apiKeyResult?.valid && apiKeyResult.key) {- const key = apiKeyResult.key;- c.set("userId", key.userId);- c.set("userEmail", "");- c.set("user", null);- c.set("session", null);- c.set("apiKey", {- id: key.id,- userId: key.userId,- enabled: key.enabled,- permissions: key.permissions,- });- attachUserToScope(key.userId);+ if (apiKeyResult?.status === "valid") {+ setApiKeyContext(c, apiKeyResult);return;}+ if (apiKeyResult) {+ throw apiKeyRejection(apiKeyResult);+ }const sessionResult = await getSessionFromBearerOnlyHeaders(c);if (sessionResult?.user && sessionResult.session) {c.set("user", sessionResult.user);@@ -142,23 +147,28 @@ export async function resolveAssetBearerOrCookie(c: Context): Promise<{const apiKeyHeader = c.req.header("x-api-key")?.trim();if (!token && apiKeyHeader) {const apiKeyResult = await verifyApiKey(apiKeyHeader);- if (apiKeyResult?.valid && apiKeyResult.key) {- return {- userId: apiKeyResult.key.userId,- apiKeyId: apiKeyResult.key.id,- };+ if (apiKeyResult?.status !== "valid") {+ throw apiKeyRejection(apiKeyResult);}- throw new HTTPException(401, { message: "Unauthorized" });+ c.set("apiKeyRateLimit", apiKeyResult.rateLimit);+ return {+ userId: apiKeyResult.key.userId,+ apiKeyId: apiKeyResult.key.id,+ };}if (token) {const apiKeyResult = await verifyApiKey(token);- if (apiKeyResult?.valid && apiKeyResult.key) {+ if (apiKeyResult?.status === "valid") {+ c.set("apiKeyRateLimit", apiKeyResult.rateLimit);return {userId: apiKeyResult.key.userId,apiKeyId: apiKeyResult.key.id,};}+ if (apiKeyResult) {+ throw apiKeyRejection(apiKeyResult);+ }const sessionResult = await getSessionFromBearerOnlyHeaders(c);if (sessionResult?.user?.id) {return { userId: sessionResult.user.id };diff --git a/apps/api/src/utils/rate-limit-headers.test.ts b/apps/api/src/utils/rate-limit-headers.test.tsnew file mode 100644index 000000000..281ba83dc--- /dev/null+++ b/apps/api/src/utils/rate-limit-headers.test.ts@@ -0,0 +1,69 @@+import { describe, expect, it } from "vite-plus/test";+import {+ apiKeyDenialHeaders,+ rateLimitHeaders,+ retryAfterSeconds,+} from "./rate-limit-headers";++const now = new Date("2026-01-01T00:00:00.000Z");+const at = (ms: number) => new Date(now.getTime() + ms);++describe("retryAfterSeconds", () => {+ it("rounds partial seconds up", () => {+ expect(retryAfterSeconds(at(1_200), now)).toBe("2");+ expect(retryAfterSeconds(at(59_001), now)).toBe("60");+ });++ it("never asks for less than one second", () => {+ expect(retryAfterSeconds(at(0), now)).toBe("1");+ expect(retryAfterSeconds(at(-5_000), now)).toBe("1");+ });+});++describe("rateLimitHeaders", () => {+ it("reports the limit, remaining requests and the reset time in epoch seconds", () => {+ expect(+ rateLimitHeaders({ limit: 100, remaining: 42, resetAt: at(30_500) }),+ ).toEqual({+ "X-RateLimit-Limit": "100",+ "X-RateLimit-Remaining": "42",+ "X-RateLimit-Reset": String(Math.ceil(at(30_500).getTime() / 1000)),+ });+ });++ it("does not report a negative remaining count", () => {+ expect(+ rateLimitHeaders({ limit: 2, remaining: -1, resetAt: at(1_000) })[+ "X-RateLimit-Remaining"+ ],+ ).toBe("0");+ });+});++describe("apiKeyDenialHeaders", () => {+ it("sends Retry-After and an empty window when rate limited", () => {+ expect(+ apiKeyDenialHeaders(+ { status: "rate_limited", limit: 100, resetAt: at(12_300) },+ now,+ ),+ ).toEqual({+ "Retry-After": "13",+ "X-RateLimit-Limit": "100",+ "X-RateLimit-Remaining": "0",+ "X-RateLimit-Reset": String(Math.ceil(at(12_300).getTime() / 1000)),+ });+ });++ it("sends Retry-After for an exhausted quota only when it refills", () => {+ expect(+ apiKeyDenialHeaders(+ { status: "usage_exceeded", retryAt: at(3_600_000) },+ now,+ ),+ ).toEqual({ "Retry-After": "3600" });+ expect(+ apiKeyDenialHeaders({ status: "usage_exceeded", retryAt: null }, now),+ ).toEqual({});+ });+});diff --git a/apps/api/src/utils/rate-limit-headers.ts b/apps/api/src/utils/rate-limit-headers.tsnew file mode 100644index 000000000..0ec36558c--- /dev/null+++ b/apps/api/src/utils/rate-limit-headers.ts@@ -0,0 +1,46 @@+export type ApiKeyRateLimit = {+ limit: number;+ remaining: number;+ resetAt: Date;+};++export type ApiKeyDenial =+ | { status: "rate_limited"; limit: number; resetAt: Date }+ | { status: "usage_exceeded"; retryAt: Date | null };++export function retryAfterSeconds(retryAt: Date, now: Date) {+ return String(+ Math.max(1, Math.ceil((retryAt.getTime() - now.getTime()) / 1000)),+ );+}++export function rateLimitHeaders({+ limit,+ remaining,+ resetAt,+}: ApiKeyRateLimit): Record<string, string> {+ return {+ "X-RateLimit-Limit": String(limit),+ "X-RateLimit-Remaining": String(Math.max(0, remaining)),+ "X-RateLimit-Reset": String(Math.ceil(resetAt.getTime() / 1000)),+ };+}++export function apiKeyDenialHeaders(+ denial: ApiKeyDenial,+ now: Date,+): Record<string, string> {+ if (denial.status === "rate_limited") {+ return {+ "Retry-After": retryAfterSeconds(denial.resetAt, now),+ ...rateLimitHeaders({+ limit: denial.limit,+ remaining: 0,+ resetAt: denial.resetAt,+ }),+ };+ }+ return denial.retryAt+ ? { "Retry-After": retryAfterSeconds(denial.retryAt, now) }+ : {};+}diff --git a/apps/api/src/utils/verify-api-key.ts b/apps/api/src/utils/verify-api-key.tsindex 13b86ee9c..2b5e5f4a5 100644--- a/apps/api/src/utils/verify-api-key.ts+++ b/apps/api/src/utils/verify-api-key.ts@@ -1,6 +1,7 @@import { createHash } from "node:crypto";import { and, eq, exists, gt, isNull, or, sql } from "drizzle-orm";import db, { schema } from "../database";+import type { ApiKeyRateLimit } from "./rate-limit-headers";import { notBannedCondition } from "./user-ban";async function hashApiKey(key: string): Promise<string> {@@ -82,18 +83,6 @@ export async function verifyApiKey(const now = new Date();if (apiKey.expiresAt && apiKey.expiresAt <= now) return null;- if (options.consume === false)- return {- valid: true,- key: {- ...apiKey,- userId: apiKey.referenceId ?? apiKey.userId ?? "",- enabled: apiKey.enabled ?? false,- permissions: parsePermissions(apiKey.permissions),- metadata: null,- },- };-// Locking the key serializes quota/refill and window accounting across API// instances. Neither a stale lookup nor a rejected request can restore quota.let remaining = apiKey.remaining;@@ -108,20 +97,59 @@ export async function verifyApiKey(remaining = apiKey.refillAmount;lastRefillAt = now;}- if (remaining <= 0) return null;+ if (remaining <= 0)+ return {+ status: "usage_exceeded" as const,+ retryAt:+ apiKey.refillInterval && apiKey.refillAmount+ ? new Date(+ (lastRefillAt ?? apiKey.createdAt).getTime() ++ apiKey.refillInterval,+ )+ : null,+ };}let requestCount = apiKey.requestCount ?? 0;+ let rateLimit: ApiKeyRateLimit | null = null;if (apiKey.rateLimitEnabled) {const window = apiKey.rateLimitTimeWindow ?? 60_000;- if (- !apiKey.lastRequest ||- now.getTime() - apiKey.lastRequest.getTime() >= window- )+ const limit = apiKey.rateLimitMax ?? 100;+ let windowAnchor = apiKey.lastRequest;+ if (!windowAnchor || now.getTime() - windowAnchor.getTime() >= window) {requestCount = 0;- if (requestCount >= (apiKey.rateLimitMax ?? 100)) return null;+ windowAnchor = now;+ }+ if (requestCount >= limit)+ return {+ status: "rate_limited" as const,+ limit,+ resetAt: new Date(windowAnchor.getTime() + window),+ };+ if (options.consume !== false) {+ requestCount++;+ windowAnchor = now;+ }+ rateLimit = {+ limit,+ remaining: limit - requestCount,+ resetAt: new Date(windowAnchor.getTime() + window),+ };}++ if (options.consume === false)+ return {+ status: "valid" as const,+ rateLimit,+ key: {+ ...apiKey,+ userId: apiKey.referenceId ?? apiKey.userId ?? "",+ enabled: apiKey.enabled ?? false,+ permissions: parsePermissions(apiKey.permissions),+ metadata: null,+ },+ };+if (remaining !== null) remaining--;- if (apiKey.rateLimitEnabled) requestCount++;await tx.update(schema.apikeyTable).set({@@ -134,7 +162,8 @@ export async function verifyApiKey(.where(eq(schema.apikeyTable.id, apiKey.id));return {- valid: true,+ status: "valid" as const,+ rateLimit,key: {id: apiKey.id,userId: apiKey.referenceId ?? apiKey.userId ?? "",@@ -160,3 +189,12 @@ export async function verifyApiKey(};});}++export async function readApiKeyRateLimit(+ key: string,+): Promise<ApiKeyRateLimit | null> {+ const result = await verifyApiKey(key, { consume: false });+ if (result?.status === "rate_limited")+ return { limit: result.limit, remaining: 0, resetAt: result.resetAt };+ return result?.status === "valid" ? result.rateLimit : null;+}diff --git a/apps/docs/api-reference/authentication.mdx b/apps/docs/api-reference/authentication.mdxindex 422a8e938..a62ab421c 100644--- a/apps/docs/api-reference/authentication.mdx+++ b/apps/docs/api-reference/authentication.mdx@@ -38,6 +38,24 @@ const board = await response.json();Return to **API Keys** to remove a credential you no longer use. To rotate one, create a replacement, update the service that uses it, check a request succeeds, then revoke the old key.+## Rate limits++Each API key can make 100 requests per 60 seconds by default. Requests made with a browser session or a device access token do not count against it.++The window follows the key's most recent successful request. Every successful request starts the 60 seconds again, and the count resets only after a full window passes without a successful request. A steady stream of requests, even one per second, keeps the window open, so the key is limited after 100 requests until it has been idle for 60 seconds.++Successful requests made with an API key include these headers:++| Header | Meaning |+| --- | --- |+| `X-RateLimit-Limit` | Requests the key can make per window. |+| `X-RateLimit-Remaining` | Requests left in the current window. |+| `X-RateLimit-Reset` | Unix time in seconds when the window resets if the key makes no further requests. |++When a key goes over its limit, Kaneo answers `429 Too Many Requests` with the same headers, `X-RateLimit-Remaining: 0`, and a `Retry-After` header with the number of seconds to wait. Wait at least that long before you retry, and pace bulk jobs rather than retrying in a loop. A `429` does not mean the key is invalid. An unknown, disabled, or expired key still gets `401 Unauthorized`.++A key with a usage quota also gets `429` once the quota runs out, with the message `API key usage limit exceeded`. `Retry-After` is included when the quota refills at a known time.+## Device authorizationBy default, self-hosted Kaneo allows the built-in device clients `kaneo-cli` and `kaneo-mcp`.diff --git a/apps/docs/openapi.json b/apps/docs/openapi.jsonindex b43605a8b..1b39f9a15 100644--- a/apps/docs/openapi.json+++ b/apps/docs/openapi.json@@ -24,6 +24,44 @@"description": "API key or session token (Bearer)"}},+ "responses": {+ "ApiKeyRateLimited": {+ "description": "The API key exceeded its rate limit or usage quota. Wait the number of seconds in Retry-After before retrying. The X-RateLimit headers are sent only when the rate limit was hit.",+ "headers": {+ "Retry-After": {+ "description": "Seconds to wait before retrying. Omitted when an exhausted usage quota never refills.",+ "schema": {+ "type": "integer"+ }+ },+ "X-RateLimit-Limit": {+ "description": "Requests the API key may make per window.",+ "schema": {+ "type": "integer"+ }+ },+ "X-RateLimit-Remaining": {+ "description": "Requests left in the current window.",+ "schema": {+ "type": "integer"+ }+ },+ "X-RateLimit-Reset": {+ "description": "Unix time in seconds when the current window resets.",+ "schema": {+ "type": "integer"+ }+ }+ },+ "content": {+ "text/plain": {+ "schema": {+ "type": "string"+ }+ }+ }+ }+ },"schemas": {"InstanceStatus": {"type": "object",@@ -5368,6 +5406,9 @@},"401": {"description": "Missing or invalid credentials"+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -5445,6 +5486,9 @@},"401": {"description": "Missing or invalid credentials"+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -5482,6 +5526,9 @@},"401": {"description": "Missing or invalid credentials"+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -5519,6 +5566,9 @@},"401": {"description": "Missing or invalid credentials"+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -5592,6 +5642,9 @@},"401": {"description": "Missing or invalid credentials"+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -5647,6 +5700,9 @@},"401": {"description": "Missing or invalid credentials"+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -5724,6 +5780,9 @@},"401": {"description": "Missing or invalid credentials"+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -5768,6 +5827,9 @@},"401": {"description": "Missing or invalid credentials"+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -5833,6 +5895,9 @@},"401": {"description": "Missing or invalid credentials"+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -5878,6 +5943,9 @@},"401": {"description": "Missing or invalid credentials"+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -5896,6 +5964,9 @@},"401": {"description": "Missing or invalid credentials"+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -5919,6 +5990,9 @@},"401": {"description": "Missing or invalid credentials"+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -6015,6 +6089,9 @@},"401": {"description": "Missing or invalid credentials"+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -6033,6 +6110,9 @@},"401": {"description": "Missing or invalid credentials"+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -6094,6 +6174,9 @@},"401": {"description": "Missing or invalid credentials"+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -6243,6 +6326,9 @@"401": {"description": "Missing or invalid credentials"},+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"+ },"502": {"description": "Invitation saved, but email delivery failed","content": {@@ -6304,6 +6390,9 @@},"401": {"description": "Missing or invalid credentials"+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -6330,6 +6419,9 @@},"401": {"description": "Missing or invalid credentials"+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -6421,6 +6513,9 @@},"401": {"description": "Missing or invalid credentials"+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -6439,6 +6534,9 @@},"401": {"description": "Missing or invalid credentials"+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -6457,6 +6555,9 @@},"401": {"description": "Missing or invalid credentials"+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -6509,6 +6610,9 @@},"401": {"description": "Missing or invalid credentials"+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -6566,6 +6670,9 @@},"401": {"description": "Missing or invalid credentials"+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -6642,6 +6749,9 @@},"401": {"description": "Missing or invalid credentials"+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -6668,6 +6778,9 @@},"401": {"description": "Missing or invalid credentials"+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -6725,6 +6838,9 @@},"401": {"description": "Missing or invalid credentials"+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -6801,6 +6917,9 @@},"401": {"description": "Missing or invalid credentials"+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -6861,6 +6980,9 @@},"401": {"description": "Missing or invalid credentials"+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -6926,6 +7048,9 @@},"401": {"description": "Missing or invalid credentials"+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -6972,6 +7097,9 @@},"401": {"description": "Missing or invalid credentials"+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -7014,6 +7142,9 @@},"401": {"description": "Missing or invalid credentials"+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -7087,6 +7218,9 @@},"401": {"description": "Missing or invalid credentials"+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -7178,6 +7312,9 @@},"401": {"description": "Missing or invalid credentials"+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -7263,6 +7400,9 @@},"401": {"description": "Missing or invalid credentials"+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -7357,6 +7497,9 @@},"401": {"description": "Missing or invalid credentials"+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -7724,6 +7867,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -7749,6 +7895,9 @@},"401": {"description": "Missing or invalid credentials"+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -7860,6 +8009,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -7928,6 +8080,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}},@@ -8011,6 +8166,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -8066,6 +8224,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}},@@ -8163,6 +8324,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}},@@ -8216,6 +8380,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -8285,6 +8452,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}},@@ -8331,6 +8501,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -8424,6 +8597,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -8479,6 +8655,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -8544,6 +8723,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -8632,6 +8814,9 @@}}},+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"+ },"503": {"description": "Image uploads are not configured","content": {@@ -8737,6 +8922,9 @@}}},+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"+ },"500": {"description": "Failed to save the project background","content": {@@ -8811,6 +8999,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}},@@ -8897,6 +9088,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -8985,6 +9179,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -9080,6 +9277,9 @@}}},+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"+ },"503": {"description": "Description request timed out","content": {@@ -9164,6 +9364,9 @@}}},+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"+ },"503": {"description": "Description search timed out","content": {@@ -9243,6 +9446,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -9397,6 +9603,9 @@}}},+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"+ },"503": {"description": "Task list request timed out","content": {@@ -9513,6 +9722,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -9612,6 +9824,9 @@}}},+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"+ },"503": {"description": "Storage unavailable","content": {@@ -9734,6 +9949,9 @@}}},+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"+ },"503": {"description": "Storage unavailable","content": {@@ -9898,6 +10116,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -10026,6 +10247,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -10124,6 +10348,9 @@}}},+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"+ },"503": {"description": "Unable to copy task attachments","content": {@@ -10235,6 +10462,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -10302,6 +10532,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}},@@ -10411,6 +10644,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}},@@ -10474,6 +10710,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -10571,6 +10810,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -10626,6 +10868,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -10738,6 +10983,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -10811,6 +11059,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -10891,6 +11142,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -10978,6 +11232,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -11048,6 +11305,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -11121,6 +11381,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -11222,6 +11485,9 @@}}},+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"+ },"503": {"description": "Image uploads are not configured on this instance","content": {@@ -11336,6 +11602,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -11409,6 +11678,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -11467,6 +11739,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}},@@ -11557,6 +11832,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -11649,6 +11927,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -11734,6 +12015,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}},@@ -11797,6 +12081,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -11856,6 +12143,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -11926,6 +12216,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -12023,6 +12316,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -12091,6 +12387,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}},@@ -12167,6 +12466,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}},@@ -12238,6 +12540,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -12296,6 +12601,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}},@@ -12383,6 +12691,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -12468,6 +12779,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}},@@ -12531,6 +12845,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -12589,6 +12906,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -12644,6 +12964,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}},@@ -12725,6 +13048,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -12803,6 +13129,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -12861,6 +13190,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -12919,6 +13251,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -13013,6 +13348,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -13068,6 +13406,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}},@@ -13153,6 +13494,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}},@@ -13329,6 +13673,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}},@@ -13392,6 +13739,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -13433,6 +13783,9 @@},"401": {"description": "Missing or invalid credentials"+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}},@@ -13522,6 +13875,9 @@},"401": {"description": "Missing or invalid credentials"+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -13567,6 +13923,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -13605,6 +13964,9 @@},"401": {"description": "Missing or invalid credentials"+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -13643,6 +14005,9 @@},"401": {"description": "Missing or invalid credentials"+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -13668,6 +14033,9 @@},"401": {"description": "Missing or invalid credentials"+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}},@@ -13785,6 +14153,9 @@},"401": {"description": "Missing or invalid credentials"+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -13889,6 +14260,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}},@@ -13942,6 +14316,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -14051,6 +14428,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -14148,6 +14528,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}},@@ -14369,6 +14752,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -14586,6 +14972,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -14684,6 +15073,9 @@}}},+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"+ },"502": {"description": "External issue unavailable; sync remains paused","content": {@@ -14828,6 +15220,9 @@}}},+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"+ },"502": {"description": "External issue unavailable; sync remains paused","content": {@@ -14862,6 +15257,9 @@},"401": {"description": "Missing or invalid credentials"+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -14937,6 +15335,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -15013,6 +15414,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -15068,6 +15472,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}},@@ -15157,6 +15564,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}},@@ -15248,6 +15658,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}},@@ -15311,6 +15724,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -15505,6 +15921,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -15597,6 +16016,9 @@}}},+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"+ },"500": {"description": "Gitea verification failed","content": {@@ -15661,6 +16083,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}},@@ -15747,6 +16172,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}},@@ -15838,6 +16266,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}},@@ -15901,6 +16332,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -15974,6 +16408,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -16063,6 +16500,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -16158,6 +16598,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -16213,6 +16656,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}},@@ -16312,6 +16758,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}},@@ -16403,6 +16852,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}},@@ -16466,6 +16918,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -16539,6 +16994,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -16594,6 +17052,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}},@@ -16717,6 +17178,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}},@@ -16852,6 +17316,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}},@@ -16923,6 +17390,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -16978,6 +17448,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}},@@ -17076,6 +17549,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}},@@ -17186,6 +17662,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}},@@ -17257,6 +17736,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -17312,6 +17794,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}},@@ -17410,6 +17895,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}},@@ -17520,6 +18008,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}},@@ -17591,6 +18082,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -17646,6 +18140,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}},@@ -17744,6 +18241,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}},@@ -17854,6 +18354,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}},@@ -17925,6 +18428,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -17980,6 +18486,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}},@@ -18087,6 +18596,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}},@@ -18206,6 +18718,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}},@@ -18277,6 +18792,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -18335,6 +18853,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -18431,6 +18952,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -18486,6 +19010,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -18572,6 +19099,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}},@@ -18628,6 +19158,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -18708,6 +19241,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -18766,6 +19302,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}},@@ -18845,6 +19384,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -18900,6 +19442,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -18928,6 +19473,9 @@},"401": {"description": "Missing or invalid credentials"+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -18963,6 +19511,9 @@},"401": {"description": "Missing or invalid credentials"+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -19041,6 +19592,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -19096,6 +19650,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -19155,6 +19712,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -19259,6 +19819,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -19317,6 +19880,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -19375,6 +19941,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -19433,6 +20002,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -19491,6 +20063,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -19583,6 +20158,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -19671,6 +20249,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -19742,6 +20323,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -19797,6 +20381,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -19839,6 +20426,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -19921,6 +20511,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}},@@ -19944,6 +20537,9 @@},"401": {"description": "Missing or invalid credentials"+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -20024,6 +20620,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -20104,6 +20703,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -20162,6 +20764,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}},@@ -20264,6 +20869,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -20323,6 +20931,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -20430,6 +21041,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -20506,6 +21120,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}@@ -20594,6 +21211,9 @@}}}+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"}}}diff --git a/tests/api-integration/api-key-accounting.test.ts b/tests/api-integration/api-key-accounting.test.tsindex fb5fb4003..c234a4c68 100644--- a/tests/api-integration/api-key-accounting.test.ts+++ b/tests/api-integration/api-key-accounting.test.ts@@ -33,14 +33,18 @@ async function seedKey(describe("API key accounting", () => {it("denies an exhausted quota", async () => {const { key } = await seedKey({ remaining: 0 });- expect(await verifyApiKey(key)).toBeNull();+ expect(await verifyApiKey(key)).toEqual({+ status: "usage_exceeded",+ retryAt: null,+ });});it("enforces a rate window across concurrent requests", async () => {const { key, row } = await seedKey();const results = await Promise.all(Array.from({ length: 6 }, () => verifyApiKey(key)),);- expect(results.filter(Boolean)).toHaveLength(2);+ expect(results.filter((r) => r?.status === "valid")).toHaveLength(2);+ expect(results.filter((r) => r?.status === "rate_limited")).toHaveLength(4);const [saved] = await db.select().from(schema.apikeyTable)@@ -52,7 +56,10 @@ describe("API key accounting", () => {const results = await Promise.all(Array.from({ length: 5 }, () => verifyApiKey(key)),);- expect(results.filter(Boolean)).toHaveLength(1);+ expect(results.filter((r) => r?.status === "valid")).toHaveLength(1);+ expect(results.filter((r) => r?.status === "usage_exceeded")).toHaveLength(+ 4,+ );});it("refills eligible quota and resets an expired window", async () => {const old = new Date(Date.now() - 120000);@@ -64,7 +71,7 @@ describe("API key accounting", () => {lastRequest: old,requestCount: 2,});- expect(await verifyApiKey(key)).toMatchObject({ valid: true });+ expect(await verifyApiKey(key)).toMatchObject({ status: "valid" });});});@@ -98,7 +105,7 @@ it("creates normal API keys with the configured 100-per-minute limit", async ()expect(saved.rateLimitMax).toBe(100);expect(saved.rateLimitTimeWindow).toBe(60_000);for (let i = 0; i < 11; i++)- expect(await verifyApiKey(created.key)).not.toBeNull();+ expect(await verifyApiKey(created.key)).toMatchObject({ status: "valid" });});it.each([true, false])(diff --git a/tests/api-integration/api-key-banned-user.test.ts b/tests/api-integration/api-key-banned-user.test.tsindex 66e26c28f..4ec7c9cb8 100644--- a/tests/api-integration/api-key-banned-user.test.ts+++ b/tests/api-integration/api-key-banned-user.test.ts@@ -59,7 +59,8 @@ describe("API integration: API keys of banned users", () => {.update(schema.apikeyTable).set({ rateLimitEnabled: false, rateLimitMax: 1, requestCount: 0 }).where(eq(schema.apikeyTable.userId, userId));- for (let i = 0; i < 3; i++) expect(await verifyApiKey(key)).not.toBeNull();+ for (let i = 0; i < 3; i++)+ expect(await verifyApiKey(key)).toMatchObject({ status: "valid" });expect((await db.query.apikeyTable.findFirst({@@ -71,8 +72,8 @@ describe("API integration: API keys of banned users", () => {.update(schema.apikeyTable).set({ rateLimitEnabled: true }).where(eq(schema.apikeyTable.userId, userId));- expect(await verifyApiKey(key)).not.toBeNull();- expect(await verifyApiKey(key)).toBeNull();+ expect(await verifyApiKey(key)).toMatchObject({ status: "valid" });+ expect(await verifyApiKey(key)).toMatchObject({ status: "rate_limited" });});it("rejects the key of a banned user", async () => {diff --git a/tests/api-integration/api-key-rate-limit.test.ts b/tests/api-integration/api-key-rate-limit.test.tsnew file mode 100644index 000000000..22d4da2d7--- /dev/null+++ b/tests/api-integration/api-key-rate-limit.test.ts@@ -0,0 +1,288 @@+import { createHash, randomUUID } from "node:crypto";+import { eq } from "drizzle-orm";+import { beforeEach, describe, expect, it } from "vite-plus/test";+import db, { schema } from "../../apps/api/src/database";+import { createApp } from "../../apps/api/src/index";+import { signUpWithSession } from "./helpers/auth-session";+import { resetTestDatabase } from "./helpers/database";+import { createWorkspaceMember } from "./helpers/fixtures";++const LIMIT = 3;+const WINDOW = 60_000;++beforeEach(resetTestDatabase);++async function seedKey(+ overrides: Partial<typeof schema.apikeyTable.$inferInsert> = {},+) {+ const { user, workspace } = await createWorkspaceMember();+ const key = `rate-limit-test-${user.id}`.padEnd(64, "x");+ const [row] = await db+ .insert(schema.apikeyTable)+ .values({+ referenceId: user.id,+ userId: user.id,+ key: createHash("sha256").update(key).digest("base64url"),+ createdAt: new Date(),+ updatedAt: new Date(),+ rateLimitEnabled: true,+ rateLimitMax: LIMIT,+ rateLimitTimeWindow: WINDOW,+ ...overrides,+ })+ .returning();+ return { key, row, workspace };+}++async function fillWindow(id: string, lastRequest: Date) {+ await db+ .update(schema.apikeyTable)+ .set({ requestCount: LIMIT, lastRequest })+ .where(eq(schema.apikeyTable.id, id));+}++async function savedKey(id: string) {+ const [row] = await db+ .select()+ .from(schema.apikeyTable)+ .where(eq(schema.apikeyTable.id, id));+ return row;+}++function limitHeaders(response: Response) {+ return {+ limit: response.headers.get("x-ratelimit-limit"),+ remaining: response.headers.get("x-ratelimit-remaining"),+ reset: response.headers.get("x-ratelimit-reset"),+ retryAfter: response.headers.get("retry-after"),+ };+}++function epochSeconds(date: Date) {+ return String(Math.ceil(date.getTime() / 1000));+}++describe("API key rate limits", () => {+ it("reports the window on every successful key request", async () => {+ const { key } = await seedKey();+ const { app } = createApp();++ const before = Date.now();+ const first = await app.request("/api/user/me", {+ headers: { "x-api-key": key },+ });+ const after = Date.now();++ expect(first.status).toBe(200);+ const headers = limitHeaders(first);+ expect(headers).toMatchObject({+ limit: String(LIMIT),+ remaining: String(LIMIT - 1),+ retryAfter: null,+ });+ expect(Number(headers.reset)).toBeGreaterThanOrEqual(+ Math.ceil((before + WINDOW) / 1000),+ );+ expect(Number(headers.reset)).toBeLessThanOrEqual(+ Math.ceil((after + WINDOW) / 1000),+ );++ const second = await app.request("/api/user/me", {+ headers: { Authorization: `Bearer ${key}` },+ });+ expect(second.status).toBe(200);+ expect(limitHeaders(second).remaining).toBe(String(LIMIT - 2));+ });++ it.each([+ ["x-api-key", (key: string) => ({ "x-api-key": key })],+ ["a Bearer key", (key: string) => ({ Authorization: `Bearer ${key}` })],+ ])("answers 429 with retry headers via %s", async (_, headersFor) => {+ const { key, row } = await seedKey();+ const lastRequest = new Date(Date.now() - 45_000);+ await fillWindow(row.id, lastRequest);+ const { app } = createApp();++ const response = await app.request("/api/user/me", {+ headers: headersFor(key),+ });++ expect(response.status).toBe(429);+ expect(await response.text()).toContain("Rate limit exceeded");+ const headers = limitHeaders(response);+ expect(headers).toMatchObject({+ limit: String(LIMIT),+ remaining: "0",+ reset: epochSeconds(new Date(lastRequest.getTime() + WINDOW)),+ });+ expect(Number(headers.retryAfter)).toBeGreaterThanOrEqual(14);+ expect(Number(headers.retryAfter)).toBeLessThanOrEqual(15);++ const saved = await savedKey(row.id);+ expect(saved.requestCount).toBe(LIMIT);+ expect(saved.lastRequest?.getTime()).toBe(lastRequest.getTime());+ });++ it("answers 429 on Better Auth routes", async () => {+ const { key, row } = await seedKey();+ const { app } = createApp();++ const allowed = await app.request("/api/auth/get-session", {+ headers: { "x-api-key": key },+ });+ expect(allowed.status).toBe(200);+ expect(await allowed.json()).toMatchObject({+ user: { id: row.referenceId },+ });+ expect(limitHeaders(allowed)).toMatchObject({+ limit: String(LIMIT),+ remaining: String(LIMIT - 1),+ });++ await fillWindow(row.id, new Date());++ const limited = await app.request("/api/auth/get-session", {+ headers: { "x-api-key": key },+ });+ expect(limited.status).toBe(429);+ expect(await limited.text()).toContain("Rate limit exceeded");+ expect(limitHeaders(limited)).toMatchObject({+ limit: String(LIMIT),+ remaining: "0",+ });+ expect(Number(limitHeaders(limited).retryAfter)).toBeGreaterThanOrEqual(59);++ const bearer = await app.request("/api/auth/organization/list", {+ headers: { Authorization: `Bearer ${key}` },+ });+ expect(bearer.status).toBe(429);+ expect(await bearer.text()).toContain("Rate limit exceeded");+ expect(limitHeaders(bearer).remaining).toBe("0");+ expect(limitHeaders(bearer).retryAfter).not.toBeNull();+ });++ it("answers 429 when Better Auth rejects a rate limited key", async () => {+ const { key, row } = await seedKey();+ await fillWindow(row.id, new Date());+ const { app } = createApp();++ const response = await app.request("/api/user/me", {+ headers: { Authorization: "Bearer not-a-real-key", "x-api-key": key },+ });++ expect(response.status).toBe(429);+ expect(await response.text()).toContain("Rate limit exceeded");+ expect(Number(limitHeaders(response).retryAfter)).toBeGreaterThanOrEqual(+ 59,+ );+ });++ it("lets the key through again after a full window", async () => {+ const { key, row } = await seedKey();+ await fillWindow(row.id, new Date(Date.now() - WINDOW - 1_000));+ const { app } = createApp();++ const response = await app.request("/api/user/me", {+ headers: { "x-api-key": key },+ });++ expect(response.status).toBe(200);+ expect(limitHeaders(response).remaining).toBe(String(LIMIT - 1));+ });++ it.each([+ ["x-api-key", { "x-api-key": "not-a-real-key" }],+ ["Bearer", { Authorization: "Bearer not-a-real-key" }],+ ])("keeps answering 401 for an unknown key in %s", async (_, headers) => {+ const { app } = createApp();++ const response = await app.request("/api/user/me", { headers });++ expect(response.status).toBe(401);+ expect(await response.text()).toBe("Unauthorized");+ expect(limitHeaders(response)).toMatchObject({+ limit: null,+ retryAfter: null,+ });+ });++ it("sends no rate limit headers on session requests", async () => {+ const { app } = createApp();+ const { cookies } = await signUpWithSession(app, {+ email: `${randomUUID()}@example.com`,+ name: "Session User",+ });++ const response = await app.request("/api/user/me", {+ headers: { cookie: cookies },+ });++ expect(response.status).toBe(200);+ expect(limitHeaders(response)).toEqual({+ limit: null,+ remaining: null,+ reset: null,+ retryAfter: null,+ });+ });++ it("keeps the headers when the route itself fails", async () => {+ const { key, workspace } = await seedKey();+ const { app } = createApp();++ const missing = await app.request(+ `/api/workspace/${workspace.id}/members?projectId=${randomUUID()}`,+ { headers: { "x-api-key": key } },+ );+ expect(missing.status).toBe(404);+ expect(await missing.text()).toContain("Project not found");+ expect(limitHeaders(missing)).toMatchObject({+ limit: String(LIMIT),+ remaining: String(LIMIT - 1),+ });++ const unknownRoute = await app.request("/api/no-such-route", {+ headers: { "x-api-key": key },+ });+ expect(unknownRoute.status).toBe(404);+ expect(limitHeaders(unknownRoute).remaining).toBe(String(LIMIT - 2));+ });++ it("answers 429 when the usage quota is exhausted", async () => {+ const lastRefillAt = new Date(Date.now() - 600_000);+ const { key, row } = await seedKey({+ remaining: 0,+ refillAmount: 5,+ refillInterval: 3_600_000,+ lastRefillAt,+ });+ const { app } = createApp();++ const response = await app.request("/api/user/me", {+ headers: { "x-api-key": key },+ });++ expect(response.status).toBe(429);+ expect(await response.text()).toContain("API key usage limit exceeded");+ const retryAfter = Number(limitHeaders(response).retryAfter);+ expect(retryAfter).toBeGreaterThanOrEqual(2_999);+ expect(retryAfter).toBeLessThanOrEqual(3_000);+ expect(limitHeaders(response).limit).toBeNull();+ expect((await savedKey(row.id)).remaining).toBe(0);+ });++ it("answers 429 without Retry-After when the quota never refills", async () => {+ const { key } = await seedKey({ remaining: 0 });+ const { app } = createApp();++ for (const headers of [+ { "x-api-key": key },+ { Authorization: `Bearer ${key}` },+ ]) {+ const response = await app.request("/api/user/me", { headers });+ expect(response.status).toBe(429);+ expect(await response.text()).toContain("API key usage limit exceeded");+ expect(limitHeaders(response).retryAfter).toBeNull();+ }+ });+});diff --git a/tests/api-integration/cors.test.ts b/tests/api-integration/cors.test.tsindex 574b27aab..80f5c3a2c 100644--- a/tests/api-integration/cors.test.ts+++ b/tests/api-integration/cors.test.ts@@ -57,6 +57,30 @@ describe("API integration: CORS origin policy", () => {expect(await originHeaderFor("https://attacker.example")).toBeNull();});+ it("lets browser clients read the rate limit headers", async () => {+ process.env.NODE_ENV = "production";+ process.env.KANEO_CLIENT_URL = "https://kaneo.example";+ delete process.env.CORS_ORIGINS;+ const { app } = createApp();++ const response = await app.request("/api/health", {+ headers: { origin: "https://kaneo.example" },+ });++ const exposed = response.headers+ .get("access-control-expose-headers")+ ?.split(",")+ .map((name) => name.trim().toLowerCase());+ expect(exposed).toEqual(+ expect.arrayContaining([+ "retry-after",+ "x-ratelimit-limit",+ "x-ratelimit-remaining",+ "x-ratelimit-reset",+ ]),+ );+ });+it("honours a comma-separated CORS_ORIGINS allowlist", async () => {process.env.NODE_ENV = "production";delete process.env.KANEO_CLIENT_URL;diff --git a/tests/api-integration/openapi.test.ts b/tests/api-integration/openapi.test.tsindex c6d608691..72c12655f 100644--- a/tests/api-integration/openapi.test.ts+++ b/tests/api-integration/openapi.test.ts@@ -13,6 +13,7 @@ type Spec = {paths: Record<string, Record<string, Operation>>;security?: Array<Record<string, unknown>>;components: {+ responses: Record<string, { headers?: Record<string, unknown> }>;schemas: Record<string, unknown>;securitySchemes: Record<string, { type: string; scheme?: string }>;};@@ -124,4 +125,29 @@ describe("Kaneo API OpenAPI spec", () => {}expect(missing).toEqual([]);});++ it("documents the API key rate limit on every operation that requires auth", () => {+ expect(+ Object.keys(+ spec.components.responses.ApiKeyRateLimited?.headers ?? {},+ ).sort(),+ ).toEqual([+ "Retry-After",+ "X-RateLimit-Limit",+ "X-RateLimit-Remaining",+ "X-RateLimit-Reset",+ ]);+ const missing: string[] = [];+ for (const [method, path, operation] of operations(spec)) {+ const isPublic =+ Array.isArray(operation.security) && operation.security.length === 0;+ if (isPublic) continue;+ if (!operation.responses["429"])+ missing.push(`${method.toUpperCase()} ${path}`);+ }+ expect(missing).toEqual([]);+ expect(spec.paths["/project"]?.get?.responses["429"]).toEqual({+ $ref: "#/components/responses/ApiKeyRateLimited",+ });+ });});diff --git a/tests/api-integration/websocket-security.test.ts b/tests/api-integration/websocket-security.test.tsindex a0b4e70f7..51c42fc85 100644--- a/tests/api-integration/websocket-security.test.ts+++ b/tests/api-integration/websocket-security.test.ts@@ -131,7 +131,7 @@ describe.each(["project", "user"])("%s WebSocket", (endpoint) => {.where(eq(schema.apikeyTable.id, row.id));expect(saved.remaining).toBe(0);expect(saved.requestCount).toBe(1);- expect((await connect(path(), { "x-api-key": key })).status).toBe(401);+ expect((await connect(path(), { "x-api-key": key })).status).toBe(429);});it("rejects missing, null, hostile and lookalike browser origins", async () => {for (const origin of [