feat(webapp): add multiple environment API key management (#4390)

## Summary

Projects can create, inspect, expire, and revoke multiple API keys for
each environment. Plaintext values are shown only at creation; stored
credentials are hashed and the API keys page displays only an obfuscated
suffix afterward.

Self-hosted installations support full-access additional keys by
default. Authorization extensions can provide additional access presets
and optional task selection. Additional keys can also mint scoped public
access tokens through the Trigger.dev API without receiving the
environment signing key.

## Feature notes
- Only admin+ can create API keys (Developer can make in Development
branch).
- JWT self-signing will be a server call when used with new `_ak_` keys.
- JWTs with long expiry can keep working even with api key deleted (gets
priveleges from api key, signed with root key)
- Unfiltered session listings intentionally preserve the existing broad
task-read behavior. Filtered listings enforce task-level scopes for
every requested task.
- Buffered runs without a task identifier are not safely authorizable,
so cancel/replay requests fail closed rather than resolving an unscoped
run.
- Batch and waitpoint endpoints intentionally return server-minted,
narrowly scoped public tokens to all callers. These tokens have bounded
lifetimes and may remain valid until expiry after API-key revocation.

## Deployment notes

Deploy the management UI and public-token endpoint with new key creation
disabled. Enable creation for selected organizations after the
authentication path and released SDK have been verified, then expand
availability gradually.

Revoking an API key prevents new bearer requests and new token minting.
Public tokens already minted by that key remain valid until their own
expiration because they are signed by the environment signing key.

## TODO
- [x] Add "Created by" to the key table
- [x] Document that streamed batch ingestion is non-atomic and may
 partially accept items before a validation or authorization error.

## Follow-ups

- [x] Add an organization-level feature flag for the API key management
UI and creation action.
- [x] Document rollout ordering: enable additional-key lookup before
enabling issuance.
- [x] Add a system-wide gate that can stop new key issuance without
disabling authentication for existing keys.
- [x] Replace the generic SDK compatibility warning with the first
published compatible version. Old SDK will mint an unusable token if
given an `_ak_` key.
- [x] Add public documentation covering creation, storage, expiration,
revocation, SDK compatibility, and public-token lifetime behavior.
- [x] Add observability for key creation, revocation, policy preparation
failures, and public-token mint failures.
- [ ] Exercise create, copy-once display, authenticate, mint, expire,
and revoke flows end to end before broad enablement.

Author: carderne

.server-changes/api-key-deploy-envvars-presets.md

@@ -0,0 +1,6 @@
+---
+area: webapp
+type: feature
+---
+
+Self-hosted deployments can now create multiple full-access API keys for each environment.

.server-changes/public-token-additional-api-keys.md

@@ -0,0 +1,6 @@
+---
+area: webapp
+type: feature
+---
+
+Additional environment API keys can now create scoped public access tokens.

apps/webapp/app/consts.ts

@@ -10,6 +10,7 @@ export const RUN_CHUNK_EXECUTION_BUFFER = 350;
 export const MAX_RUN_CHUNK_EXECUTION_LIMIT = 120000; // 2 minutes
 export const VERCEL_RESPONSE_TIMEOUT_STATUS_CODES = [408, 504];
 export const MAX_BATCH_TRIGGER_ITEMS = 100;
+export const MAX_API_KEY_TASK_IDENTIFIERS = 10;
 export const MAX_TASK_RUN_ATTEMPTS = 250;
 export const BULK_ACTION_RUN_LIMIT = 250;
 export const MAX_JOB_RUN_EXECUTION_COUNT = 250;

apps/webapp/app/models/api-key.server.ts

@@ -1,9 +1,18 @@
-import type { RuntimeEnvironment } from "@trigger.dev/database";
-import { prisma } from "~/db.server";
+import type { PrismaClient, RuntimeEnvironment } from "@trigger.dev/database";
+import type { HostRbacController } from "@trigger.dev/rbac";
+import { trail } from "agentcrumbs"; // @crumbs
 import { customAlphabet } from "nanoid";
+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";
 
+const crumb = trail("webapp"); // @crumbs
+
 const apiKeyId = customAlphabet(
   "1234567890abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ",
   12
@@ -94,8 +103,175 @@ export async function regenerateApiKey({ userId, environmentId }: RegenerateAPIK
   return updatedEnviroment;
 }
 
+export async function createEnvironmentApiKey(
+  {
+    environmentId,
+    taskEnvironmentId,
+    userId,
+    name,
+    expiresAt,
+    presetId,
+    taskIdentifiers,
+  }: {
+    environmentId: string;
+    taskEnvironmentId: string;
+    userId: string;
+    name: string;
+    expiresAt?: Date;
+    presetId: string;
+    taskIdentifiers?: string[];
+  },
+  {
+    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({
+    where: {
+      id: environmentId,
+      organization: { members: { some: { userId } } },
+    },
+    select: { id: true, type: true, organizationId: true },
+  });
+
+  if (!environment) {
+    throw new Error("Environment not found");
+  }
+
+  const canIssue =
+    issuanceAllowed ??
+    ((organizationId) => canIssueAdditionalApiKeys(organizationId, prismaClient));
+  if (!(await canIssue(environment.organizationId))) {
+    throw new Error("Creating additional API keys is not enabled.");
+  }
+
+  if (expiresAt && expiresAt.getTime() <= Date.now()) {
+    throw new Error("Expiration must be in the future");
+  }
+
+  const selectedTasks = [...new Set(taskIdentifiers?.map((task) => task.trim()).filter(Boolean))];
+
+  if (selectedTasks.length > MAX_API_KEY_TASK_IDENTIFIERS) {
+    throw new Error(`You can select at most ${MAX_API_KEY_TASK_IDENTIFIERS} tasks for an API key`);
+  }
+  if (selectedTasks.length > 0) {
+    const matchingTasks = await prismaClient.taskIdentifier.count({
+      where: {
+        runtimeEnvironmentId: taskEnvironmentId,
+        slug: { in: selectedTasks },
+        runtimeEnvironment: {
+          OR: [{ id: environment.id }, { parentEnvironmentId: environment.id }],
+        },
+      },
+    });
+
+    if (matchingTasks !== selectedTasks.length) {
+      throw new Error("One or more selected tasks are not available in this environment");
+    }
+  }
+
+  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 (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,
+    environmentId,
+    presetId: apiKey.presetId,
+  }); // @crumbs
+
+  return { apiKey, plaintext: generated.apiKey };
+}
+
+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
+}
+
 export function createApiKeyForEnv(envType: RuntimeEnvironment["type"]) {
-  return `tr_${envSlug(envType)}_${apiKeyId(20)}`;
+  return generateRootApiKey(envType).apiKey;
 }
 
 export function createPkApiKeyForEnv(envType: RuntimeEnvironment["type"]) {