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

## Summary

Additional environment API keys can use SDK APIs that require public
access tokens. The SDK detects the additional-key format and asks the
Trigger.dev server to mint scoped tokens instead of attempting to sign
them locally.

Root environment keys retain their existing local-signing behavior.
Trigger and batch clients also prefer server-issued tokens returned in
response headers while preserving compatibility with older servers.

## Deployment notes

This package update is safe to publish before servers expose additional
key creation. Existing root keys continue to use the current path, while
an additional key used with an older server fails with an actionable
upgrade error.

Author: carderne

.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,
   });