feat(webapp): add API key lifecycle metrics

carderne · carderne · commit ca744a5c8483 · 2026-07-28T12:32:15.000+01:00
Record bounded outcomes for additional key creation, policy preparation, revocation, and public-token minting.
diff --git a/apps/webapp/app/models/api-key.server.ts b/apps/webapp/app/models/api-key.server.ts
@@ -10,6 +10,7 @@ import { MAX_API_KEY_TASK_IDENTIFIERS } from "~/consts";
 import { prisma } from "~/db.server";
 import { RuntimeEnvironmentType } from "~/database-types";
 import { canIssueAdditionalApiKeys } from "~/services/additionalApiKeyIssuance.server";
+import { apiKeyTelemetry, type ApiKeyTelemetry } from "~/services/apiKeyTelemetry.server";
 import { rbac } from "~/services/rbac.server";
 import { generateAdditionalApiKey, generateRootApiKey } from "~/utils/apiKeys";
 import { controlPlaneResolver } from "~/v3/runOpsMigration/controlPlaneResolver.server";
@@ -131,13 +132,15 @@ export async function createEnvironmentApiKey(
     prismaClient = prisma,
     rbacController = rbac,
     issuanceAllowed,
+    telemetryRecorder = apiKeyTelemetry,
   }: {
     prismaClient?: Pick<
       PrismaClient,
       "apiKey" | "featureFlag" | "organization" | "runtimeEnvironment" | "taskIdentifier"
     >;
     rbacController?: Pick<HostRbacController, "prepareApiKeyPolicy">;
     issuanceAllowed?: (organizationId: string) => Promise<boolean>;
+    telemetryRecorder?: ApiKeyTelemetry;
   } = {}
 ) {
   const environment = await prismaClient.runtimeEnvironment.findFirst({
@@ -184,29 +187,45 @@ export async function createEnvironmentApiKey(
     }
   }
 
-  const prepared = await rbacController.prepareApiKeyPolicy({
-    organizationId: environment.organizationId,
-    presetId,
-    taskIdentifiers: selectedTasks.length > 0 ? selectedTasks : undefined,
-  });
+  let prepared: Awaited<ReturnType<typeof rbacController.prepareApiKeyPolicy>>;
+  try {
+    prepared = await rbacController.prepareApiKeyPolicy({
+      organizationId: environment.organizationId,
+      presetId,
+      taskIdentifiers: selectedTasks.length > 0 ? selectedTasks : undefined,
+    });
+  } catch (error) {
+    telemetryRecorder.recordOperation("prepare_policy", "error", "policy_error");
+    throw error;
+  }
 
   if (!prepared.ok) {
+    telemetryRecorder.recordOperation("prepare_policy", "rejected", "policy_rejected");
     throw new Error(prepared.error);
   }
+  telemetryRecorder.recordOperation("prepare_policy", "success");
 
   const generated = generateAdditionalApiKey(environment.type);
-  const apiKey = await prismaClient.apiKey.create({
-    data: {
-      name,
-      keyHash: generated.keyHash,
-      lastFour: generated.lastFour,
-      runtimeEnvironmentId: environment.id,
-      createdByUserId: userId,
-      expiresAt,
-      presetId: prepared.policy.presetId,
-      scopes: prepared.policy.scopes,
-    },
-  });
+  const apiKey = await (async () => {
+    try {
+      return await prismaClient.apiKey.create({
+        data: {
+          name,
+          keyHash: generated.keyHash,
+          lastFour: generated.lastFour,
+          runtimeEnvironmentId: environment.id,
+          createdByUserId: userId,
+          expiresAt,
+          presetId: prepared.policy.presetId,
+          scopes: prepared.policy.scopes,
+        },
+      });
+    } catch (error) {
+      telemetryRecorder.recordOperation("create", "error", "database_error");
+      throw error;
+    }
+  })();
+  telemetryRecorder.recordOperation("create", "success");
 
   crumb("environment API key created", {
     apiKeyId: apiKey.id,
@@ -217,26 +236,44 @@ export async function createEnvironmentApiKey(
   return { apiKey, plaintext: generated.apiKey };
 }
 
-export async function revokeEnvironmentApiKey({
-  environmentId,
-  apiKeyId,
-}: {
-  environmentId: string;
-  apiKeyId: string;
-}) {
-  const result = await prisma.apiKey.updateMany({
-    where: {
-      id: apiKeyId,
-      runtimeEnvironmentId: environmentId,
-      revokedAt: null,
-    },
-    data: { revokedAt: new Date() },
-  });
+export async function revokeEnvironmentApiKey(
+  {
+    environmentId,
+    apiKeyId,
+  }: {
+    environmentId: string;
+    apiKeyId: string;
+  },
+  {
+    prismaClient = prisma,
+    telemetryRecorder = apiKeyTelemetry,
+  }: {
+    prismaClient?: Pick<PrismaClient, "apiKey">;
+    telemetryRecorder?: ApiKeyTelemetry;
+  } = {}
+) {
+  const result = await (async () => {
+    try {
+      return await prismaClient.apiKey.updateMany({
+        where: {
+          id: apiKeyId,
+          runtimeEnvironmentId: environmentId,
+          revokedAt: null,
+        },
+        data: { revokedAt: new Date() },
+      });
+    } catch (error) {
+      telemetryRecorder.recordOperation("revoke", "error", "database_error");
+      throw error;
+    }
+  })();
 
   if (result.count !== 1) {
+    telemetryRecorder.recordOperation("revoke", "rejected", "not_found_or_revoked");
     throw new Error("API key not found or already revoked");
   }
 
+  telemetryRecorder.recordOperation("revoke", "success");
   crumb("environment API key revoked", { apiKeyId, environmentId }); // @crumbs
 }
 
diff --git a/apps/webapp/app/services/apiKeyTelemetry.server.ts b/apps/webapp/app/services/apiKeyTelemetry.server.ts
@@ -0,0 +1,49 @@
+import { getMeter } from "@internal/tracing";
+import { singleton } from "~/utils/singleton";
+
+export type ApiKeyOperation = "create" | "prepare_policy" | "revoke";
+export type ApiKeyOperationResult = "success" | "rejected" | "error";
+export type ApiKeyOperationReason =
+  | "none"
+  | "database_error"
+  | "not_found_or_revoked"
+  | "policy_rejected"
+  | "policy_error";
+
+export type PublicTokenMintResult = "success" | "rejected" | "error";
+export type PublicTokenMintReason =
+  | "none"
+  | "invalid_body"
+  | "scope_not_allowed"
+  | "invalid_expiration"
+  | "expiration_not_future"
+  | "expiration_too_long"
+  | "signing_failed";
+
+const telemetry = singleton("apiKeyTelemetry", () => {
+  const meter = getMeter("api-key");
+
+  return {
+    operations: meter.createCounter("api_key.operations", {
+      description: "Additional environment API key management operations",
+    }),
+    publicTokenMintAttempts: meter.createCounter("public_token.mint_attempts", {
+      description: "Public access token mint attempts using environment API keys",
+    }),
+  };
+});
+
+export const apiKeyTelemetry = {
+  recordOperation(
+    operation: ApiKeyOperation,
+    result: ApiKeyOperationResult,
+    reason: ApiKeyOperationReason = "none"
+  ) {
+    telemetry.operations.add(1, { operation, result, reason });
+  },
+  recordPublicTokenMint(result: PublicTokenMintResult, reason: PublicTokenMintReason = "none") {
+    telemetry.publicTokenMintAttempts.add(1, { result, reason });
+  },
+};
+
+export type ApiKeyTelemetry = typeof apiKeyTelemetry;
diff --git a/apps/webapp/app/services/publicTokens.server.ts b/apps/webapp/app/services/publicTokens.server.ts
@@ -3,6 +3,7 @@ import type { RoleBaseAccessController } from "@trigger.dev/rbac";
 import { resolveJwtSigningKey, scopesWithinAbility } from "@trigger.dev/rbac";
 import { json } from "@remix-run/server-runtime";
 import { z } from "zod";
+import { apiKeyTelemetry, type ApiKeyTelemetry } from "~/services/apiKeyTelemetry.server";
 import { rbac } from "~/services/rbac.server";
 
 // Public access tokens may be valid for at most 30 days.
@@ -53,7 +54,8 @@ function expirationTimestamp(expirationTime: string | number, now: number): numb
 
 export async function handlePublicTokenRequest(
   request: Request,
-  controller: Pick<RoleBaseAccessController, "authenticateBearer"> = rbac
+  controller: Pick<RoleBaseAccessController, "authenticateBearer"> = rbac,
+  telemetryRecorder: ApiKeyTelemetry = apiKeyTelemetry
 ) {
   // Public JWTs are intentionally not enabled here. Only API keys may mint tokens.
   const authResult = await controller.authenticateBearer(request);
@@ -65,11 +67,13 @@ export async function handlePublicTokenRequest(
   try {
     body = await request.json();
   } catch {
+    telemetryRecorder.recordPublicTokenMint("rejected", "invalid_body");
     return json({ error: "Invalid request body" }, { status: 400 });
   }
 
   const parsedBody = RequestBodySchema.safeParse(body);
   if (!parsedBody.success) {
+    telemetryRecorder.recordPublicTokenMint("rejected", "invalid_body");
     return json(
       { error: "Invalid request body", issues: parsedBody.error.issues },
       { status: 400 }
@@ -78,6 +82,7 @@ export async function handlePublicTokenRequest(
 
   const scopeCheck = scopesWithinAbility(parsedBody.data.scopes, authResult.ability);
   if (!scopeCheck.ok) {
+    telemetryRecorder.recordPublicTokenMint("rejected", "scope_not_allowed");
     return json(
       {
         error: "Requested scopes exceed the API key's access",
@@ -92,32 +97,42 @@ export async function handlePublicTokenRequest(
   const now = Math.floor(Date.now() / 1000);
   const expiresAt = expirationTimestamp(expirationTime, now);
   if (expiresAt === undefined) {
+    telemetryRecorder.recordPublicTokenMint("rejected", "invalid_expiration");
     return json({ error: "Invalid expiration time" }, { status: 400 });
   }
   // `expirationTimestamp` accepts past values ("-5m", "5m ago"), which would
   // otherwise mint an already-expired token behind a 200.
   if (expiresAt <= now) {
+    telemetryRecorder.recordPublicTokenMint("rejected", "expiration_not_future");
     return json({ error: "Expiration time must be in the future" }, { status: 400 });
   }
   if (expiresAt - now > MAX_PUBLIC_TOKEN_LIFETIME_SECONDS) {
+    telemetryRecorder.recordPublicTokenMint("rejected", "expiration_too_long");
     return json({ error: "Expiration time cannot exceed 30 days" }, { status: 400 });
   }
 
-  const token = await generateJWT({
-    secretKey: resolveJwtSigningKey(authResult.environment),
-    payload: {
-      sub: authResult.environment.id,
-      pub: true,
-      scopes: parsedBody.data.scopes,
-      ...(parsedBody.data.oneTimeUse ? { otu: true } : {}),
-      ...(parsedBody.data.realtime ? { realtime: parsedBody.data.realtime } : {}),
-    },
-    // Pass the absolute `exp` validated above, not the original string.
-    // `generateJWT` hands the string to jose's own parser, which would leave
-    // the 30-day cap enforced against a different computation than the one
-    // that actually sets the claim.
-    expirationTime: expiresAt,
-  });
+  let token: string;
+  try {
+    token = await generateJWT({
+      secretKey: resolveJwtSigningKey(authResult.environment),
+      payload: {
+        sub: authResult.environment.id,
+        pub: true,
+        scopes: parsedBody.data.scopes,
+        ...(parsedBody.data.oneTimeUse ? { otu: true } : {}),
+        ...(parsedBody.data.realtime ? { realtime: parsedBody.data.realtime } : {}),
+      },
+      // Pass the absolute `exp` validated above, not the original string.
+      // `generateJWT` hands the string to jose's own parser, which would leave
+      // the 30-day cap enforced against a different computation than the one
+      // that actually sets the claim.
+      expirationTime: expiresAt,
+    });
+  } catch (error) {
+    telemetryRecorder.recordPublicTokenMint("error", "signing_failed");
+    throw error;
+  }
 
+  telemetryRecorder.recordPublicTokenMint("success");
   return json({ token });
 }
diff --git a/apps/webapp/test/createEnvironmentApiKey.test.ts b/apps/webapp/test/createEnvironmentApiKey.test.ts
@@ -3,7 +3,8 @@ import type { PrismaClient } from "@trigger.dev/database";
 import rbacPlugin, { type RoleBaseAccessController } from "@trigger.dev/rbac";
 import { expect, vi } from "vitest";
 import { MAX_API_KEY_TASK_IDENTIFIERS } from "~/consts";
-import { createEnvironmentApiKey } from "~/models/api-key.server";
+import { createEnvironmentApiKey, revokeEnvironmentApiKey } from "~/models/api-key.server";
+import type { ApiKeyTelemetry } from "~/services/apiKeyTelemetry.server";
 import { FEATURE_FLAG } from "~/v3/featureFlags";
 import {
   createRuntimeEnvironment,
@@ -19,6 +20,13 @@ function policyController(
   return { prepareApiKeyPolicy: vi.fn(implementation) };
 }
 
+function telemetryRecorder(): ApiKeyTelemetry {
+  return {
+    recordOperation: vi.fn(),
+    recordPublicTokenMint: vi.fn(),
+  };
+}
+
 async function setup(prisma: PrismaClient) {
   const { organization, project, user } = await createTestOrgProjectWithMember(prisma);
   const [environment] = await Promise.all([
@@ -77,6 +85,7 @@ containerTest(
 containerTest("standalone fallback creates one explicit full-access key", async ({ prisma }) => {
   const { user, environment } = await setup(prisma);
   const fallback = rbacPlugin.create({ primary: prisma, replica: prisma }, { forceFallback: true });
+  const telemetry = telemetryRecorder();
   const expiresAt = new Date(Date.now() + 30 * 24 * 60 * 60 * 1000);
 
   const result = await createEnvironmentApiKey(
@@ -88,9 +97,11 @@ containerTest("standalone fallback creates one explicit full-access key", async
       expiresAt,
       presetId: "FULL_ACCESS",
     },
-    { prismaClient: prisma, rbacController: fallback }
+    { prismaClient: prisma, rbacController: fallback, telemetryRecorder: telemetry }
   );
 
+  expect(telemetry.recordOperation).toHaveBeenNthCalledWith(1, "prepare_policy", "success");
+  expect(telemetry.recordOperation).toHaveBeenNthCalledWith(2, "create", "success");
   expect(result.plaintext).toMatch(/^tr_prod_sk_[A-Za-z0-9]{24}$/);
   expect(result.apiKey).toMatchObject({
     presetId: null,
@@ -102,6 +113,31 @@ containerTest("standalone fallback creates one explicit full-access key", async
   ).resolves.toBe(1);
 });
 
+containerTest("records successful API key revocation", async ({ prisma }) => {
+  const { user, environment } = await setup(prisma);
+  const apiKey = await prisma.apiKey.create({
+    data: {
+      name: "Revoke me",
+      keyHash: uniqueId("hash"),
+      lastFour: "last",
+      runtimeEnvironmentId: environment.id,
+      createdByUserId: user.id,
+      scopes: ["admin"],
+    },
+  });
+  const telemetry = telemetryRecorder();
+
+  await revokeEnvironmentApiKey(
+    { environmentId: environment.id, apiKeyId: apiKey.id },
+    { prismaClient: prisma, telemetryRecorder: telemetry }
+  );
+
+  expect(telemetry.recordOperation).toHaveBeenCalledWith("revoke", "success");
+  await expect(prisma.apiKey.findUnique({ where: { id: apiKey.id } })).resolves.toMatchObject({
+    revokedAt: expect.any(Date),
+  });
+});
+
 containerTest("persists trusted full-access and restricted cloud policies", async ({ prisma }) => {
   const { organization, user, environment } = await setup(prisma);
   const fullAccessController = policyController(async () => ({
@@ -155,6 +191,7 @@ containerTest("policy preparation failure inserts no credential", async ({ prism
     ok: false,
     error: "This API key access preset is not available on your plan",
   }));
+  const telemetry = telemetryRecorder();
 
   await expect(
     createEnvironmentApiKey(
@@ -165,10 +202,15 @@ containerTest("policy preparation failure inserts no credential", async ({ prism
         name: "Unavailable",
         presetId: "RESTRICTED",
       },
-      { prismaClient: prisma, rbacController: controller }
+      { prismaClient: prisma, rbacController: controller, telemetryRecorder: telemetry }
     )
   ).rejects.toThrow("not available on your plan");
 
+  expect(telemetry.recordOperation).toHaveBeenCalledWith(
+    "prepare_policy",
+    "rejected",
+    "policy_rejected"
+  );
   await expect(
     prisma.apiKey.count({ where: { runtimeEnvironmentId: environment.id } })
   ).resolves.toBe(0);
diff --git a/apps/webapp/test/publicTokensRoute.test.ts b/apps/webapp/test/publicTokensRoute.test.ts
