Skip to content

🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.

feat(api)!: reject legacy reads for new organizations (#17487)

Max Deichmann7ee78c93cf58
diff --git a/.env.prod.example b/.env.prod.example
index 946e180156..ef4e88247a 100644
--- a/.env.prod.example
+++ b/.env.prod.example
@@ -69,6 +69,10 @@ OTEL_SERVICE_NAME="langfuse"
# Enable experimental features, optional
# LANGFUSE_ENABLE_EXPERIMENTAL_FEATURES=false
+# Reject deprecated GET APIs for Cloud organizations created on or after the cutoff date, optional (default: false)
+# LANGFUSE_API_ORGANIZATION_CUTOFF_ENABLED=false
+# LANGFUSE_API_ORGANIZATION_CUTOFF_DATE=2026-09-16T00:00:00.000Z
+
# Auth, optional configuration
# AUTH_DOMAINS_WITH_SSO_ENFORCEMENT=domain1.com,domain2.com
# AUTH_IGNORE_ACCOUNT_FIELDS=foo,bar
diff --git a/packages/shared/src/server/auth/types.ts b/packages/shared/src/server/auth/types.ts
index bd8ba25cdc..4a92cb47a9 100644
--- a/packages/shared/src/server/auth/types.ts
+++ b/packages/shared/src/server/auth/types.ts
@@ -14,6 +14,7 @@ const ApiKeyBaseSchema = z.object({
fastHashedSecretKey: z.string(),
hashedSecretKey: z.string(),
orgId: z.string(),
+ organizationCreatedAt: z.iso.datetime(),
plan: z.enum(plans as unknown as [string, ...string[]]),
rateLimitOverrides: CloudConfigRateLimit.nullish(),
isIngestionSuspended: z.boolean().nullish(),
@@ -68,6 +69,7 @@ type BaseApiAccessScope = {
type ApiAccessScopeMetadata = {
orgId: string;
+ organizationCreatedAt?: string | null;
plan: Plan;
rateLimitOverrides: z.infer<typeof CloudConfigRateLimit>;
apiKeyId: string;
diff --git a/web/src/__tests__/server/api-auth.servertest.ts b/web/src/__tests__/server/api-auth.servertest.ts
index ff5dcd2168..4c2366d3c3 100644
--- a/web/src/__tests__/server/api-auth.servertest.ts
+++ b/web/src/__tests__/server/api-auth.servertest.ts
@@ -513,6 +513,9 @@ describe("Authenticate API calls", () => {
const apiKey = await prisma.apiKey.findUnique({
where: { publicKey: legacyPublicKey },
});
+ const organization = await prisma.organization.findUniqueOrThrow({
+ where: { id: testApiKey.orgId },
+ });
expect(apiKey).not.toBeNull();
expect(apiKey?.fastHashedSecretKey).not.toBeNull();
@@ -552,6 +555,7 @@ describe("Authenticate API calls", () => {
},
],
createdAt: apiKey?.createdAt.toISOString(),
+ organizationCreatedAt: organization.createdAt.toISOString(),
isIngestionSuspended: expect.anything(),
});
@@ -668,6 +672,7 @@ describe("Authenticate API calls", () => {
},
],
createdAt: apiKey?.createdAt.toISOString(),
+ organizationCreatedAt: expect.any(String),
isIngestionSuspended: expect.anything(),
});
@@ -798,6 +803,7 @@ describe("Authenticate API calls", () => {
orgId: testApiKey.orgId,
plan: "cloud:hobby",
scope: "PROJECT",
+ organizationCreatedAt: expect.any(String),
});
});
@@ -885,6 +891,7 @@ describe("Authenticate API calls", () => {
orgId: testApiKey.orgId,
plan: "cloud:hobby",
createdAt: apiKey?.createdAt.toISOString(),
+ organizationCreatedAt: expect.any(String),
scope: "PROJECT",
isIngestionSuspended: expect.anything(),
});
diff --git a/web/src/__tests__/server/unit/apiKey/authenticator.servertest.ts b/web/src/__tests__/server/unit/apiKey/authenticator.servertest.ts
index 156f817255..204393753f 100644
--- a/web/src/__tests__/server/unit/apiKey/authenticator.servertest.ts
+++ b/web/src/__tests__/server/unit/apiKey/authenticator.servertest.ts
@@ -65,6 +65,7 @@ const store = (key: ApiKey): ApiKeyRepository =>
const orgRow = {
id: ORG,
+ createdAt: new Date("2026-09-16T00:00:00.000Z"),
cloudConfig: null,
cloudFreeTierUsageThresholdState: null,
projects: [{ id: PRJ }],
diff --git a/web/src/__tests__/server/unit/create-authed-project-api-route-auth-errors.servertest.ts b/web/src/__tests__/server/unit/create-authed-project-api-route-auth-errors.servertest.ts
index 396854da1b..877073634d 100644
--- a/web/src/__tests__/server/unit/create-authed-project-api-route-auth-errors.servertest.ts
+++ b/web/src/__tests__/server/unit/create-authed-project-api-route-auth-errors.servertest.ts
@@ -9,16 +9,29 @@ const {
mockRateLimitRequest,
mockTraceException,
mockLoggerDebug,
+ mockLoggerInfo,
+ mockRecordIncrement,
+ mockFindOrganization,
mockCreateStructuredPublicApiAuthError,
mockSendStructuredPublicApiErrorResponse,
+ mockEnv,
} = vi.hoisted(() => ({
mockVerifyAuthHeaderAndReturnScope: vi.fn(),
mockIsPrismaException: vi.fn(),
mockRateLimitRequest: vi.fn(),
mockTraceException: vi.fn(),
mockLoggerDebug: vi.fn(),
+ mockLoggerInfo: vi.fn(),
+ mockRecordIncrement: vi.fn(),
+ mockFindOrganization: vi.fn(),
mockCreateStructuredPublicApiAuthError: vi.fn((value) => value),
mockSendStructuredPublicApiErrorResponse: vi.fn(),
+ mockEnv: {
+ NODE_ENV: "test",
+ NEXT_PUBLIC_LANGFUSE_CLOUD_REGION: undefined as string | undefined,
+ LANGFUSE_API_ORGANIZATION_CUTOFF_ENABLED: "false" as "true" | "false",
+ LANGFUSE_API_ORGANIZATION_CUTOFF_DATE: "2026-09-16T00:00:00.000Z",
+ },
}));
vi.mock("@/src/features/public-api/server/apiAuth", () => ({
@@ -34,7 +47,11 @@ vi.mock("@langfuse/shared/src/db", async () => {
GatewayConnectionStatus,
GatewayIngestionMode,
GatewayProvider,
- prisma: {},
+ prisma: {
+ organization: {
+ findUnique: mockFindOrganization,
+ },
+ },
};
});
@@ -42,10 +59,11 @@ vi.mock("@langfuse/shared/src/server", () => ({
redis: null,
logger: {
debug: mockLoggerDebug,
- info: vi.fn(),
+ info: mockLoggerInfo,
warn: vi.fn(),
error: vi.fn(),
},
+ recordIncrement: mockRecordIncrement,
traceException: mockTraceException,
contextWithLangfuseProps: vi.fn(() => ({})),
ClickHouseClientManager: {
@@ -78,11 +96,7 @@ vi.mock(
}),
);
-vi.mock("@/src/env.mjs", () => ({
- env: {
- NODE_ENV: "test",
- },
-}));
+vi.mock("@/src/env.mjs", () => ({ env: mockEnv }));
vi.mock("@opentelemetry/api", () => ({
context: {
@@ -97,11 +111,19 @@ vi.mock("@/src/utils/exceptions", () => ({
import { createAuthedProjectAPIRoute } from "@/src/features/public-api/server/createAuthedProjectAPIRoute";
describe("createAuthedProjectAPIRoute auth error handling", () => {
+ const deprecation = {
+ message: "This endpoint is deprecated. Use the replacement.",
+ replacement: "GET /api/public/v2/observations",
+ docsUrl:
+ "https://langfuse.com/docs/api-and-data-platform/features/observations-api",
+ sunsetAt: "2026-11-16",
+ };
const validAuth = {
validKey: true,
scope: {
projectId: "project-1",
orgId: "org-1",
+ organizationCreatedAt: "2026-09-16T00:00:00.000Z",
plan: "cloud:hobby",
accessLevel: "project",
rateLimitOverrides: [],
@@ -118,6 +140,8 @@ describe("createAuthedProjectAPIRoute auth error handling", () => {
mockRateLimitRequest.mockResolvedValue({
isRateLimited: () => false,
});
+ mockEnv.NEXT_PUBLIC_LANGFUSE_CLOUD_REGION = undefined;
+ mockEnv.LANGFUSE_API_ORGANIZATION_CUTOFF_ENABLED = "false";
});
async function callRoute(options?: {
@@ -128,6 +152,8 @@ describe("createAuthedProjectAPIRoute auth error handling", () => {
docsUrl: string;
};
mockResponseSerializationError?: boolean;
+ deprecation?: typeof deprecation;
+ method?: "GET" | "POST";
}) {
const handler = createAuthedProjectAPIRoute({
name: "Test Route",
@@ -138,11 +164,13 @@ describe("createAuthedProjectAPIRoute auth error handling", () => {
? "structured"
: undefined,
rateLimitUpgradePath: options?.rateLimitUpgradePath,
+ deprecation: options?.deprecation,
fn: async () => ({ ok: true as const }),
});
const { req, res } = createMocks<NextApiRequest, NextApiResponse>({
- method: "GET",
+ method: options?.method ?? "GET",
+ url: "/api/public/test",
headers: {
authorization: "Basic test",
},
@@ -163,6 +191,108 @@ describe("createAuthedProjectAPIRoute auth error handling", () => {
return res;
}
+ it("rejects deprecated GET routes using cached organization data with actionable guidance", async () => {
+ mockEnv.NEXT_PUBLIC_LANGFUSE_CLOUD_REGION = "US";
+ mockEnv.LANGFUSE_API_ORGANIZATION_CUTOFF_ENABLED = "true";
+ mockVerifyAuthHeaderAndReturnScope.mockResolvedValueOnce(validAuth);
+
+ const res = await callRoute({ deprecation });
+
+ expect(res.statusCode).toBe(410);
+ expect(res._getJSONData()).toEqual({
+ error: "LEGACY_API_UNAVAILABLE_FOR_NEW_ORGANIZATION",
+ message:
+ "GET /api/public/test is a legacy API that is not available to organizations created on or after September 16, 2026. Migrate this request to GET /api/public/v2/observations. See the migration documentation at https://langfuse.com/docs/api-and-data-platform/features/observations-api.",
+ requestedEndpoint: "GET /api/public/test",
+ replacementEndpoint: "GET /api/public/v2/observations",
+ documentationUrl:
+ "https://langfuse.com/docs/api-and-data-platform/features/observations-api",
+ _deprecation: deprecation,
+ });
+ expect(mockRateLimitRequest).toHaveBeenCalledOnce();
+ expect(mockRecordIncrement).toHaveBeenCalledWith(
+ "langfuse.public_api.legacy_get_rejected",
+ 1,
+ );
+ expect(mockFindOrganization).not.toHaveBeenCalled();
+ expect(mockLoggerInfo).toHaveBeenCalledWith(
+ "Rejected legacy GET API request for organization created at or after cutoff",
+ {
+ orgId: "org-1",
+ projectId: "project-1",
+ apiRoute: "Test Route",
+ apiPath: "GET /api/public/test",
+ organizationCreatedAt: "2026-09-16T00:00:00.000Z",
+ cutoff: "2026-09-16T00:00:00.000Z",
+ },
+ );
+ });
+
+ it("keeps deprecated GET routes available when the cutoff is disabled", async () => {
+ mockEnv.NEXT_PUBLIC_LANGFUSE_CLOUD_REGION = "US";
+ mockVerifyAuthHeaderAndReturnScope.mockResolvedValueOnce(validAuth);
+
+ const res = await callRoute({ deprecation });
+
+ expect(res.statusCode).toBe(200);
+ expect(mockFindOrganization).not.toHaveBeenCalled();
+ expect(mockRecordIncrement).not.toHaveBeenCalled();
+ expect(mockLoggerInfo).not.toHaveBeenCalled();
+ });
+
+ it("keeps deprecated GET routes available to older Cloud organizations", async () => {
+ mockEnv.NEXT_PUBLIC_LANGFUSE_CLOUD_REGION = "US";
+ mockEnv.LANGFUSE_API_ORGANIZATION_CUTOFF_ENABLED = "true";
+ mockVerifyAuthHeaderAndReturnScope.mockResolvedValueOnce({
+ ...validAuth,
+ scope: {
+ ...validAuth.scope,
+ organizationCreatedAt: "2026-09-15T23:59:59.999Z",
+ },
+ });
+
+ const res = await callRoute({ deprecation });
+
+ expect(res.statusCode).toBe(200);
+ expect(res._getJSONData()).toEqual({
+ ok: true,
+ _deprecation: deprecation,
+ });
+ expect(mockFindOrganization).not.toHaveBeenCalled();
+ });
+
+ it("does not apply the organization cutoff outside Langfuse Cloud", async () => {
+ mockEnv.LANGFUSE_API_ORGANIZATION_CUTOFF_ENABLED = "true";
+ mockVerifyAuthHeaderAndReturnScope.mockResolvedValueOnce(validAuth);
+
+ const res = await callRoute({ deprecation });
+
+ expect(res.statusCode).toBe(200);
+ expect(mockFindOrganization).not.toHaveBeenCalled();
+ });
+
+ it("does not apply the organization cutoff to current GET routes", async () => {
+ mockEnv.NEXT_PUBLIC_LANGFUSE_CLOUD_REGION = "US";
+ mockEnv.LANGFUSE_API_ORGANIZATION_CUTOFF_ENABLED = "true";
+ mockVerifyAuthHeaderAndReturnScope.mockResolvedValueOnce(validAuth);
+
+ const res = await callRoute();
+
+ expect(res.statusCode).toBe(200);
+ expect(mockFindOrganization).not.toHaveBeenCalled();
+ });
+
+ it("does not apply the organization cutoff to deprecated write routes", async () => {
+ mockEnv.NEXT_PUBLIC_LANGFUSE_CLOUD_REGION = "US";
+ mockEnv.LANGFUSE_API_ORGANIZATION_CUTOFF_ENABLED = "true";
+ mockVerifyAuthHeaderAndReturnScope.mockResolvedValueOnce(validAuth);
+
+ const res = await callRoute({ deprecation, method: "POST" });
+
+ expect(res.statusCode).toBe(200);
+ expect(mockFindOrganization).not.toHaveBeenCalled();
+ });
+
it("returns 401 for invalid credentials", async () => {
mockVerifyAuthHeaderAndReturnScope.mockResolvedValueOnce({
validKey: false,
@@ -243,6 +373,25 @@ describe("createAuthedProjectAPIRoute auth error handling", () => {
});
});
+ it("rate limits deprecated GET routes before loading the organization", async () => {
+ const sendRestResponseIfLimited = vi.fn((res: NextApiResponse) => {
+ res.status(429).json({ message: "rate limited" });
+ });
+
+ mockEnv.NEXT_PUBLIC_LANGFUSE_CLOUD_REGION = "US";
+ mockEnv.LANGFUSE_API_ORGANIZATION_CUTOFF_ENABLED = "true";
+ mockVerifyAuthHeaderAndReturnScope.mockResolvedValueOnce(validAuth);
+ mockRateLimitRequest.mockResolvedValueOnce({
+ isRateLimited: () => true,
+ sendRestResponseIfLimited,
+ });
+
+ const res = await callRoute({ deprecation });
+
+ expect(res.statusCode).toBe(429);
+ expect(mockFindOrganization).not.toHaveBeenCalled();
+ });
+
it("passes upgrade guidance to the shared rate limit response", async () => {
const sendRestResponseIfLimited = vi.fn((res: NextApiResponse) => {
res.status(429).json({ message: "rate limited" });
diff --git a/web/src/__tests__/server/unit/policy/contextResolver.servertest.ts b/web/src/__tests__/server/unit/policy/contextResolver.servertest.ts
index eb83eab067..17698d45fa 100644
--- a/web/src/__tests__/server/unit/policy/contextResolver.servertest.ts
+++ b/web/src/__tests__/server/unit/policy/contextResolver.servertest.ts
@@ -18,12 +18,14 @@ const ORG = "org_1";
const PRJ = "prj_1";
const OTHER_PRJ = "prj_2";
const USER = "user_1";
+const ORGANIZATION_CREATED_AT = new Date("2026-09-16T00:00:00.000Z");
const orgRow = (
over: Partial<OrganizationWithProjects> = {},
): OrganizationWithProjects =>
({
id: ORG,
+ createdAt: ORGANIZATION_CREATED_AT,
cloudConfig: null,
cloudFreeTierUsageThresholdState: null,
projects: [{ id: PRJ }, { id: OTHER_PRJ }],
@@ -176,6 +178,18 @@ describe("attribution", () => {
ctx.principal.kind === "apiKey" && ctx.principal.isInAppAgentKey,
).toBe(true);
});
+
+ it("carries the organization creation time", async () => {
+ const ctx = await contextFor({
+ authorization: "privateKey",
+ apiKey: apiKey(),
+ });
+ const org =
+ ctx.principal.kind === "apiKey" ? ctx.principal.organizations[0] : null;
+ expect(org?.organizationCreatedAt).toBe(
+ ORGANIZATION_CREATED_AT.toISOString(),
+ );
+ });
});
describe("org suspension rides as a boolean, not a policy", () => {
diff --git a/web/src/__tests__/server/unit/public-api/toApiAccessScope.servertest.ts b/web/src/__tests__/server/unit/public-api/toApiAccessScope.servertest.ts
index 83436b1baa..fa8a0a736d 100644
--- a/web/src/__tests__/server/unit/public-api/toApiAccessScope.servertest.ts
+++ b/web/src/__tests__/server/unit/public-api/toApiAccessScope.servertest.ts
@@ -7,6 +7,7 @@ import { type Principal } from "@/src/features/auth/policy/types";
const scopeOrg = {
orgId: "org_1",
+ organizationCreatedAt: "2026-09-16T00:00:00.000Z",
plan: "oss" as const,
rateLimitOverrides: [],
projectIds: ["prj_1"],
@@ -35,6 +36,7 @@ const projectScope = {
projectId: "prj_1",
accessLevel: "project",
orgId: "org_1",
+ organizationCreatedAt: "2026-09-16T00:00:00.000Z",
plan: "oss",
rateLimitOverrides: [],
apiKeyId: "key_1",
@@ -54,6 +56,7 @@ describe("toApiAccessScope", () => {
projectId: null,
accessLevel: "organization",
orgId: "org_1",
+ organizationCreatedAt: "2026-09-16T00:00:00.000Z",
plan: "oss",
rateLimitOverrides: [],
apiKeyId: "key_1",
diff --git a/web/src/env.mjs b/web/src/env.mjs
index 2fdfbc26d9..c0c8857bad 100644
--- a/web/src/env.mjs
+++ b/web/src/env.mjs
@@ -599,6 +599,15 @@ export const env = createEnv({
.default("false"),
LANGFUSE_API_TRACES_DEFAULT_FIELDS: z.string().optional(),
LANGFUSE_API_TRACEBYID_DEFAULT_FIELDS: z.string().optional(),
+ // Cloud rollout gate for rejecting deprecated GET APIs for organizations
+ // created on or after the cutoff date. Defaults off: the cutoff date is
+ // today, so a date-only gate would start rejecting on deploy.
+ LANGFUSE_API_ORGANIZATION_CUTOFF_ENABLED: z
+ .enum(["true", "false"])
+ .default("false"),
+ LANGFUSE_API_ORGANIZATION_CUTOFF_DATE: z.iso
+ .datetime()
+ .default("2026-09-16T00:00:00.000Z"),
// V4 preview opt-in. See LFE-9778. Defaults on for the v4 target state so
// the events read paths are available out of the box (v3 shipped "false").
@@ -1181,6 +1190,10 @@ export const env = createEnv({
process.env.LANGFUSE_API_TRACES_DEFAULT_FIELDS,
LANGFUSE_API_TRACEBYID_DEFAULT_FIELDS:
process.env.LANGFUSE_API_TRACEBYID_DEFAULT_FIELDS,
+ LANGFUSE_API_ORGANIZATION_CUTOFF_ENABLED:
+ process.env.LANGFUSE_API_ORGANIZATION_CUTOFF_ENABLED,
+ LANGFUSE_API_ORGANIZATION_CUTOFF_DATE:
+ process.env.LANGFUSE_API_ORGANIZATION_CUTOFF_DATE,
LANGFUSE_MIGRATION_V4_ALLOW_PREVIEW_OPT_IN:
process.env.LANGFUSE_MIGRATION_V4_ALLOW_PREVIEW_OPT_IN,
LANGFUSE_MIGRATION_V4_WRITE_MODE:
diff --git a/web/src/features/auth/policy/contextResolver.ts b/web/src/features/auth/policy/contextResolver.ts
index a0c7e15b6e..ee8d022aab 100644
--- a/web/src/features/auth/policy/contextResolver.ts
+++ b/web/src/features/auth/policy/contextResolver.ts
@@ -163,6 +163,7 @@ function toPrincipalOrganization(
const cloudConfig = getCloudConfig(org);
return {
orgId: org.id,
+ organizationCreatedAt: org.createdAt.toISOString(),
plan: getOrganizationPlanServerSide(cloudConfig),
rateLimitOverrides: cloudConfig?.rateLimitOverrides ?? [],
projectIds: org.projects.map((p) => p.id),
diff --git a/web/src/features/auth/policy/types.ts b/web/src/features/auth/policy/types.ts
index 71a02a5c3c..fcd1368b42 100644
--- a/web/src/features/auth/policy/types.ts
+++ b/web/src/features/auth/policy/types.ts
@@ -50,6 +50,7 @@ export type Action = ProjectAction | OrganizationAction;
/** PrincipalOrganization carries an org's static caps and its ingestion-suspension liveness state, enforced at the seam not the PDP. */
export type PrincipalOrganization = {
orgId: string;
+ organizationCreatedAt: string;
plan: Plan;
rateLimitOverrides: z.infer<typeof CloudConfigRateLimit>;
projectIds: string[];
diff --git a/web/src/features/public-api/server/apiAuth.ts b/web/src/features/public-api/server/apiAuth.ts
index 3cc70fa025..cb27695719 100644
--- a/web/src/features/public-api/server/apiAuth.ts
+++ b/web/src/features/public-api/server/apiAuth.ts
@@ -201,6 +201,7 @@ export class ApiAuthService {
projectId: finalApiKey.projectId,
accessLevel,
orgId: finalApiKey.orgId,
+ organizationCreatedAt: finalApiKey.organizationCreatedAt,
plan: plan,
rateLimitOverrides: finalApiKey.rateLimitOverrides ?? [],
apiKeyId: finalApiKey.id,
@@ -225,8 +226,12 @@ export class ApiAuthService {
);
}
- const { orgId, cloudConfig, cloudFreeTierUsageThresholdState } =
- this.extractOrgIdAndCloudConfig(dbKey);
+ const {
+ orgId,
+ organizationCreatedAt,
+ cloudConfig,
+ cloudFreeTierUsageThresholdState,
+ } = this.extractOrgIdAndCloudConfig(dbKey);
const plan = getOrganizationPlanServerSide(cloudConfig);
addUserToSpan(
@@ -246,6 +251,7 @@ export class ApiAuthService {
projectId: dbKey.projectId,
accessLevel: "scores" as const,
orgId,
+ organizationCreatedAt: organizationCreatedAt.toISOString(),
plan,
rateLimitOverrides: cloudConfig?.rateLimitOverrides ?? [],
apiKeyId: dbKey.id,
@@ -447,6 +453,9 @@ export class ApiAuthService {
const orgId =
apiKeyAndOrganisation.project?.organization.id ??
apiKeyAndOrganisation.organization?.id;
+ const organizationCreatedAt =
+ apiKeyAndOrganisation.project?.organization.createdAt ??
+ apiKeyAndOrganisation.organization?.createdAt;
const rawCloudConfig =
apiKeyAndOrganisation.project?.organization.cloudConfig ??
apiKeyAndOrganisation.organization?.cloudConfig;
@@ -455,7 +464,7 @@ export class ApiAuthService {
.cloudFreeTierUsageThresholdState ??
apiKeyAndOrganisation.organization?.cloudFreeTierUsageThresholdState;
- if (!orgId) {
+ if (!orgId || !organizationCreatedAt) {
logger.error(
`No organization found for key: ${apiKeyAndOrganisation.publicKey}`,
);
@@ -468,6 +477,7 @@ export class ApiAuthService {
return {
orgId,
+ organizationCreatedAt,
cloudConfig,
cloudFreeTierUsageThresholdState,
};
@@ -503,13 +513,18 @@ export class ApiAuthService {
} | null;
},
) {
- const { orgId, cloudConfig, cloudFreeTierUsageThresholdState } =
- this.extractOrgIdAndCloudConfig(apiKeyAndOrganisation);
+ const {
+ orgId,
+ organizationCreatedAt,
+ cloudConfig,
+ cloudFreeTierUsageThresholdState,
+ } = this.extractOrgIdAndCloudConfig(apiKeyAndOrganisation);
const newApiKey = OrgEnrichedApiKey.parse({
...apiKeyAndOrganisation,
createdAt: apiKeyAndOrganisation.createdAt?.toISOString(),
orgId,
+ organizationCreatedAt: organizationCreatedAt.toISOString(),
plan: getOrganizationPlanServerSide(cloudConfig),
rateLimitOverrides: cloudConfig?.rateLimitOverrides,
isIngestionSuspended: cloudFreeTierUsageThresholdState === "BLOCKED",
diff --git a/web/src/features/public-api/server/createAuthedProjectAPIRoute.ts b/web/src/features/public-api/server/createAuthedProjectAPIRoute.ts
index 13e5b942b1..7cdbf8293c 100644
--- a/web/src/features/public-api/server/createAuthedProjectAPIRoute.ts
+++ b/web/src/features/public-api/server/createAuthedProjectAPIRoute.ts
@@ -28,6 +28,7 @@ import {
} from "./structuredPublicApiErrorContract";
import { clickHouseRouteForRequest } from "@/src/features/public-api/server/clickHouseRequestTags";
import { attachDeprecation } from "@/src/features/public-api/server/deprecations";
+import { applyLegacyApiOrganizationCutoff } from "@/src/features/public-api/server/legacyApiOrganizationCutoff";
import { type RouteAccessLevel } from "@/src/features/public-api/server/verifyProjectApiKeyAuth";
import { shadowAuth } from "@/src/features/public-api/server/shadowAuth";
import { type ProjectAction } from "@/src/features/auth/policy/types";
@@ -216,6 +217,17 @@ export const createAuthedProjectAPIRoute = <
});
}
+ const cutoffRejection = applyLegacyApiOrganizationCutoff({
+ req,
+ deprecation,
+ scope: auth.scope,
+ routeName: routeConfig.name,
+ });
+ if (cutoffRejection) {
+ res.status(410).json(cutoffRejection.body);
+ return;
+ }
+
logger.debug(
`Request to route ${routeConfig.name} projectId ${auth.scope.projectId}`,
);
diff --git a/web/src/features/public-api/server/legacyApiOrganizationCutoff.ts b/web/src/features/public-api/server/legacyApiOrganizationCutoff.ts
new file mode 100644
index 0000000000..0cc4eef943
--- /dev/null
+++ b/web/src/features/public-api/server/legacyApiOrganizationCutoff.ts
@@ -0,0 +1,69 @@
+import { type NextApiRequest } from "next";
+import { type ApiDeprecationInfo } from "@langfuse/shared";
+import {
+ logger,
+ recordIncrement,
+ type ApiAccessScopeWithOptionalApiKeyId,
+} from "@langfuse/shared/src/server";
+
+import { env } from "@/src/env.mjs";
+import { clickHouseRouteForRequest } from "@/src/features/public-api/server/clickHouseRequestTags";
+import { attachDeprecation } from "@/src/features/public-api/server/deprecations";
+
+const utcDateFormatter = new Intl.DateTimeFormat("en-US", {
+ year: "numeric",
+ month: "long",
+ day: "numeric",
+ timeZone: "UTC",
+});
+
+/** applyLegacyApiOrganizationCutoff returns a 410 body when a Cloud organization created at or after the cutoff hits a deprecated GET. Self-hosted requests never carry `deprecation`, so they are unaffected. POST ingestion is not a GET and is never rejected here. */
+export function applyLegacyApiOrganizationCutoff(params: {
+ req: NextApiRequest;
+ deprecation: ApiDeprecationInfo | undefined;
+ scope: ApiAccessScopeWithOptionalApiKeyId;
+ routeName: string;
+}): { body: unknown } | null {
+ if (env.LANGFUSE_API_ORGANIZATION_CUTOFF_ENABLED !== "true") {
+ return null;
+ }
+ if (params.req.method !== "GET" || !params.deprecation) {
+ return null;
+ }
+ if (!params.scope.orgId || !params.scope.organizationCreatedAt) {
+ return null;
+ }
+
+ const cutoff = new Date(env.LANGFUSE_API_ORGANIZATION_CUTOFF_DATE);
+ const organizationCreatedAt = new Date(params.scope.organizationCreatedAt);
+ if (organizationCreatedAt < cutoff) {
+ return null;
+ }
+
+ const apiPath = clickHouseRouteForRequest(params.req);
+ recordIncrement("langfuse.public_api.legacy_get_rejected", 1);
+ logger.info(
+ "Rejected legacy GET API request for organization created at or after cutoff",
+ {
+ orgId: params.scope.orgId,
+ projectId: params.scope.projectId,
+ apiRoute: params.routeName,
+ apiPath,
+ organizationCreatedAt: params.scope.organizationCreatedAt,
+ cutoff: cutoff.toISOString(),
+ },
+ );
+
+ return {
+ body: attachDeprecation(
+ {
+ error: "LEGACY_API_UNAVAILABLE_FOR_NEW_ORGANIZATION",
+ message: `${apiPath} is a legacy API that is not available to organizations created on or after ${utcDateFormatter.format(cutoff)}. Migrate this request to ${params.deprecation.replacement}. See the migration documentation at ${params.deprecation.docsUrl}.`,
+ requestedEndpoint: apiPath,
+ replacementEndpoint: params.deprecation.replacement,
+ documentationUrl: params.deprecation.docsUrl,
+ },
+ params.deprecation,
+ ),
+ };
+}
diff --git a/web/src/features/public-api/server/toApiAccessScope.ts b/web/src/features/public-api/server/toApiAccessScope.ts
index f7445376da..c374f6291a 100644
--- a/web/src/features/public-api/server/toApiAccessScope.ts
+++ b/web/src/features/public-api/server/toApiAccessScope.ts
@@ -44,6 +44,7 @@ function apiKeyScope(
const [org] = principal.organizations;
return {
orgId: target.orgId,
+ organizationCreatedAt: org.organizationCreatedAt,
projectId: target.projectId,
plan: org.plan,
rateLimitOverrides: org.rateLimitOverrides,