Skip to content

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

feat(ai-gateway): let owners and admins issue gateway keys as a service account (#19214)

Tobias Wochingerceb2588cb463
diff --git a/web/src/__tests__/server/ai-gateway-control-plane.servertest.ts b/web/src/__tests__/server/ai-gateway-control-plane.servertest.ts
index 37381c6f3d..91524d122e 100644
--- a/web/src/__tests__/server/ai-gateway-control-plane.servertest.ts
+++ b/web/src/__tests__/server/ai-gateway-control-plane.servertest.ts
@@ -764,6 +764,36 @@ describe("AI gateway control plane", () => {
).rejects.toMatchObject({ code: "FORBIDDEN" });
});
+ it("lets only gateway managers issue service-account keys", async () => {
+ const owner = await prepare();
+ const member = await createCallerForOrganizationRole(owner, Role.MEMBER);
+
+ const serviceKey = await owner.caller.aiGateway.createApiKey({
+ orgId: owner.org.id,
+ name: "Service key",
+ metadata: {},
+ issuedAs: "serviceAccount",
+ });
+ const ownerList = await owner.caller.aiGateway.listApiKeys({
+ orgId: owner.org.id,
+ });
+ expect(
+ ownerList.data.find(({ apiKey }) => apiKey.id === serviceKey.id)?.apiKey
+ .user,
+ ).toBeNull();
+
+ await expect(
+ member.aiGateway.createApiKey({
+ orgId: owner.org.id,
+ metadata: {},
+ issuedAs: "serviceAccount",
+ }),
+ ).rejects.toMatchObject({ code: "FORBIDDEN" });
+ expect(
+ (await member.aiGateway.listApiKeys({ orgId: owner.org.id })).data,
+ ).toEqual([]);
+ });
+
it.each(["legacy", "shadow"] as const)(
"keeps gateway API key creation admin-only when API_AUTH_MIGRATION is %s",
async (migration) => {
@@ -776,6 +806,8 @@ describe("AI gateway control plane", () => {
Role.MEMBER,
);
+ const admin = await createCallerForOrganizationRole(owner, Role.ADMIN);
+
await expect(
member.aiGateway.createApiKey({ orgId: owner.org.id, metadata: {} }),
).rejects.toMatchObject({ code: "FORBIDDEN" });
@@ -787,6 +819,22 @@ describe("AI gateway control plane", () => {
).resolves.toMatchObject({
secretKey: expect.stringMatching(/^sk-lf-/),
});
+ await expect(
+ admin.aiGateway.createApiKey({
+ orgId: owner.org.id,
+ metadata: {},
+ issuedAs: "serviceAccount",
+ }),
+ ).rejects.toMatchObject({ code: "FORBIDDEN" });
+ await expect(
+ owner.caller.aiGateway.createApiKey({
+ orgId: owner.org.id,
+ metadata: {},
+ issuedAs: "serviceAccount",
+ }),
+ ).resolves.toMatchObject({
+ secretKey: expect.stringMatching(/^sk-lf-/),
+ });
} finally {
Object.assign(env, { API_AUTH_MIGRATION: originalMigration });
}
@@ -827,6 +875,7 @@ describe("AI gateway control plane", () => {
const key = await apiKeyService.create({
organizationId: org.id,
metadata: {},
+ issuedAs: "user",
session,
});
diff --git a/web/src/__tests__/server/ai-gateway-user-bound-api-keys.servertest.ts b/web/src/__tests__/server/ai-gateway-user-bound-api-keys.servertest.ts
index 33b970202f..74fa6c2e0e 100644
--- a/web/src/__tests__/server/ai-gateway-user-bound-api-keys.servertest.ts
+++ b/web/src/__tests__/server/ai-gateway-user-bound-api-keys.servertest.ts
@@ -153,12 +153,58 @@ describe("user-bound API keys", () => {
const key = await new GatewayApiKeyService(prisma).create({
organizationId: org.id,
metadata: {},
+ issuedAs: "user",
session: orgSession(user, org, Role.MEMBER),
});
expect(await boundUserOf(key.id)).toBe(user.id);
});
+ it("leaves a service-account key unbound so it outlives the creator", async () => {
+ const org = await createOrg();
+ const user = await createUser();
+ await prisma.organizationMembership.create({
+ data: { orgId: org.id, userId: user.id, role: Role.ADMIN },
+ });
+
+ const key = await new GatewayApiKeyService(prisma).create({
+ organizationId: org.id,
+ metadata: {},
+ issuedAs: "serviceAccount",
+ session: orgSession(user, org, Role.ADMIN),
+ });
+ await prisma.$transaction((tx) =>
+ deleteUserBoundApiKeys(tx, { userId: user.id, orgId: org.id }),
+ );
+
+ expect(await boundUserOf(key.id)).toBeNull();
+ expect(
+ await prisma.apiKey.findUniqueOrThrow({
+ where: { id: key.id },
+ select: { createdByUserId: true },
+ }),
+ ).toEqual({ createdByUserId: user.id });
+ });
+
+ it("rejects a service-account key from a creator whose current role cannot manage the gateway", async () => {
+ const org = await createOrg();
+ const user = await createUser();
+ await prisma.organizationMembership.create({
+ data: { orgId: org.id, userId: user.id, role: Role.MEMBER },
+ });
+ const before = await existingKeyIds();
+
+ await expect(
+ new GatewayApiKeyService(prisma).create({
+ organizationId: org.id,
+ metadata: {},
+ issuedAs: "serviceAccount",
+ session: orgSession(user, org, Role.ADMIN),
+ }),
+ ).rejects.toThrow(ForbiddenError);
+ expect(await existingKeyIds()).toEqual(before);
+ });
+
it("rejects a creator whose current role cannot invoke the gateway", async () => {
const org = await createOrg();
const user = await createUser();
@@ -171,6 +217,7 @@ describe("user-bound API keys", () => {
new GatewayApiKeyService(prisma).create({
organizationId: org.id,
metadata: {},
+ issuedAs: "user",
session: orgSession(user, org, Role.OWNER),
}),
).rejects.toThrow(ForbiddenError);
@@ -186,6 +233,7 @@ describe("user-bound API keys", () => {
new GatewayApiKeyService(prisma).create({
organizationId: org.id,
metadata: {},
+ issuedAs: "user",
session: orgSession(user, org, Role.OWNER),
}),
).rejects.toThrow(ForbiddenError);
diff --git a/web/src/features/ai-gateway/components/GatewayApiKeysPage/components/CreateGatewayApiKeyDialogController/CreateGatewayApiKeyDialogController.tsx b/web/src/features/ai-gateway/components/GatewayApiKeysPage/components/CreateGatewayApiKeyDialogController/CreateGatewayApiKeyDialogController.tsx
index 6d50547be9..25bd457c10 100644
--- a/web/src/features/ai-gateway/components/GatewayApiKeysPage/components/CreateGatewayApiKeyDialogController/CreateGatewayApiKeyDialogController.tsx
+++ b/web/src/features/ai-gateway/components/GatewayApiKeysPage/components/CreateGatewayApiKeyDialogController/CreateGatewayApiKeyDialogController.tsx
@@ -3,6 +3,7 @@ import { useState, type ReactNode } from "react";
import { ChevronRight, Plus, X } from "@langfuse/icons";
import { Alert } from "@/src/components/design-system/Alert/Alert";
+import { Tabs } from "@/src/components/design-system/Tabs/Tabs";
import { Button } from "@/src/components/ui/button";
import {
Collapsible,
@@ -25,6 +26,7 @@ import {
resolveApiKeyExpiration,
} from "@/src/features/apiKey";
import { GeneratedKeyContent } from "@/src/features/ai-gateway/components/GatewayApiKeysPage/components/GeneratedKeyContent";
+import { useHasOrganizationAccess } from "@/src/features/rbac";
import {
api,
reportNonTrpcError,
@@ -37,6 +39,13 @@ type MetadataField = {
value: string;
};
+type IssuedAs = "user" | "serviceAccount";
+
+const issuedAsDescriptions: Record<IssuedAs, string> = {
+ user: "Stops working if you leave the organization.",
+ serviceAccount: "Keeps working when people leave the organization.",
+};
+
export function CreateGatewayApiKeyDialogController({
organizationId,
children,
@@ -53,6 +62,11 @@ export function CreateGatewayApiKeyDialogController({
]);
const [isMetadataOpen, setIsMetadataOpen] = useState(false);
const [nextMetadataId, setNextMetadataId] = useState(2);
+ const [issuedAs, setIssuedAs] = useState<IssuedAs>("user");
+ const canIssueServiceAccountKeys = useHasOrganizationAccess({
+ organizationId,
+ scope: "gateway:manage",
+ });
const [generatedKeys, setGeneratedKeys] = useState<{
publicKey: string;
secretKey: string;
@@ -71,6 +85,7 @@ export function CreateGatewayApiKeyDialogController({
setIsMetadataOpen(false);
setGeneratedKeys(null);
setNextMetadataId(2);
+ setIssuedAs("user");
};
const metadataCount = metadata.filter((field) => field.key.trim()).length;
@@ -89,6 +104,7 @@ export function CreateGatewayApiKeyDialogController({
name: name.trim() || undefined,
metadata: metadataObject,
expiresAt,
+ issuedAs: canIssueServiceAccountKeys ? issuedAs : "user",
});
setGeneratedKeys({
publicKey: created.publicKey,
@@ -140,6 +156,35 @@ export function CreateGatewayApiKeyDialogController({
onChange={(event) => setName(event.target.value)}
/>
</div>
+ {canIssueServiceAccountKeys ? (
+ <div className="flex flex-col gap-1.5">
+ <Label>Issued as</Label>
+ <div>
+ <Tabs
+ activationMode="manual"
+ value={issuedAs}
+ onValueChange={(value) =>
+ setIssuedAs(value as IssuedAs)
+ }
+ >
+ <Tabs.List
+ variant="inset"
+ size="md"
+ aria-label="Issued as"
+ >
+ <Tabs.Trigger value="user" label="My user" />
+ <Tabs.Trigger
+ value="serviceAccount"
+ label="Service account"
+ />
+ </Tabs.List>
+ </Tabs>
+ </div>
+ <p className="text-muted-foreground text-xs">
+ {issuedAsDescriptions[issuedAs]}
+ </p>
+ </div>
+ ) : null}
<ApiKeyExpirationInput
id="gateway-key-expiry"
expiryPreset={expiryPreset}
diff --git a/web/src/features/ai-gateway/components/GatewayApiKeysPage/components/GatewayApiKeysTable/GatewayApiKeysTable.tsx b/web/src/features/ai-gateway/components/GatewayApiKeysPage/components/GatewayApiKeysTable/GatewayApiKeysTable.tsx
index f13f47cf4c..73d7c6adf3 100644
--- a/web/src/features/ai-gateway/components/GatewayApiKeysPage/components/GatewayApiKeysTable/GatewayApiKeysTable.tsx
+++ b/web/src/features/ai-gateway/components/GatewayApiKeysPage/components/GatewayApiKeysTable/GatewayApiKeysTable.tsx
@@ -66,7 +66,7 @@ export function GatewayApiKeysTable({
id: "user",
header: "User",
variant: "avatar",
- nullValue: "-",
+ nullValue: "Service account",
hideBelowMd: true,
enableResizing: false,
}),
diff --git a/web/src/features/ai-gateway/server/apiKey/gatewayApiKeyService.ts b/web/src/features/ai-gateway/server/apiKey/gatewayApiKeyService.ts
index ad0f22e67f..54d4068dc6 100644
--- a/web/src/features/ai-gateway/server/apiKey/gatewayApiKeyService.ts
+++ b/web/src/features/ai-gateway/server/apiKey/gatewayApiKeyService.ts
@@ -8,9 +8,15 @@ import {
createApiKey,
deleteApiKeyFromDb,
} from "@langfuse/shared/src/server/auth/apiKeys";
-import { OrganizationId, SystemRoleId, UserId } from "@langfuse/shared/rbac";
+import {
+ OrganizationId,
+ type OrganizationScope,
+ SystemRoleId,
+ UserId,
+} from "@langfuse/shared/rbac";
import type { Cluster, Redis } from "ioredis";
+import { env } from "@/src/env.mjs";
import { auditLog } from "@/src/features/audit-logs/server";
import type { GatewayMetadata } from "@/src/features/ai-gateway/server/provider";
import type { OrgAuthedContext } from "@/src/server/api/trpc";
@@ -18,6 +24,8 @@ import { invalidateGatewayResolveCacheForApiKey } from "@/src/features/ai-gatewa
import { hasOrganizationAccess } from "@/src/features/rbac/utils/checkOrganizationAccess";
import { GatewayApiKeyRepository } from "./gatewayApiKeyRepository";
+type GatewayApiKeyIssuedAs = "user" | "serviceAccount";
+
export class GatewayApiKeyService {
private readonly repository: GatewayApiKeyRepository;
@@ -44,6 +52,8 @@ export class GatewayApiKeyService {
name?: string;
metadata: GatewayMetadata;
expiresAt?: Date | null;
+ /** `user` keys are revoked with the creator's gateway access; `serviceAccount` keys belong to the organization. */
+ issuedAs: GatewayApiKeyIssuedAs;
session: OrgAuthedContext["session"];
}) {
const key = await this.prisma.$transaction(
@@ -51,7 +61,10 @@ export class GatewayApiKeyService {
await assertCreatorCanInvokeGateway(tx, params);
const key = await createApiKey(tx, {
tenant: OrganizationId(params.organizationId),
- scope: UserId(params.session.user.id),
+ scope:
+ params.issuedAs === "serviceAccount"
+ ? OrganizationId(params.organizationId)
+ : UserId(params.session.user.id),
role: SystemRoleId("AI_GATEWAY"),
createdBy: UserId(params.session.user.id),
name: params.name,
@@ -79,6 +92,7 @@ export class GatewayApiKeyService {
displaySecretKey: key.displaySecretKey,
note: key.note,
expiresAt: params.expiresAt ?? null,
+ issuedAs: params.issuedAs,
},
},
this.prisma,
@@ -132,10 +146,29 @@ export class GatewayApiKeyService {
}
}
+/**
+ * Service-account keys survive membership changes, so only gateway managers may
+ * issue them. Legacy public API auth ignores key roles and accepts a gateway key
+ * as an organization admin key, so outside enforce they also need the right to
+ * create organization API keys.
+ */
+export function gatewayApiKeyCreatorScopes(
+ issuedAs: GatewayApiKeyIssuedAs,
+): OrganizationScope[] {
+ if (issuedAs === "user") return ["gateway:invoke"];
+ return env.API_AUTH_MIGRATION === "enforce"
+ ? ["gateway:manage"]
+ : ["gateway:manage", "organization:CRUD_apiKeys"];
+}
+
/** assertCreatorCanInvokeGateway share-locks the creator's membership so removal and demotion order after the key insert. */
async function assertCreatorCanInvokeGateway(
tx: Prisma.TransactionClient,
- params: { organizationId: string; session: OrgAuthedContext["session"] },
+ params: {
+ organizationId: string;
+ issuedAs: GatewayApiKeyIssuedAs;
+ session: OrgAuthedContext["session"];
+ },
) {
const [membership] = await tx.$queryRaw<{ role: Role }[]>`
SELECT role FROM organization_memberships
@@ -144,12 +177,16 @@ async function assertCreatorCanInvokeGateway(
FOR SHARE
`;
if (params.session.user.admin) return;
- if (
- !membership ||
- !hasOrganizationAccess({ role: membership.role, scope: "gateway:invoke" })
- ) {
+ const allowed =
+ membership !== undefined &&
+ gatewayApiKeyCreatorScopes(params.issuedAs).every((scope) =>
+ hasOrganizationAccess({ role: membership.role, scope }),
+ );
+ if (!allowed) {
throw new ForbiddenError(
- "Only organization members who can invoke the gateway can create gateway API keys",
+ params.issuedAs === "serviceAccount"
+ ? "Your organization role cannot issue service-account gateway API keys"
+ : "Only organization members who can invoke the gateway can create gateway API keys",
);
}
}
diff --git a/web/src/features/ai-gateway/server/router.ts b/web/src/features/ai-gateway/server/router.ts
index 49d2bcc1fb..120ab4ad43 100644
--- a/web/src/features/ai-gateway/server/router.ts
+++ b/web/src/features/ai-gateway/server/router.ts
@@ -22,7 +22,10 @@ import {
} from "@langfuse/shared/src/db";
import { redis } from "@langfuse/shared/src/server";
-import { GatewayApiKeyService } from "./apiKey/gatewayApiKeyService";
+import {
+ GatewayApiKeyService,
+ gatewayApiKeyCreatorScopes,
+} from "./apiKey/gatewayApiKeyService";
import { requireGatewayEnabledForOrganization } from "./availability";
import { getGatewayBaseUrl } from "@/src/features/ai-gateway/fns/gatewayUrls/getGatewayBaseUrl";
import { GatewayConfigService } from "./config/gatewayConfigService";
@@ -379,21 +382,30 @@ export const aiGatewayRouter = createTRPCRouter({
.refine((date) => date == null || date.getTime() > Date.now(), {
message: "Expiration date must be in the future",
}),
+ issuedAs: z.enum(["user", "serviceAccount"]).default("user"),
}),
)
.mutation(async ({ input, ctx }) => {
// Legacy public API auth ignores key roles, so a gateway key passes as an
// organization admin key there; only managers may mint one outside enforce.
- if (env.API_AUTH_MIGRATION === "enforce") {
+ if (env.API_AUTH_MIGRATION === "enforce" && input.issuedAs === "user") {
requireGatewayInvoke({ session: ctx.session, orgId: input.orgId });
} else {
requireGatewayAdmin({ session: ctx.session, orgId: input.orgId });
}
+ for (const scope of gatewayApiKeyCreatorScopes(input.issuedAs)) {
+ throwIfNoOrganizationAccess({
+ session: ctx.session,
+ organizationId: input.orgId,
+ scope,
+ });
+ }
const key = await new GatewayApiKeyService(ctx.prisma, redis).create({
organizationId: input.orgId,
name: input.name,
metadata: input.metadata,
expiresAt: input.expiresAt,
+ issuedAs: input.issuedAs,
session: ctx.session,
});
return key;