@trigger.dev/sdk 4.8.2 → 4.8.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (71) hide show
  1. package/dist/commonjs/v3/ai-shared.d.ts +3 -2
  2. package/dist/commonjs/v3/ai-shared.js +219 -28
  3. package/dist/commonjs/v3/ai-shared.js.map +1 -1
  4. package/dist/commonjs/v3/ai.d.ts +4 -0
  5. package/dist/commonjs/v3/ai.js +97 -87
  6. package/dist/commonjs/v3/ai.js.map +1 -1
  7. package/dist/commonjs/v3/auth.d.ts +11 -4
  8. package/dist/commonjs/v3/auth.js +9 -8
  9. package/dist/commonjs/v3/auth.js.map +1 -1
  10. package/dist/commonjs/v3/chat-server.js +3 -1
  11. package/dist/commonjs/v3/chat-server.js.map +1 -1
  12. package/dist/commonjs/v3/chat.js +26 -6
  13. package/dist/commonjs/v3/chat.js.map +1 -1
  14. package/dist/commonjs/v3/index.d.ts +1 -1
  15. package/dist/commonjs/v3/index.js +2 -1
  16. package/dist/commonjs/v3/index.js.map +1 -1
  17. package/dist/commonjs/v3/oidc/aws.d.ts +24 -0
  18. package/dist/commonjs/v3/oidc/aws.js +46 -0
  19. package/dist/commonjs/v3/oidc/aws.js.map +1 -0
  20. package/dist/commonjs/v3/oidc/infisical.d.ts +16 -0
  21. package/dist/commonjs/v3/oidc/infisical.js +43 -0
  22. package/dist/commonjs/v3/oidc/infisical.js.map +1 -0
  23. package/dist/commonjs/version.js +1 -1
  24. package/dist/esm/v3/ai-shared.d.ts +3 -2
  25. package/dist/esm/v3/ai-shared.js +214 -28
  26. package/dist/esm/v3/ai-shared.js.map +1 -1
  27. package/dist/esm/v3/ai.d.ts +4 -0
  28. package/dist/esm/v3/ai.js +98 -88
  29. package/dist/esm/v3/ai.js.map +1 -1
  30. package/dist/esm/v3/auth.d.ts +11 -4
  31. package/dist/esm/v3/auth.js +9 -8
  32. package/dist/esm/v3/auth.js.map +1 -1
  33. package/dist/esm/v3/chat-server.js +4 -2
  34. package/dist/esm/v3/chat-server.js.map +1 -1
  35. package/dist/esm/v3/chat.js +26 -6
  36. package/dist/esm/v3/chat.js.map +1 -1
  37. package/dist/esm/v3/index.d.ts +1 -1
  38. package/dist/esm/v3/index.js +1 -1
  39. package/dist/esm/v3/index.js.map +1 -1
  40. package/dist/esm/v3/oidc/aws.d.ts +24 -0
  41. package/dist/esm/v3/oidc/aws.js +43 -0
  42. package/dist/esm/v3/oidc/aws.js.map +1 -0
  43. package/dist/esm/v3/oidc/infisical.d.ts +16 -0
  44. package/dist/esm/v3/oidc/infisical.js +40 -0
  45. package/dist/esm/v3/oidc/infisical.js.map +1 -0
  46. package/dist/esm/version.js +1 -1
  47. package/docs/ai-chat/backend.mdx +2 -2
  48. package/docs/ai-chat/custom-agents.mdx +8 -1
  49. package/docs/ai-chat/frontend.mdx +1 -1
  50. package/docs/ai-chat/lifecycle-hooks.mdx +4 -0
  51. package/docs/ai-chat/migrating-from-hydrate-messages.mdx +1 -1
  52. package/docs/ai-chat/transcript-storage.mdx +3 -1
  53. package/docs/apikeys/custom-access.mdx +209 -0
  54. package/docs/apikeys.mdx +54 -13
  55. package/docs/cli-login-commands.mdx +7 -1
  56. package/docs/cli-preview-archive.mdx +8 -0
  57. package/docs/cli-webhooks-commands.mdx +115 -0
  58. package/docs/config/config-file.mdx +2 -2
  59. package/docs/deployment/overview.mdx +2 -0
  60. package/docs/deployment/trusted-publishing.mdx +140 -0
  61. package/docs/github-actions.mdx +2 -2
  62. package/docs/github-integration.mdx +21 -0
  63. package/docs/oidc/anthropic.mdx +187 -0
  64. package/docs/oidc/aws.mdx +219 -0
  65. package/docs/oidc/custom.mdx +48 -0
  66. package/docs/oidc/infisical.mdx +59 -0
  67. package/docs/oidc.mdx +75 -0
  68. package/docs/self-hosting/env/webapp.mdx +7 -0
  69. package/docs/webhooks/connect.mdx +12 -0
  70. package/docs/webhooks/public-beta.mdx +70 -0
  71. package/package.json +37 -2
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/v3/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,OAAO,EAAE,KAAK,EAAqB,MAAM,YAAY,CAAC;AACtD,OAAO,EAAE,KAAK,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACzE,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAC3B,cAAc,sBAAsB,CAAC;AACrC,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAO9B,OAAO,EACL,2BAA2B,EAC3B,uBAAuB,EACvB,4BAA4B,EAC5B,kBAAkB,EAClB,oBAAoB,GAKrB,MAAM,sBAAsB,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAS3B,OAAO,EACL,QAAQ,EACR,mBAAmB,EACnB,eAAe,EACf,aAAa,EACb,mBAAmB,EACnB,aAAa,EACb,qBAAqB,EACrB,cAAc,EACd,wBAAwB,EACxB,iBAAiB,EACjB,gBAAgB,EAChB,sBAAsB,EACtB,sBAAsB,EACtB,wBAAwB,EACxB,MAAM,GAEP,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,IAAI,GAUL,MAAM,WAAW,CAAC;AACnB,OAAO,KAAK,SAAS,MAAM,sBAAsB,CAAC;AAClD,OAAO,EACL,WAAW,GAGZ,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,OAAO,MAAM,cAAc,CAAC;AACxC,OAAO,KAAK,MAAM,MAAM,aAAa,CAAC;AACtC,OAAO,KAAK,iBAAiB,MAAM,wBAAwB,CAAC;AAG5D,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,EAAE,aAAa,EAA4B,MAAM,oBAAoB,CAAC;AAC7E,OAAO,KAAK,OAAO,MAAM,cAAc,CAAC;AACxC,OAAO,KAAK,MAAM,MAAM,aAAa,CAAC"}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/v3/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,OAAO,EAAE,KAAK,EAAqB,MAAM,YAAY,CAAC;AACtD,OAAO,EAAE,KAAK,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACzE,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAC3B,cAAc,sBAAsB,CAAC;AACrC,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAO9B,OAAO,EACL,2BAA2B,EAC3B,uBAAuB,EACvB,4BAA4B,EAC5B,kBAAkB,EAClB,oBAAoB,GAKrB,MAAM,sBAAsB,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAS3B,OAAO,EACL,QAAQ,EACR,cAAc,EAEd,mBAAmB,EACnB,eAAe,EACf,aAAa,EACb,mBAAmB,EACnB,aAAa,EACb,qBAAqB,EACrB,cAAc,EACd,wBAAwB,EACxB,iBAAiB,EACjB,gBAAgB,EAChB,sBAAsB,EACtB,sBAAsB,EACtB,wBAAwB,EACxB,MAAM,GAEP,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,IAAI,GAUL,MAAM,WAAW,CAAC;AACnB,OAAO,KAAK,SAAS,MAAM,sBAAsB,CAAC;AAClD,OAAO,EACL,WAAW,GAGZ,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,OAAO,MAAM,cAAc,CAAC;AACxC,OAAO,KAAK,MAAM,MAAM,aAAa,CAAC;AACtC,OAAO,KAAK,iBAAiB,MAAM,wBAAwB,CAAC;AAG5D,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,EAAE,aAAa,EAA4B,MAAM,oBAAoB,CAAC;AAC7E,OAAO,KAAK,OAAO,MAAM,cAAc,CAAC;AACxC,OAAO,KAAK,MAAM,MAAM,aAAa,CAAC"}
@@ -0,0 +1,24 @@
1
+ export type AWSCredentialProviderOptions = {
2
+ roleArn: string;
3
+ region: string;
4
+ /** Defaults to the current run ID, sanitized and limited to 64 characters. */
5
+ roleSessionName?: string;
6
+ /** STS session duration, in seconds. Defaults to one hour. */
7
+ durationSeconds?: number;
8
+ /** Include verified identity as AWS session tags. Requires sts:TagSession in the role trust policy. Defaults to false. */
9
+ sessionTags?: boolean;
10
+ };
11
+ export type AWSCredentials = {
12
+ accessKeyId: string;
13
+ secretAccessKey: string;
14
+ sessionToken: string;
15
+ expiration: Date;
16
+ };
17
+ /**
18
+ * Pass directly as an AWS SDK client's credentials option.
19
+ * The AWS SDK caches credentials and calls this provider again before expiration.
20
+ * Create the AWS client inside `run` and reuse it only within that run. Module-scope
21
+ * clients can reuse a previous run's credentials and AWS session attribution.
22
+ * Install the optional peer @aws-sdk/client-sts to use this subpath.
23
+ */
24
+ export declare function awsCredentialProvider(options: AWSCredentialProviderOptions): () => Promise<AWSCredentials>;
@@ -0,0 +1,43 @@
1
+ import { AssumeRoleWithWebIdentityCommand, STSClient } from "@aws-sdk/client-sts";
2
+ import { taskContext } from "@trigger.dev/core/v3";
3
+ import { auth } from "../auth.js";
4
+ const DEFAULT_DURATION_SECONDS = 60 * 60;
5
+ const MAX_ROLE_SESSION_NAME_LENGTH = 64;
6
+ /**
7
+ * Pass directly as an AWS SDK client's credentials option.
8
+ * The AWS SDK caches credentials and calls this provider again before expiration.
9
+ * Create the AWS client inside `run` and reuse it only within that run. Module-scope
10
+ * clients can reuse a previous run's credentials and AWS session attribution.
11
+ * Install the optional peer @aws-sdk/client-sts to use this subpath.
12
+ */
13
+ export function awsCredentialProvider(options) {
14
+ const client = new STSClient({ region: options.region });
15
+ return async () => {
16
+ const { token } = await auth.getOIDCToken({
17
+ audience: "sts.amazonaws.com",
18
+ awsSessionTags: options.sessionTags,
19
+ });
20
+ const roleSessionName = options.roleSessionName ??
21
+ taskContext.ctx.run.id.replace(/[^\w+=,.@-]/g, "_").slice(0, MAX_ROLE_SESSION_NAME_LENGTH);
22
+ const { Credentials } = await client.send(new AssumeRoleWithWebIdentityCommand({
23
+ RoleArn: options.roleArn,
24
+ RoleSessionName: roleSessionName,
25
+ DurationSeconds: options.durationSeconds ?? DEFAULT_DURATION_SECONDS,
26
+ WebIdentityToken: token,
27
+ }));
28
+ if (!Credentials?.AccessKeyId ||
29
+ !Credentials.SecretAccessKey ||
30
+ !Credentials.SessionToken ||
31
+ !Credentials.Expiration ||
32
+ !Number.isFinite(Credentials.Expiration.getTime())) {
33
+ throw new Error("AWS STS did not return complete temporary credentials with an expiration.");
34
+ }
35
+ return {
36
+ accessKeyId: Credentials.AccessKeyId,
37
+ secretAccessKey: Credentials.SecretAccessKey,
38
+ sessionToken: Credentials.SessionToken,
39
+ expiration: Credentials.Expiration,
40
+ };
41
+ };
42
+ }
43
+ //# sourceMappingURL=aws.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"aws.js","sourceRoot":"","sources":["../../../../src/v3/oidc/aws.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gCAAgC,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAClF,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACnD,OAAO,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAElC,MAAM,wBAAwB,GAAG,EAAE,GAAG,EAAE,CAAC;AACzC,MAAM,4BAA4B,GAAG,EAAE,CAAC;AAoBxC;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CACnC,OAAqC;IAErC,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAEzD,OAAO,KAAK,IAAI,EAAE;QAChB,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,IAAI,CAAC,YAAY,CAAC;YACxC,QAAQ,EAAE,mBAAmB;YAC7B,cAAc,EAAE,OAAO,CAAC,WAAW;SACpC,CAAC,CAAC;QACH,MAAM,eAAe,GACnB,OAAO,CAAC,eAAe;YACvB,WAAW,CAAC,GAAI,CAAC,GAAG,CAAC,EAAE,CAAC,OAAO,CAAC,cAAc,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,4BAA4B,CAAC,CAAC;QAC9F,MAAM,EAAE,WAAW,EAAE,GAAG,MAAM,MAAM,CAAC,IAAI,CACvC,IAAI,gCAAgC,CAAC;YACnC,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,eAAe,EAAE,eAAe;YAChC,eAAe,EAAE,OAAO,CAAC,eAAe,IAAI,wBAAwB;YACpE,gBAAgB,EAAE,KAAK;SACxB,CAAC,CACH,CAAC;QAEF,IACE,CAAC,WAAW,EAAE,WAAW;YACzB,CAAC,WAAW,CAAC,eAAe;YAC5B,CAAC,WAAW,CAAC,YAAY;YACzB,CAAC,WAAW,CAAC,UAAU;YACvB,CAAC,MAAM,CAAC,QAAQ,CAAC,WAAW,CAAC,UAAU,CAAC,OAAO,EAAE,CAAC,EAClD,CAAC;YACD,MAAM,IAAI,KAAK,CAAC,2EAA2E,CAAC,CAAC;QAC/F,CAAC;QAED,OAAO;YACL,WAAW,EAAE,WAAW,CAAC,WAAW;YACpC,eAAe,EAAE,WAAW,CAAC,eAAe;YAC5C,YAAY,EAAE,WAAW,CAAC,YAAY;YACtC,UAAU,EAAE,WAAW,CAAC,UAAU;SACnC,CAAC;IACJ,CAAC,CAAC;AACJ,CAAC"}
@@ -0,0 +1,16 @@
1
+ export type InfisicalAccessTokenOptions = {
2
+ identityId: string;
3
+ /** Defaults to https://us.infisical.com. Set this for EU or self-hosted instances. */
4
+ siteUrl?: string;
5
+ /** Defaults to siteUrl, without a trailing slash. Must match the identity's allowed audience. */
6
+ audience?: string;
7
+ /** Infisical organization to scope the session to. Defaults to the identity's organization. */
8
+ organizationSlug?: string;
9
+ };
10
+ export type InfisicalAccessToken = {
11
+ accessToken: string;
12
+ tokenType: "Bearer";
13
+ expiresAt: Date;
14
+ };
15
+ /** Authenticate inside run. Tokens are not cached; call again before expiresAt when needed. */
16
+ export declare function infisicalAccessToken(options: InfisicalAccessTokenOptions): Promise<InfisicalAccessToken>;
@@ -0,0 +1,40 @@
1
+ import { auth } from "../auth.js";
2
+ const DEFAULT_SITE_URL = "https://us.infisical.com";
3
+ /** Authenticate inside run. Tokens are not cached; call again before expiresAt when needed. */
4
+ export async function infisicalAccessToken(options) {
5
+ const siteUrl = (options.siteUrl ?? DEFAULT_SITE_URL).replace(/\/+$/, "");
6
+ const loginUrl = new URL("api/v1/auth/oidc-auth/login", `${siteUrl}/`);
7
+ const { token } = await auth.getOIDCToken({ audience: options.audience ?? siteUrl });
8
+ const requestedAt = Date.now();
9
+ const response = await fetch(loginUrl, {
10
+ method: "POST",
11
+ headers: { "Content-Type": "application/json" },
12
+ body: JSON.stringify({
13
+ identityId: options.identityId,
14
+ jwt: token,
15
+ organizationSlug: options.organizationSlug,
16
+ }),
17
+ });
18
+ const result = await response.json().catch(() => undefined);
19
+ const data = result && typeof result === "object" ? result : undefined;
20
+ if (!response.ok) {
21
+ const message = typeof data?.message === "string"
22
+ ? data.message.replaceAll(token, "[redacted]")
23
+ : response.statusText;
24
+ throw new Error(`Infisical OIDC login failed (${response.status}): ${message}`);
25
+ }
26
+ if (typeof data?.accessToken !== "string" ||
27
+ !data.accessToken.trim() ||
28
+ data.tokenType !== "Bearer" ||
29
+ typeof data.expiresIn !== "number" ||
30
+ !Number.isFinite(data.expiresIn) ||
31
+ data.expiresIn <= 0) {
32
+ throw new Error("Infisical OIDC login returned an invalid access token or expiration.");
33
+ }
34
+ const expiresAt = new Date(requestedAt + data.expiresIn * 1000);
35
+ if (!Number.isFinite(expiresAt.getTime())) {
36
+ throw new Error("Infisical OIDC login returned an invalid expiration.");
37
+ }
38
+ return { accessToken: data.accessToken, tokenType: "Bearer", expiresAt };
39
+ }
40
+ //# sourceMappingURL=infisical.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"infisical.js","sourceRoot":"","sources":["../../../../src/v3/oidc/infisical.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAElC,MAAM,gBAAgB,GAAG,0BAA0B,CAAC;AAkBpD,+FAA+F;AAC/F,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,OAAoC;IAEpC,MAAM,OAAO,GAAG,CAAC,OAAO,CAAC,OAAO,IAAI,gBAAgB,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAC1E,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,6BAA6B,EAAE,GAAG,OAAO,GAAG,CAAC,CAAC;IACvE,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,IAAI,CAAC,YAAY,CAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,OAAO,EAAE,CAAC,CAAC;IACrF,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAC/B,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,QAAQ,EAAE;QACrC,MAAM,EAAE,MAAM;QACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;QAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;YACnB,UAAU,EAAE,OAAO,CAAC,UAAU;YAC9B,GAAG,EAAE,KAAK;YACV,gBAAgB,EAAE,OAAO,CAAC,gBAAgB;SAC3C,CAAC;KACH,CAAC,CAAC;IACH,MAAM,MAAM,GAAY,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;IACrE,MAAM,IAAI,GACR,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAE,MAAkC,CAAC,CAAC,CAAC,SAAS,CAAC;IAEzF,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;QACjB,MAAM,OAAO,GACX,OAAO,IAAI,EAAE,OAAO,KAAK,QAAQ;YAC/B,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,KAAK,EAAE,YAAY,CAAC;YAC9C,CAAC,CAAC,QAAQ,CAAC,UAAU,CAAC;QAC1B,MAAM,IAAI,KAAK,CAAC,gCAAgC,QAAQ,CAAC,MAAM,MAAM,OAAO,EAAE,CAAC,CAAC;IAClF,CAAC;IAED,IACE,OAAO,IAAI,EAAE,WAAW,KAAK,QAAQ;QACrC,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,EAAE;QACxB,IAAI,CAAC,SAAS,KAAK,QAAQ;QAC3B,OAAO,IAAI,CAAC,SAAS,KAAK,QAAQ;QAClC,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC;QAChC,IAAI,CAAC,SAAS,IAAI,CAAC,EACnB,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,sEAAsE,CAAC,CAAC;IAC1F,CAAC;IAED,MAAM,SAAS,GAAG,IAAI,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC;IAChE,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC;QAC1C,MAAM,IAAI,KAAK,CAAC,sDAAsD,CAAC,CAAC;IAC1E,CAAC;IAED,OAAO,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE,SAAS,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC;AAC3E,CAAC"}
@@ -1,2 +1,2 @@
1
- export const VERSION = "4.8.2";
1
+ export const VERSION = "4.8.4";
2
2
  //# sourceMappingURL=version.js.map
@@ -599,13 +599,13 @@ onAction: async ({ action }) => {
599
599
  },
600
600
 
601
601
  // Side-effect once per net-new tool result when wire messages come in
602
- hydrateMessages: async ({ incomingMessages }) => {
602
+ hydrateMessages: async ({ incomingMessages, previousMessages }) => {
603
603
  for (const msg of incomingMessages) {
604
604
  for (const r of chat.history.extractNewToolResults(msg)) {
605
605
  await onToolResolved({ id: r.toolCallId, output: r.output, errorText: r.errorText });
606
606
  }
607
607
  }
608
- return incomingMessages;
608
+ return [...previousMessages, ...incomingMessages.filter((m) => m.role === "user")];
609
609
  },
610
610
  ```
611
611
 
@@ -423,7 +423,12 @@ export const myChat = chat.customAgent({
423
423
  const incoming = currentPayload.message ? [currentPayload.message] : [];
424
424
  const turnInput =
425
425
  turn === 0 && continuationSeed.length > 0
426
- ? [...continuationSeed.filter((s) => !incoming.some((m) => m.id === s.id)), ...incoming]
426
+ ? [
427
+ ...continuationSeed.filter(
428
+ (s) => !incoming.some((m) => m.role === "user" && m.id === s.id)
429
+ ),
430
+ ...incoming,
431
+ ]
427
432
  : incoming;
428
433
  const messages = await conversation.addIncoming(turnInput, currentPayload.trigger, turn);
429
434
 
@@ -488,6 +493,8 @@ export const myChat = chat.customAgent({
488
493
  - **Turn 0 or `trigger === "regenerate-message"`: replaces** the accumulator with exactly what you pass. This is why continuation seeding goes through `addIncoming` (above), and why a regenerate needs you to slice your own history — the wire omits the message on regenerate, so pass the stored history minus the last assistant message.
489
494
  - **Every other turn: appends** what you pass (the wire carries at most the one new user message).
490
495
 
496
+ In both modes, a tool approval or tool output from the client is merged onto the stored tool call it answers, found in the accumulator or earlier in what you pass, rather than appended as a new message. One that answers no pending call is dropped.
497
+
491
498
  ```ts
492
499
  const conversation = new chat.MessageAccumulator();
493
500
 
@@ -109,7 +109,7 @@ Every chat is backed by a durable Session — the row that owns the chat's runs,
109
109
  | Field | Type | Notes |
110
110
  | --- | --- | --- |
111
111
  | `publicAccessToken` | `string` | Session-scoped JWT (`read:sessions:{chatId} + write:sessions:{chatId}`). Refreshed automatically on 401/403 via `accessToken`. |
112
- | `lastEventId` | `string \| undefined` | Last SSE event received on `.out`. **Valid for the lifetime of the Session** — keep it across `endRun` / `requestUpgrade` / continuation-run boundaries; only clear when the Session itself closes. The cursor lets the next subscription open past the prior turn's stale `turn-complete` record. |
112
+ | `lastEventId` | `string \| undefined` | Resume cursor on `.out`: the last SSE event received, or while a turn is streaming, the cursor from when that turn started, so a reload replays the whole turn. **Valid for the lifetime of the Session**: keep it across `endRun` / `requestUpgrade` / continuation-run boundaries; only clear when the Session itself closes. The cursor lets the next subscription open past the prior turn's stale `turn-complete` record. |
113
113
  | `isStreaming` | `boolean \| undefined` | **Optional.** The transport sets it internally, but you don't have to persist it — the server decides "nothing is streaming" via the session's [`X-Session-Settled`](/ai-chat/client-protocol#x-session-settled-fast-close-on-idle-reconnects) signal on reconnect. If you do persist it, the transport keeps the fast-path short-circuit. If you drop it, reconnects open the SSE and close fast on settled sessions. |
114
114
 
115
115
  ### Session cleanup (frontend)
@@ -254,6 +254,10 @@ export const myChat = chat.agent({
254
254
  On HITL continuations (`addToolOutput` / `addToolApproveResponse`) the assistant entry in `messages` is **slim** — `state` + `output` / `errorText` / `approval` only, no `input` or other parts. `validateUIMessages` against the AI SDK schema rejects that shape (the schema requires `input` on resolved tool parts), so filter to user messages first (or skip validation entirely on those turns). The example above does the filter.
255
255
  </Warning>
256
256
 
257
+ <Note>
258
+ The agent only takes two kinds of message from a client: user messages, and resolutions of tool calls the agent itself made (an approval response for a call awaiting approval, or the output of a client-side tool). Tool parts on a user message, any client-supplied tool `input`, other roles, and resolutions that don't answer a pending call are dropped before your hooks run. Tool `input` always comes from the agent's own history.
259
+ </Note>
260
+
257
261
  <Note>
258
262
  `onValidateMessages` fires **before** `onTurnStart` and message accumulation. If you need to validate messages loaded from a database, do the loading in `onChatStart` or `onPreload` and let `onValidateMessages` validate the full incoming set each turn.
259
263
  </Note>
@@ -178,7 +178,7 @@ With `hydrateMessages`, your hook was the source of truth and the runtime wrote
178
178
  ```ts lib/transcript-storage.ts
179
179
  loadContext: async ({ chatId, clientData }, { incomingMessages }) => {
180
180
  const branch = await db.activeBranch(chatId, clientData.userId);
181
- return [...branch, ...incomingMessages];
181
+ return [...branch, ...incomingMessages.filter((m) => m.role === "user")];
182
182
  },
183
183
  ```
184
184
 
@@ -194,11 +194,13 @@ const storage: TranscriptStorage<{ userId: string }> = {
194
194
  save: (ctx, changeset) => rows.save(ctx, changeset),
195
195
  loadContext: async ({ chatId, clientData }, { incomingMessages }) => {
196
196
  const branch = await rows.activeBranch(chatId, clientData.userId);
197
- return [...branch, ...incomingMessages];
197
+ return [...branch, ...incomingMessages.filter((m) => m.role === "user")];
198
198
  },
199
199
  };
200
200
  ```
201
201
 
202
+ Append only the user's messages. A tool approval or tool output from the browser arrives in `incomingMessages` too, and the runtime merges it onto the stored call in what you return, so passing it through adds nothing and puts client input into the conversation as is.
203
+
202
204
  `save` keeps receiving every change, and crash recovery keeps running. This is the replacement for the deprecated [`hydrateMessages`](/ai-chat/lifecycle-hooks#hydratemessages) hook; setting both `hydrateMessages` and `storage` on an agent is a startup error.
203
205
 
204
206
  ## Writing your own storage
@@ -0,0 +1,209 @@
1
+ ---
2
+ title: "Custom API key access"
3
+ sidebarTitle: "Custom access"
4
+ description: "Build an API key's access from presets and per-area levels, limit it to selected tasks, and save the result as a preset your organization can reuse."
5
+ ---
6
+
7
+ **Custom access lets you build a key's access area by area, such as Runs or Deployments, when no single [access preset](/apikeys#access-presets) fits.** A common case is a CI key that operates on runs and also deploys: the **Operator** preset plus the **Deploy only** preset in one key.
8
+
9
+ Custom access is available on every plan. A custom key works everywhere a preset key does: the SDK, the CLI and the API.
10
+
11
+ ## Create a key with custom access
12
+
13
+ <Steps titleSize="h3">
14
+ <Step title="Switch to Custom">
15
+ On the **API keys** page, click **Create API key**. Under **Access**, switch from **Preset**
16
+ to **Custom**. The grid starts from the preset that was selected, or empty when **No
17
+ restrictions** is selected.
18
+ </Step>
19
+ <Step title="Combine presets">
20
+ Use **Start from** to replace the grid with a preset, and **Add preset** to add a preset's
21
+ access to what's already there. For the CI key, pick **Operator** in **Start from**, then
22
+ **Deploy only** in **Add preset**. Adding a preset never removes access.
23
+ </Step>
24
+ <Step title="Adjust each area">
25
+ Each row is one area of the environment. Set it to **None**, **Read**, **Write**, **Read and
26
+ write**, or **Manage**, where the area has that level. **Tasks** has its own levels, listed
27
+ below. **Clear all** sets every row to **None**.
28
+ </Step>
29
+ <Step title="Check the summary and create the key">
30
+ The panel beside the grid names the key's access, for example "Operator + Deploy only", and
31
+ lists each area with the scopes it grants. Click **Create API key** and copy the secret.
32
+ </Step>
33
+ </Steps>
34
+
35
+ ## Areas and levels
36
+
37
+ | Area | Levels |
38
+ | --- | --- |
39
+ | **Tasks** | None, Read, Trigger, Read and trigger, Operate runs |
40
+ | **Runs** | None, Read, Read and write |
41
+ | **Batches** | None, Read |
42
+ | **Large payloads** | None, Write |
43
+ | **Queues** | None, Read, Read and write |
44
+ | **Sessions** | None, Read, Read and write, Manage |
45
+ | **Input streams** | None, Write, Read and write |
46
+ | **Tagged runs** | None, Read |
47
+ | **Errors** | None, Read, Read and write |
48
+ | **Webhooks** | None, Read, Read and write |
49
+ | **Waitpoints** | None, Read and write |
50
+ | **Prompts** | None, Read, Read and write |
51
+ | **Deployments** | None, Read, Read and write |
52
+ | **Preview branches** | None, Manage |
53
+ | **Env vars** | None, Read, Read and write |
54
+
55
+ Some levels need another area, and the grid sets it for you:
56
+
57
+ - **Deployments: Read and write** needs **Env vars: Read**, because deploys read the environment's variables while building.
58
+ - **Sessions: Read and write** and **Sessions: Manage** need task trigger access (**Trigger**, **Read and trigger**, or **Operate runs** on all tasks), because sessions continue runs of any task. **Sessions: Read** doesn't.
59
+ - **Input streams: Read and write** needs **Runs: Read and write** and **Waitpoints: Read and write**, because waiting on an input stream pauses the run on a waitpoint. **Write**, which only sends, needs neither.
60
+
61
+ Some levels grant more than their name suggests:
62
+
63
+ - **Large payloads: Write** lets the SDK upload a payload that's too large to send with the trigger request. Keys that trigger tasks with large payloads need it. A key can only read back payloads through the runs it can read. In the Development environment, large payload uploads still need a key with **No restrictions**.
64
+ - **Sessions: Manage** also closes sessions and updates their metadata and tags.
65
+ - **Prompts: Read and write** also changes prompt overrides and promotes versions.
66
+
67
+ **Waitpoints** has no read-only level. Reading a waitpoint token returns its callback URL, which can complete the token, so reading waitpoints always comes with writing them.
68
+
69
+ A deploy only writes environment variables when your build uses [`syncEnvVars`](/config/extensions/syncEnvVars) or another extension that syncs them. Only then does the key need **Env vars: Read and write**. Without it, the deploy fails when it syncs.
70
+
71
+ A backend or CI key that creates or completes [waitpoint tokens](/wait-for-token) with `wait.createToken()` or `wait.completeToken()` needs **Waitpoints: Read and write**. The **Operator** preset includes it. The public access token returned with each waitpoint token can complete that token without an API key.
72
+
73
+ ## Use the key from CI
74
+
75
+ One key triggers a smoke test, waits for it, and deploys. Start from **Operator** and set **Deployments** to **Read and write** (the grid adds **Env vars: Read**), or limit it to the smoke test task as shown in the next section. Raise **Env vars** to **Read and write** only if the build syncs environment variables.
76
+
77
+ ```typescript ci/smoke-test.ts
78
+ import { configure, runs, tasks } from "@trigger.dev/sdk";
79
+ import type { report } from "../src/trigger/report";
80
+
81
+ configure({ accessToken: process.env.TRIGGER_SECRET_KEY });
82
+
83
+ const handle = await tasks.trigger<typeof report>("report", { day: "2026-11-07" });
84
+ const run = await runs.poll(handle, { pollIntervalMs: 1000 });
85
+
86
+ if (run.status !== "COMPLETED") {
87
+ throw new Error(`Smoke test ${run.id} ended as ${run.status}`);
88
+ }
89
+ ```
90
+
91
+ The CLI reads the same key from `TRIGGER_ACCESS_TOKEN`:
92
+
93
+ ```bash
94
+ TRIGGER_ACCESS_TOKEN="$TRIGGER_SECRET_KEY" npx trigger.dev@latest deploy --env prod
95
+ ```
96
+
97
+ ## Limit a custom key to selected tasks
98
+
99
+ The **Tasks** row applies to **All tasks** or to **Selected tasks**, up to 10 task identifiers per key. For a CI key that deploys and runs one smoke test and nothing else: **Start from** Trigger only, set **Tasks** to **Read and trigger**, choose **Selected tasks** and pick `report`, then set **Deployments** to **Read and write**. The task picker lists the tasks deployed to this environment.
100
+
101
+ With selected tasks:
102
+
103
+ - The **Tasks** levels apply only to the selected tasks. Triggering any other task returns a 403.
104
+ - At **Trigger**, the key can't read back the runs it triggers. **Read and trigger** lets it retrieve and poll runs of its selected tasks, and nothing else. **Operate runs** also lets it cancel and replay those runs.
105
+ - **Sessions** and **Input streams** are unavailable, because they reach runs of any task.
106
+ - Every other row applies to the whole environment, and the grid marks it **Applies to the whole environment**. Leave a row at **None** if the key should only reach its selected tasks.
107
+ - **Deployments** applies to the whole environment too. A key that can deploy ships new code for every task, so selected tasks don't limit what a deploy can change.
108
+ - Bulk replay needs trigger access to all tasks. A key limited to selected tasks replays runs one at a time.
109
+
110
+ ### List runs with a task-limited key
111
+
112
+ A run list without a task filter covers every task, so a task-limited key needs the filter:
113
+
114
+ ```typescript Your backend code
115
+ import { runs } from "@trigger.dev/sdk";
116
+
117
+ for await (const run of runs.list({ taskIdentifier: "report", tag: "nightly" })) {
118
+ console.log(run.id, run.status);
119
+ }
120
+ ```
121
+
122
+ `runs.list()` without `taskIdentifier` returns a 403. The filter also combines with `batch`. Retrieving a batch with `batch.retrieve()` needs **Runs: Read** or **Batches: Read**, so to wait on a batch with a task-limited key, list its runs with the task filter instead.
123
+
124
+ ## Public access tokens from a custom key
125
+
126
+ A [Public Access Token](/realtime/auth) can't grant more than the key that creates it. A request for more returns a 403 with `Requested scopes exceed the API key's access`.
127
+
128
+ - A key without **Runs: Read** can't create a token that reads a run by its ID, even a run it triggered.
129
+ - A key limited to selected tasks asks for those tasks instead:
130
+
131
+ ```typescript Your backend code
132
+ import { auth } from "@trigger.dev/sdk";
133
+
134
+ const publicToken = await auth.createPublicToken({
135
+ scopes: { read: { tasks: ["report"] } },
136
+ });
137
+ ```
138
+
139
+ - A key at **Tasks: Trigger** can't create read tokens. The trigger response still includes a token for the run it created (`handle.publicAccessToken`), so a frontend can follow that run.
140
+
141
+ Your backend sends the browser the run ID and `handle.publicAccessToken`, never the API key. Without React, the browser follows the run with the SDK:
142
+
143
+ ```typescript Your frontend code
144
+ import { configure, runs } from "@trigger.dev/sdk";
145
+
146
+ configure({ accessToken: publicAccessToken, baseURL: "https://api.trigger.dev" });
147
+
148
+ for await (const run of runs.subscribeToRun(runId)) {
149
+ console.log(run.status, run.metadata);
150
+ if (run.isCompleted) break;
151
+ }
152
+ ```
153
+
154
+ The token reads only that run. Triggering, listing runs or reading another run with it returns a 403.
155
+
156
+ Use `@trigger.dev/sdk` 4.5.8 or later to create public tokens with an environment API key.
157
+
158
+ ## Save access as a preset
159
+
160
+ When your team creates the same kind of key again and again, save its access once. In **Custom**, build the access, click **Save as preset**, and give it a name (up to 64 characters) and an optional description.
161
+
162
+ Saved presets belong to your organization. They appear under **Your presets** in the preset list of every project and environment, and in the **Start from** and **Add preset** menus.
163
+
164
+ - A saved preset holds access, not tasks, since task identifiers differ between projects. If you save it while the grid is limited to **Selected tasks**, the preset remembers that: a key made from it starts at **Selected tasks** with nothing picked, and asks for tasks in each project. Switch to **All tasks** only on purpose.
165
+ - Saved presets can't be edited. To change one, delete it and save a new one.
166
+ - An organization can save up to 50 presets. A saved preset can't reuse the name of another preset.
167
+ - Deleting a saved preset doesn't change the keys created from it. They keep their access and show as **Custom** on the API keys page.
168
+
169
+ Saving and deleting presets needs the Owner or Admin role in the organization, since presets are shared by every project. A project role doesn't count. Anyone who can create API keys in an environment can create keys from saved presets.
170
+
171
+ ## See a key's access
172
+
173
+ The **Access** column on the API keys page shows a key's preset. For a custom key it shows **Custom**, followed by the presets the access matches, such as "Operator + Deploy only", or the number of selected tasks. Click a key to open its details: each area and level, read from the key itself, and its selected tasks. **Show scopes** lists the scopes behind each level.
174
+
175
+ To change a custom key later, use [**Edit access**](/apikeys#change-a-keys-access).
176
+
177
+ ## See what a key uses
178
+
179
+ Trigger.dev Cloud records which access each API key uses, so you can find access a key never needs and remove it. Click a key to open its details. Under **Access**, each area the key has shows:
180
+
181
+ - **Last used** with the date and time the key last used it, or **Never**
182
+ - the level it used when that's less than it has, such as **Read last used** on an area with read and write access
183
+
184
+ For a key with **No restrictions**, every area is listed. Below the areas, **Usage tracked since** shows when tracking started.
185
+
186
+ Usage is recorded per area and level, not per request: there are no counts, paths or IP addresses. The last-used time can lag by up to an hour.
187
+
188
+ ### Narrow a key to what it used
189
+
190
+ In the key's details, click **Narrow to what it used** below its access. [**Edit access**](/apikeys#change-a-keys-access) opens with the smallest level per area that covers the key's requests in the last 30 days, keeping its selected tasks, and asks you to confirm: it lists each area the key loses with when it was last used. Click **Back** to adjust the grid, or **Save access** to apply it. The secret doesn't change, so nothing needs redeploying.
191
+
192
+ Narrowing isn't offered when:
193
+
194
+ - the key has less than 7 days of recorded usage
195
+ - the key used access the grid doesn't cover
196
+ - a key with **No restrictions** called endpoints that only unrestricted keys can use, such as `whoami` and pausing or resuming an environment, in the last 30 days. A narrower key would break those calls.
197
+
198
+ Access that a key uses rarely, such as a monthly report, can look unused after 30 days. Check the last-used note on each area before you save.
199
+
200
+ ## Next steps
201
+
202
+ <CardGroup cols={2}>
203
+ <Card title="API keys" icon="key" href="/apikeys">
204
+ Create keys, restrict them to IP addresses, and rotate them.
205
+ </Card>
206
+ <Card title="Realtime authentication" icon="tower-broadcast" href="/realtime/auth">
207
+ Create scoped public tokens for frontend and realtime access.
208
+ </Card>
209
+ </CardGroup>
package/docs/apikeys.mdx CHANGED
@@ -10,6 +10,11 @@ description: "Authenticate backend requests with environment-specific API keys."
10
10
  environment variable, never commit them to source control, and never expose them in frontend code.
11
11
  </Warning>
12
12
 
13
+ <Tip>
14
+ To access AWS or another external service from a deployed task without stored cloud keys, use
15
+ [workload identity](/oidc). Trigger.dev API keys cannot mint OIDC tokens.
16
+ </Tip>
17
+
13
18
  ## Create an API key
14
19
 
15
20
  Create a separate named key for each service or integration that accesses Trigger.dev.
@@ -26,12 +31,14 @@ API keys belong to one environment. A Development key cannot access Production,
26
31
  Select the project and environment the integration needs to access, then open [**API keys**](https://cloud.trigger.dev/_/apikeys).
27
32
  </Step>
28
33
  <Step title="Create the key">
29
- Click **New API key**, enter a descriptive name, and optionally set an expiration date. Names can
30
- contain up to 64 characters.
34
+ Click **Create API key**, enter a descriptive name, and choose when it expires: in 30 days, 90
35
+ days (the default), or 1 year, on a custom date, or never. Names can contain up to 64 characters. To
36
+ [restrict the key to your servers](#restrict-a-key-to-ip-addresses), list their IP addresses.
31
37
  </Step>
32
38
  <Step title="Choose its access">
33
39
  Select the narrowest access preset that supports the integration. For task-aware presets, choose
34
- all tasks or up to 10 task identifiers.
40
+ all tasks or up to 10 task identifiers. When no single preset fits, switch to
41
+ [Custom](/apikeys/custom-access) and combine presets or set each area's level.
35
42
  </Step>
36
43
  <Step title="Copy and store the secret">
37
44
  Copy the key into your secret manager or backend environment. Trigger.dev shows the complete
@@ -54,7 +61,7 @@ import { configure, tasks } from "@trigger.dev/sdk";
54
61
  import type { sendEmail } from "./trigger/send-email";
55
62
 
56
63
  configure({
57
- secretKey: process.env.TRIGGER_SECRET_KEY,
64
+ accessToken: process.env.TRIGGER_SECRET_KEY,
58
65
  previewBranch: "my-branch", // Only needed for preview branches
59
66
  baseURL: "https://mytrigger.example.com", // Optional
60
67
  });
@@ -75,21 +82,23 @@ The default API URL is `https://api.trigger.dev`.
75
82
 
76
83
  ## Access presets
77
84
 
78
- Access presets define what a key can do. On the Free and Hobby plans only the **No restrictions** preset is available. All other presets require the Pro or Enterprise plan.
85
+ Access presets define what a key can do. Every preset is available on every plan.
79
86
 
80
87
  | Preset | Access |
81
88
  | --- | --- |
82
- | **Trigger only** | Trigger runs and batches for all or selected tasks. Trigger responses include scoped public access tokens for the runs and batches they create |
83
- | **Task operator** | Trigger all or selected tasks and inspect or operate on their runs |
84
- | **Observer** | Read runs, tasks, batches, logs, traces, queues, errors, and webhooks |
85
- | **Operator** | Observe and operate on runs, queues, errors, and webhooks, and trigger tasks |
89
+ | **Trigger only** | Trigger runs and batches for all or selected tasks, and upload large payloads. Trigger responses include scoped public access tokens for the runs and batches they create |
90
+ | **Task operator** | Trigger all or selected tasks, upload large payloads, and inspect or operate on their runs |
91
+ | **Observer** | Read runs, tasks, batches, logs, traces, queues, errors, webhooks, sessions, and prompts |
92
+ | **Operator** | Observe and operate on runs, queues, errors, webhooks, sessions, and waitpoints, close sessions, send to and wait on input streams, read tagged runs and prompts, upload large payloads, and trigger tasks |
86
93
  | **Webhooks only** | Read and write [webhooks](/webhooks/overview). Replaying deliveries that trigger tasks and creating webhook waiters require task or waitpoint scopes |
87
- | **Waitpoints only** | Create, list, and retrieve [waitpoint tokens](/wait-for-token). No task or run access |
94
+ | **Waitpoints only** | Create, read, and complete [waitpoint tokens](/wait-for-token), and create and cancel webhook waiters. No task or run access |
88
95
  | **Deploy only** | Deploy versions, sync environment variables, and manage Preview branches |
89
96
  | **Variables only** | Read and write environment variables in this environment |
90
97
  | **No restrictions** | Full access to the environment |
91
98
 
92
- **Trigger only** and **Task operator** can be restricted to selected tasks, up to 10 tasks per key. Task restrictions use task identifiers, such as `send-email`. A request involving multiple tasks — such as a batch trigger — succeeds only when the key can access every task in the request, so a task-restricted key can batch-trigger only its selected tasks.
99
+ **Trigger only** and **Task operator** can be restricted to selected tasks, up to 10 tasks per key. Task restrictions use task identifiers, such as `send-email`. A request involving multiple tasks (such as a batch trigger) succeeds only when the key can access every task in the request, so a task-restricted key can batch-trigger only its selected tasks.
100
+
101
+ When no single preset fits, such as a CI key that operates on runs and also deploys, build the key's access with [custom access](/apikeys/custom-access). Your organization can also save custom access as its own preset.
93
102
 
94
103
  ## Deploy with an API key
95
104
 
@@ -110,9 +119,38 @@ The key must belong to the target environment. Use a Production key with `--env
110
119
  CLI login.
111
120
  </Note>
112
121
 
122
+ ## Restrict a key to IP addresses
123
+
124
+ Give a key a list of allowed IP addresses to limit where it can be used. Requests using the key from any other address are rejected, so a leaked key is useless outside your network. They get the same `Invalid API key` error as a key that doesn't exist, so the response never confirms the key is real. If a working key suddenly returns that error, check its allowed IP addresses.
125
+
126
+ - Enter one IPv4 or IPv6 address or CIDR range per line, for example `203.0.113.9` or `203.0.113.0/24`. A key can have up to 50 ranges.
127
+ - Leave the list empty to allow any IP address.
128
+ - Private and reserved ranges, such as `10.0.0.0/8` or `192.168.0.0/16`, are not accepted. Use the public addresses your requests come from.
129
+ - Set the list when you create the key, or change it later with **Edit allowed IPs** in the key's menu. Changes take effect immediately.
130
+ - The API keys page shows the IP address each key was last used from, so you can check it before saving a list.
131
+ - [Public Access Tokens](/realtime/auth) created with the key are not IP-restricted, since they are meant for browsers. Creating one still requires an allowed IP address.
132
+
133
+ <Tip>
134
+ To lock down an environment, give each backend its own IP-restricted key, move your applications
135
+ to those keys, then hide the root key. Your tasks keep working because they don't authenticate
136
+ with your API keys.
137
+ </Tip>
138
+
139
+ ## Change a key's access
140
+
141
+ To change what an existing key can do, click the key on the API keys page to open its details, then click **Edit access**. The key's menu has the same option. Pick another preset or switch to **Custom**, then click **Save access**. The dialog lists what the key gains and loses before you confirm.
142
+
143
+ The key's secret doesn't change, so nothing needs redeploying, and the new access applies to the key's next request. Name, expiry and allowed IP addresses stay as they are. Editing access needs permission to manage API keys in that environment. The root key and revoked or expired keys can't be edited.
144
+
145
+ To remove access a key never uses, click **Narrow to what it used** in the key's details. See [See what a key uses](/apikeys/custom-access#see-what-a-key-uses).
146
+
147
+ ### When a key's access differs from its preset
148
+
149
+ A key keeps the access it was created with. If a preset later grants more or less, keys created before the change don't follow it. When a preset now grants more than a key has, the API keys page marks the key with a dot after the preset name in the **Access** column. Click the key to see which areas the preset now grants, then click **Update to current preset** and **Save access** to update the key.
150
+
113
151
  ## Expire and revoke keys
114
152
 
115
- Set an expiration date when creating a key if the integration only needs temporary access. An expired key stops authenticating automatically.
153
+ Set an expiration date when creating a key if the integration only needs temporary access. A key with a custom date works until the end of that day in UTC. An expired key stops authenticating automatically.
116
154
 
117
155
  Revoking a key takes effect immediately and cannot be reversed. Requests using the key fail, and the key can no longer create public access tokens. Create a replacement before revoking a key when you need to rotate it without interrupting the integration.
118
156
 
@@ -145,7 +183,9 @@ The SDK sends the branch automatically. When calling the API directly, send the
145
183
 
146
184
  ## Self-hosting
147
185
 
148
- Self-hosted installations support multiple keys with **No restrictions**. The restricted access presets are available in Trigger.dev Cloud.
186
+ Self-hosted installations support multiple keys with **No restrictions**. The restricted access presets, custom access, saved presets and key usage are available in Trigger.dev Cloud.
187
+
188
+ IP allowlists use the last address in the `X-Forwarded-For` header, so run the webapp behind a reverse proxy that appends the client IP to that header. To allow private ranges because your clients reach the instance over a private network, set `API_KEY_ALLOW_PRIVATE_IP_RANGES=1`.
149
189
 
150
190
  Keep your instance and SDK current before creating keys. Calling a public-token API with a key on a server that does not support server-minted tokens returns an upgrade error. Upgrade the instance before creating public tokens with an environment API key.
151
191
 
@@ -153,6 +193,7 @@ Keep your instance and SDK current before creating keys. Calling a public-token
153
193
 
154
194
  - Create one key per service or integration instead of sharing keys.
155
195
  - Choose the narrowest access preset and task selection that supports the integration.
196
+ - Restrict keys used from servers with fixed IP addresses to those addresses.
156
197
  - Store keys in a secret manager and inject them as backend environment variables.
157
198
  - Set expiration dates for temporary integrations and deployment credentials.
158
199
  - Revoke keys when an integration or team member no longer needs access.
@@ -24,10 +24,16 @@ yarn dlx trigger.dev@latest login
24
24
 
25
25
  </CodeGroup>
26
26
 
27
+ When the CLI opens your browser, approving the login sends you back to the CLI automatically. If the browser is on another machine, for example when you're connected over SSH, use `--no-browser`: after you approve, the page shows a code to paste into the terminal.
28
+
27
29
  ## Options
28
30
 
29
31
  <ParamField body="No browser" type="--no-browser">
30
- Do not open the browser. Print the URL only.
32
+ Do not open the browser. Print the URL only, and finish the login by pasting the code shown after you approve.
33
+ </ParamField>
34
+
35
+ <ParamField body="Code" type="--code <code>">
36
+ Finish a pending login with the code shown in your browser. Use this after `--no-wait`, or when the terminal can't prompt for the code.
31
37
  </ParamField>
32
38
 
33
39
  <ParamField body="Email" type="--email <email>">
@@ -42,6 +42,14 @@ npx trigger.dev@latest preview archive [path]
42
42
 
43
43
  ## Options
44
44
 
45
+ <ParamField body="Authentication method" type="--auth-method <method>">
46
+ Use `auto` (default) or `oidc`. In GitHub Actions, `auto` uses OIDC when no
47
+ `TRIGGER_ACCESS_TOKEN` is set. Explicit `oidc` ignores stored credentials and tokens.
48
+ See [Trusted publishing](/deployment/trusted-publishing).
49
+ </ParamField>
50
+
51
+ You can also authenticate with a parent Preview environment API key in `TRIGGER_ACCESS_TOKEN`.
52
+
45
53
  <BranchOption />
46
54
 
47
55
  <ConfigFileOption />