@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.
- package/dist/commonjs/v3/ai-shared.d.ts +3 -2
- package/dist/commonjs/v3/ai-shared.js +219 -28
- package/dist/commonjs/v3/ai-shared.js.map +1 -1
- package/dist/commonjs/v3/ai.d.ts +4 -0
- package/dist/commonjs/v3/ai.js +97 -87
- package/dist/commonjs/v3/ai.js.map +1 -1
- package/dist/commonjs/v3/auth.d.ts +11 -4
- package/dist/commonjs/v3/auth.js +9 -8
- package/dist/commonjs/v3/auth.js.map +1 -1
- package/dist/commonjs/v3/chat-server.js +3 -1
- package/dist/commonjs/v3/chat-server.js.map +1 -1
- package/dist/commonjs/v3/chat.js +26 -6
- package/dist/commonjs/v3/chat.js.map +1 -1
- package/dist/commonjs/v3/index.d.ts +1 -1
- package/dist/commonjs/v3/index.js +2 -1
- package/dist/commonjs/v3/index.js.map +1 -1
- package/dist/commonjs/v3/oidc/aws.d.ts +24 -0
- package/dist/commonjs/v3/oidc/aws.js +46 -0
- package/dist/commonjs/v3/oidc/aws.js.map +1 -0
- package/dist/commonjs/v3/oidc/infisical.d.ts +16 -0
- package/dist/commonjs/v3/oidc/infisical.js +43 -0
- package/dist/commonjs/v3/oidc/infisical.js.map +1 -0
- package/dist/commonjs/version.js +1 -1
- package/dist/esm/v3/ai-shared.d.ts +3 -2
- package/dist/esm/v3/ai-shared.js +214 -28
- package/dist/esm/v3/ai-shared.js.map +1 -1
- package/dist/esm/v3/ai.d.ts +4 -0
- package/dist/esm/v3/ai.js +98 -88
- package/dist/esm/v3/ai.js.map +1 -1
- package/dist/esm/v3/auth.d.ts +11 -4
- package/dist/esm/v3/auth.js +9 -8
- package/dist/esm/v3/auth.js.map +1 -1
- package/dist/esm/v3/chat-server.js +4 -2
- package/dist/esm/v3/chat-server.js.map +1 -1
- package/dist/esm/v3/chat.js +26 -6
- package/dist/esm/v3/chat.js.map +1 -1
- package/dist/esm/v3/index.d.ts +1 -1
- package/dist/esm/v3/index.js +1 -1
- package/dist/esm/v3/index.js.map +1 -1
- package/dist/esm/v3/oidc/aws.d.ts +24 -0
- package/dist/esm/v3/oidc/aws.js +43 -0
- package/dist/esm/v3/oidc/aws.js.map +1 -0
- package/dist/esm/v3/oidc/infisical.d.ts +16 -0
- package/dist/esm/v3/oidc/infisical.js +40 -0
- package/dist/esm/v3/oidc/infisical.js.map +1 -0
- package/dist/esm/version.js +1 -1
- package/docs/ai-chat/backend.mdx +2 -2
- package/docs/ai-chat/custom-agents.mdx +8 -1
- package/docs/ai-chat/frontend.mdx +1 -1
- package/docs/ai-chat/lifecycle-hooks.mdx +4 -0
- package/docs/ai-chat/migrating-from-hydrate-messages.mdx +1 -1
- package/docs/ai-chat/transcript-storage.mdx +3 -1
- package/docs/apikeys/custom-access.mdx +209 -0
- package/docs/apikeys.mdx +54 -13
- package/docs/cli-login-commands.mdx +7 -1
- package/docs/cli-preview-archive.mdx +8 -0
- package/docs/cli-webhooks-commands.mdx +115 -0
- package/docs/config/config-file.mdx +2 -2
- package/docs/deployment/overview.mdx +2 -0
- package/docs/deployment/trusted-publishing.mdx +140 -0
- package/docs/github-actions.mdx +2 -2
- package/docs/github-integration.mdx +21 -0
- package/docs/oidc/anthropic.mdx +187 -0
- package/docs/oidc/aws.mdx +219 -0
- package/docs/oidc/custom.mdx +48 -0
- package/docs/oidc/infisical.mdx +59 -0
- package/docs/oidc.mdx +75 -0
- package/docs/self-hosting/env/webapp.mdx +7 -0
- package/docs/webhooks/connect.mdx +12 -0
- package/docs/webhooks/public-beta.mdx +70 -0
- package/package.json +37 -2
package/dist/esm/v3/index.js.map
CHANGED
|
@@ -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"}
|
package/dist/esm/version.js
CHANGED
|
@@ -1,2 +1,2 @@
|
|
|
1
|
-
export const VERSION = "4.8.
|
|
1
|
+
export const VERSION = "4.8.4";
|
|
2
2
|
//# sourceMappingURL=version.js.map
|
package/docs/ai-chat/backend.mdx
CHANGED
|
@@ -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
|
-
? [
|
|
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` |
|
|
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 **
|
|
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
|
-
|
|
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.
|
|
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
|
|
85
|
-
| **Operator** | Observe and operate on runs, queues, errors, and
|
|
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,
|
|
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
|
|
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 />
|