feat(core,sdk): support additional environment API keys

.changeset/friendly-keys-batch-tokens.md

@@ -0,0 +1,6 @@
+---
+"@trigger.dev/core": patch
+"@trigger.dev/sdk": patch
+---
+
+Allow additional environment API keys to create scoped public access tokens through the Trigger.dev API. Use server-issued public access tokens for batch operations so environment-scoped API keys can read batch results.

packages/core/src/v3/apiClient/index.ts

@@ -1,6 +1,7 @@
 import { nanoid } from "nanoid";
 import { z } from "zod";
 import { VERSION } from "../../version.js";
+import { isAdditionalApiKey } from "../apiKeys.js";
 import type { ApiClientConfiguration } from "../apiClientManager-api.js";
 import { generateJWT } from "../jwt.js";
 import {
@@ -201,6 +202,15 @@ export type {
 
 export * from "./getBranch.js";
 
+export type CreatePublicTokenRequestBody = {
+  scopes: string[];
+  expirationTime?: string | number;
+  oneTimeUse?: boolean;
+  realtime?: { skipColumns?: string[] };
+};
+
+const CreatePublicTokenResponseBody = z.object({ token: z.string() });
+
 /**
  * Trigger.dev v3 API client
  */
@@ -230,6 +240,21 @@ export class ApiClient {
     this.futureFlags = futureFlags;
   }
 
+  /**
+   * Key for signing a public access token locally. Only root keys can do this —
+   * an additional key isn't the environment's signing material, so a token
+   * signed with one would never verify. Throw rather than return a dead token.
+   */
+  get #selfSigningKey(): string {
+    if (isAdditionalApiKey(this.accessToken)) {
+      throw new Error(
+        "This additional API key cannot self-sign public tokens, and the server did not return one. Upgrade the server or use the root API key."
+      );
+    }
+
+    return this.accessToken;
+  }
+
   get fetchClient(): typeof fetch {
     const headers = this.#getHeaders(false);
 
@@ -325,7 +350,7 @@ export class ApiClient {
         const claims = claimsHeader ? JSON.parse(claimsHeader) : undefined;
 
         const jwt = await generateJWT({
-          secretKey: this.accessToken,
+          secretKey: this.#selfSigningKey,
           payload: {
             ...claims,
             scopes: [`read:runs:${data.id}`],
@@ -359,11 +384,20 @@ export class ApiClient {
     )
       .withResponse()
       .then(async ({ data, response }) => {
+        const jwtHeader = response.headers.get("x-trigger-jwt");
+
+        if (typeof jwtHeader === "string") {
+          return {
+            ...data,
+            publicAccessToken: jwtHeader,
+          };
+        }
+
         const claimsHeader = response.headers.get("x-trigger-jwt-claims");
         const claims = claimsHeader ? JSON.parse(claimsHeader) : undefined;
 
         const jwt = await generateJWT({
-          secretKey: this.accessToken,
+          secretKey: this.#selfSigningKey,
           payload: {
             ...claims,
             scopes: [`read:batch:${data.id}`],
@@ -407,11 +441,20 @@ export class ApiClient {
     )
       .withResponse()
       .then(async ({ data, response }) => {
+        const jwtHeader = response.headers.get("x-trigger-jwt");
+
+        if (typeof jwtHeader === "string") {
+          return {
+            ...data,
+            publicAccessToken: jwtHeader,
+          };
+        }
+
         const claimsHeader = response.headers.get("x-trigger-jwt-claims");
         const claims = claimsHeader ? JSON.parse(claimsHeader) : undefined;
 
         const jwt = await generateJWT({
-          secretKey: this.accessToken,
+          secretKey: this.#selfSigningKey,
           payload: {
             ...claims,
             scopes: [`read:batch:${data.id}`],
@@ -1107,7 +1150,7 @@ export class ApiClient {
           const claims = claimsHeader ? JSON.parse(claimsHeader) : undefined;
 
           const jwt = await generateJWT({
-            secretKey: this.accessToken,
+            secretKey: this.#selfSigningKey,
             payload: {
               ...claims,
               scopes: [`write:waitpoints:${data.id}`],
@@ -1870,6 +1913,22 @@ export class ApiClient {
     );
   }
 
+  async createPublicToken(
+    body: CreatePublicTokenRequestBody,
+    requestOptions?: ZodFetchOptions
+  ): Promise<{ token: string }> {
+    return zodfetch(
+      CreatePublicTokenResponseBody,
+      `${this.baseUrl}/api/v1/auth/public-tokens`,
+      {
+        method: "POST",
+        headers: this.#getHeaders(false),
+        body: JSON.stringify(body),
+      },
+      mergeRequestOptions(this.defaultRequestOptions, requestOptions)
+    );
+  }
+
   retrieveBatch(batchId: string, requestOptions?: ZodFetchOptions) {
     return zodfetch(
       RetrieveBatchV2Response,

packages/core/src/v3/apiKeys.test.ts

@@ -0,0 +1,18 @@
+import { describe, expect, it } from "vitest";
+import { isAdditionalApiKey } from "./apiKeys.js";
+
+describe("isAdditionalApiKey", () => {
+  it.each(["dev", "stg", "prod", "preview"])("recognizes %s additional keys", (environment) => {
+    expect(isAdditionalApiKey(`tr_${environment}_sk_0123456789abcdefghijklmn`)).toBe(true);
+  });
+
+  it.each([
+    "tr_prod_0123456789abcdefghijklmn",
+    "tr_prod_sk_too-short",
+    "tr_prod_sk_0123456789abcdefghijklmn_extra",
+    "tr_test_sk_0123456789abcdefghijklmn",
+    "tr_prod_sk_0123456789abcdefghijkl_",
+  ])("rejects %s", (key) => {
+    expect(isAdditionalApiKey(key)).toBe(false);
+  });
+});

packages/core/src/v3/apiKeys.ts

@@ -0,0 +1,11 @@
+const ADDITIONAL_API_KEY_PATTERN = /^tr_(dev|stg|prod|preview)_sk_[0-9a-zA-Z]{24}$/;
+
+/**
+ * Returns whether a key has the additional environment API key format.
+ *
+ * This is only a routing hint. It must never be used as a security boundary;
+ * servers authenticate additional keys by resolving their stored hash.
+ */
+export function isAdditionalApiKey(key: string): boolean {
+  return ADDITIONAL_API_KEY_PATTERN.test(key);
+}

packages/core/src/v3/index.ts

@@ -30,6 +30,7 @@ export * from "./resource-catalog-api.js";
 export * from "./types/index.js";
 export { links } from "./links.js";
 export * from "./jwt.js";
+export * from "./apiKeys.js";
 export * from "./workloadDeploymentToken.js";
 export * from "./idempotencyKeys.js";
 export * from "./streams/asyncIterableStream.js";

packages/trigger-sdk/src/v3/ai.ts

@@ -14,6 +14,7 @@ import {
   type inferSchemaOut,
   InputStreamOncePromise,
   type InputStreamOnceResult,
+  isAdditionalApiKey,
   isSchemaZodEsque,
   logger,
   type MachinePresetName,
@@ -10600,24 +10601,53 @@ async function mintPublicTokenWithOverride(args: {
     throw new Error("chat.createStartSessionAction: no API access token configured for JWT mint.");
   }
   const ctx: ChatStartSessionEndpointContext = { endpoint: "auth", chatId: args.chatId };
-  const url = `${resolveChatStartBaseURL("auth", args.chatId, args.baseURLOption)}/api/v1/auth/jwt/claims`;
+  const scopes = [`read:sessions:${args.chatId}`, `write:sessions:${args.chatId}`];
+  const serverMint = isAdditionalApiKey(accessToken);
+  const endpoint = serverMint ? "/api/v1/auth/public-tokens" : "/api/v1/auth/jwt/claims";
+  const url = `${resolveChatStartBaseURL("auth", args.chatId, args.baseURLOption)}${endpoint}`;
   const init: RequestInit = {
     method: "POST",
     headers: overrideRequestHeaders(accessToken),
+    ...(serverMint
+      ? {
+          body: JSON.stringify({
+            scopes,
+            expirationTime:
+              args.expirationTime instanceof Date
+                ? Math.floor(args.expirationTime.getTime() / 1000)
+                : args.expirationTime,
+          }),
+        }
+      : {}),
   };
   const response = args.fetchOverride
     ? await args.fetchOverride(url, init, ctx)
     : await fetch(url, init);
   if (!response.ok) {
+    // An additional API key cannot self-sign, so it must use the server mint
+    // endpoint. On a server too old to expose it, explain the recovery path
+    // instead of surfacing a bare 404 (mirrors auth.createServerPublicToken).
+    if (serverMint && response.status === 404) {
+      throw new Error(
+        "This additional API key cannot self-sign public tokens, and the server does not support public-token minting. Upgrade the server or use the root API key."
+      );
+    }
     const text = await response.text().catch(() => "");
     throw new Error(`auth.createPublicToken failed: ${response.status} ${text}`);
   }
-  const claims = (await response.json()) as Record<string, unknown>;
+  const responseBody = (await response.json()) as Record<string, unknown>;
+  if (serverMint) {
+    if (typeof responseBody.token !== "string") {
+      throw new Error("auth.createPublicToken failed: server response did not include a token");
+    }
+    return responseBody.token;
+  }
+
   return generateJWT({
     secretKey: accessToken,
     payload: {
-      ...claims,
-      scopes: [`read:sessions:${args.chatId}`, `write:sessions:${args.chatId}`],
+      ...responseBody,
+      scopes,
     },
     expirationTime: args.expirationTime,
   });