@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
@@ -0,0 +1,115 @@
1
+ ---
2
+ title: "CLI webhooks commands"
3
+ sidebarTitle: "webhooks"
4
+ description: "Set or generate the signing secret of a hosted webhook endpoint from your terminal, without printing it."
5
+ ---
6
+
7
+ import CommonOptions from "/snippets/cli-options-common.mdx";
8
+ import ConfigFileOptions from "/snippets/cli-options-config-file.mdx";
9
+ import ProjectRefOptions from "/snippets/cli-options-project-ref.mdx";
10
+
11
+ **These commands store a [webhook endpoint's](/webhooks/overview) signing secret without printing it, so the value stays out of your terminal history, logs and AI agent transcripts.** `endpoint` is the endpoint's declared id (the `id` passed to `webhooks.endpoint.define`) or its `wh_` id.
12
+
13
+ ## Replacing an existing secret
14
+
15
+ When the endpoint already has a secret, both commands ask how long the old one keeps working, with the same choices as the dashboard: stop immediately, 1 hour, 24 hours (the default) or 7 days. In a script or an AI agent, where there's no prompt, pass `--previous-secret-ttl` instead; the command refuses to replace the secret without it, so a rotation can't cut the provider off by accident:
16
+
17
+ ```bash
18
+ npx trigger.dev@latest webhooks set-secret stripe --env prod --from-env STRIPE_WEBHOOK_SECRET --previous-secret-ttl 24h
19
+ ```
20
+
21
+ ## webhooks set-secret
22
+
23
+ Stores the signing secret or public key a provider issued, such as the `whsec_` secret Stripe returns when you create a webhook endpoint. It replaces the endpoint's current secret.
24
+
25
+ Pipe the secret in from the provider's CLI or a file:
26
+
27
+ <CodeGroup>
28
+
29
+ ```bash npm
30
+ stripe webhook_endpoints create -d url="$WEBHOOK_URL" -d "enabled_events[]=checkout.session.completed" \
31
+ | jq -r .secret \
32
+ | npx trigger.dev@latest webhooks set-secret stripe --env prod
33
+ ```
34
+
35
+ ```bash pnpm
36
+ stripe webhook_endpoints create -d url="$WEBHOOK_URL" -d "enabled_events[]=checkout.session.completed" \
37
+ | jq -r .secret \
38
+ | pnpm dlx trigger.dev@latest webhooks set-secret stripe --env prod
39
+ ```
40
+
41
+ ```bash bun
42
+ stripe webhook_endpoints create -d url="$WEBHOOK_URL" -d "enabled_events[]=checkout.session.completed" \
43
+ | jq -r .secret \
44
+ | bunx trigger.dev@latest webhooks set-secret stripe --env prod
45
+ ```
46
+
47
+ </CodeGroup>
48
+
49
+ Or read it from an environment variable. Without `--from-file`, the command checks the shell environment, then the project's `.env`, `.env.development`, `.env.local` and `.env.development.local` files:
50
+
51
+ ```bash
52
+ npx trigger.dev@latest webhooks set-secret stripe --env prod --from-env STRIPE_WEBHOOK_SECRET
53
+ ```
54
+
55
+ Run it in a terminal without either option and it asks for the secret with a masked prompt.
56
+
57
+ <ParamField body="From env" type="--from-env">
58
+ Read the secret from this environment variable.
59
+ </ParamField>
60
+
61
+ <ParamField body="From file" type="--from-file">
62
+ With `--from-env`, read the variable from this `.env` file only.
63
+ </ParamField>
64
+
65
+ <ParamField body="Previous secret TTL" type="--previous-secret-ttl">
66
+ When the endpoint already has a secret, how long the old one keeps working while the provider switches to the new one: seconds (`3600`) or a duration (`1h`, `24h`, `7d`), at most 7 days. `0` stops it straight away, for a secret that leaked.
67
+ </ParamField>
68
+
69
+ ## webhooks generate-secret
70
+
71
+ Generates a new signing secret, for providers that accept a secret you choose, such as GitHub. It replaces the endpoint's current secret.
72
+
73
+ Save it to an env file, then hand it to the provider by variable name:
74
+
75
+ ```bash
76
+ npx trigger.dev@latest webhooks generate-secret github --env prod --to-env GITHUB_WEBHOOK_SECRET
77
+ ```
78
+
79
+ The command writes `GITHUB_WEBHOOK_SECRET` to `.env.local`, creating the file if needed, and prints only where it saved the value. Or pipe it straight into the provider's CLI with `--print`, which outputs the secret and nothing else.
80
+
81
+ When the output isn't a terminal, the command refuses to print the secret unless you pass `--to-env` or `--print`, so an AI agent running it doesn't capture the value by accident.
82
+
83
+ <ParamField body="To env" type="--to-env">
84
+ Save the secret as this variable in an env file.
85
+ </ParamField>
86
+
87
+ <ParamField body="To file" type="--to-file">
88
+ With `--to-env`, the file to save to. Defaults to `.env.local`.
89
+ </ParamField>
90
+
91
+ <ParamField body="Print" type="--print">
92
+ Print only the secret, for piping it into another command.
93
+ </ParamField>
94
+
95
+ <ParamField body="Previous secret TTL" type="--previous-secret-ttl">
96
+ When the endpoint already has a secret, how long the old one keeps working while the provider switches to the new one: seconds (`3600`) or a duration (`1h`, `24h`, `7d`), at most 7 days. `0` stops it straight away, for a secret that leaked.
97
+ </ParamField>
98
+
99
+ ## Options
100
+
101
+ <ParamField body="Environment" type="--env | -e">
102
+ The environment to use: `dev`, `prod`, `staging` or `preview`. Defaults to `prod`.
103
+ </ParamField>
104
+
105
+ <ConfigFileOptions />
106
+ <ProjectRefOptions />
107
+ <ParamField body="Branch" type="--branch | -b">
108
+ The branch to use. Required with `--env preview`.
109
+ </ParamField>
110
+
111
+ ### Common options
112
+
113
+ These options are available on most commands.
114
+
115
+ <CommonOptions />
@@ -337,11 +337,11 @@ import { defineConfig } from "@trigger.dev/sdk";
337
337
  export default defineConfig({
338
338
  project: "<project ref>",
339
339
  // Your other config settings...
340
- runtime: "bun",
340
+ runtime: "bun-1.4",
341
341
  });
342
342
  ```
343
343
 
344
- `bun` runs on Bun 1.3 with a Node.js binary alongside it. `bun-1.4` runs on a Bun-only image with no Node.js binary. See our [Bun guide](/guides/frameworks/bun) for the differences.
344
+ `bun-1.4` runs on a Bun-only image with no Node.js binary. `bun` (Bun 1.3 with a Node.js binary alongside it) is deprecated, and deploys that use it will be rejected from January 5, 2027. See our [Bun guide](/guides/frameworks/bun) for the differences.
345
345
 
346
346
  ### Node.js versions
347
347
 
@@ -24,6 +24,8 @@ yarn dlx trigger.dev@latest deploy
24
24
 
25
25
  </CodeGroup>
26
26
 
27
+ For GitHub Actions workflows without stored API keys, use [Trusted publishing](/deployment/trusted-publishing) with OIDC.
28
+
27
29
  ## Deploying 101
28
30
 
29
31
  Let's assume you have an existing trigger.dev project with a few tasks that you have been running locally but now want to deploy to the Trigger.dev cloud (or your self-hosted instance).
@@ -0,0 +1,140 @@
1
+ ---
2
+ title: "Trusted publishing"
3
+ description: "Deploy from GitHub Actions without storing a Trigger.dev API key."
4
+ ---
5
+
6
+ Trusted publishing uses GitHub Actions OIDC tokens to authorize deployments. No Personal Access Token or environment API key is needed in GitHub secrets. Builds run entirely on Trigger.dev's build server.
7
+
8
+ ## Configure trust
9
+
10
+ 1. Select **Staging**, **Preview**, or **Production**, then open [**Trusted publishing**](https://cloud.trigger.dev/_/trusted-publishing) under **Security**.
11
+ 2. Enter the **Organization or user** and **Repository**, then click **Save**. This repository configuration applies to the whole project.
12
+ 3. Click **Enable** for the selected environment. Choose a **Scope by** option (see [Scope and additional claims](#scope-and-additional-claims)), then click **Save** to allow publishing.
13
+ 4. Configure each environment separately. Preview settings apply to **all Preview branches**.
14
+
15
+ Saved settings appear as a read-only row. Click **Edit** to change them. Deleting environment settings returns to the **Enable** button. Unsaved setup is discarded when you leave the page.
16
+
17
+ Development does not use trusted publishing. Changing the repository or its pinned IDs disables publishing for every environment. Re-save each environment to allow publishing again. Deleting the repository removes its grants.
18
+
19
+ ### Pin GitHub identities
20
+
21
+ Both fields accept a name alone or a name followed by `@ID`:
22
+
23
+ | Field | Name | Pinned identity |
24
+ | --- | --- | --- |
25
+ | Organization or user | `triggerdotdev` | `triggerdotdev@12345` |
26
+ | Repository | `my-project` | `my-project@67890` |
27
+
28
+ Pinning IDs is recommended: names can be reused after renames, transfers, or deletions. Without an ID, the corresponding name is checked instead.
29
+
30
+ Look up both IDs with the GitHub CLI, using an account with access to the repository:
31
+
32
+ ```bash
33
+ gh api repos/OWNER/REPO \
34
+ --jq '{repository_id: .id, repository_owner_id: .owner.id}'
35
+ ```
36
+
37
+ The organization or user uses `repository_owner_id`; the repository uses `repository_id`. These IDs are not secrets. GitHub Actions also exposes them as `GITHUB_REPOSITORY_OWNER_ID` and `GITHUB_REPOSITORY_ID`.
38
+
39
+ ## Scope and additional claims
40
+
41
+ Choose one scope:
42
+
43
+ - **Any branch or tag:** no ref restriction.
44
+ - **Branch:** a branch name such as `main` or `release/*`.
45
+ - **Tag:** a tag name such as `v1.0.0` or `v*`.
46
+ - **Environment:** an exact GitHub Environment name such as `production`. Set `environment: production` on the workflow job and use GitHub's required reviewers or other protections.
47
+
48
+ Branch and tag names support `*` wildcards. Do not include the `refs/heads/` or `refs/tags/` prefix.
49
+
50
+ Additional claims restrict the scope further. Enter a GitHub OIDC token claim name and its accepted values, separated by commas. Every claim must match; any listed value for that claim is accepted. Values match exactly, without wildcards.
51
+
52
+ For example, add `event_name` with `push, workflow_dispatch` to restrict triggers, or `job_workflow_ref` with a reusable workflow's exact ref. You can require a GitHub Environment alongside a branch by adding an `environment` claim.
53
+
54
+ ## Preview environments
55
+
56
+ Preview accepts `pull_request` and non-PR workflows, subject to the saved scope and additional claims.
57
+
58
+ Use **Any branch or tag** or a matching **Environment** scope for PR workflows. GitHub's PR ref is typically `refs/pull/NUMBER/merge`, so it does not match a Branch scope such as `main`.
59
+
60
+ From a `pull_request` workflow, deploy to a Preview branch using:
61
+
62
+ ```bash
63
+ npx trigger.dev@latest deploy \
64
+ --auth-method oidc \
65
+ --native-build \
66
+ --env preview \
67
+ --branch "$GITHUB_HEAD_REF"
68
+ ```
69
+
70
+ A Preview deploy for a closed or merged PR archives its branch instead of creating a deployment. You can also archive explicitly from a cleanup job with `id-token: write`:
71
+
72
+ ```bash
73
+ npx trigger.dev@latest preview archive \
74
+ --auth-method oidc \
75
+ --branch "$GITHUB_HEAD_REF"
76
+ ```
77
+
78
+ The workflow must match the project's **Preview** trusted-publishing settings. It can archive any Preview branch in that project, regardless of the workflow's current branch. Archiving preserves branch history; an already archived or missing branch is a successful no-op.
79
+
80
+ `pull_request_target` and other PR event types such as `pull_request_review` are not supported for Preview. Staging and Production reject `pull_request*` events.
81
+
82
+ ## GitHub Actions workflow
83
+
84
+ This example assumes a pnpm project with a lockfile and a `packageManager` field in `package.json`. Set `project` in `trigger.config.ts` (or `TRIGGER_PROJECT_REF`) to the project where you configured trust.
85
+
86
+ ```yaml .github/workflows/trigger-deploy.yml
87
+ name: Deploy to Trigger.dev
88
+
89
+ on:
90
+ push:
91
+ branches: [main]
92
+
93
+ permissions:
94
+ contents: read
95
+ id-token: write
96
+
97
+ jobs:
98
+ deploy:
99
+ runs-on: ubuntu-latest
100
+ # Add environment: production if your publishing scope requires it.
101
+ steps:
102
+ - uses: actions/checkout@v7.0.1
103
+ - uses: actions/setup-node@v7
104
+ with:
105
+ node-version: "24"
106
+ - uses: pnpm/action-setup@v6
107
+ - run: pnpm install --frozen-lockfile
108
+ - run: |
109
+ npx trigger.dev@latest deploy \
110
+ --auth-method oidc \
111
+ --native-build \
112
+ --env prod
113
+ ```
114
+
115
+ For Staging, use `--env staging`. For Preview, use `--env preview --branch YOUR_PREVIEW_BRANCH`.
116
+
117
+ Open **Deployments > Deploys** in the target environment and confirm the new deployment succeeded.
118
+
119
+ `--auth-method oidc` ignores stored credentials and `TRIGGER_ACCESS_TOKEN`. Without that flag, an explicit `TRIGGER_ACCESS_TOKEN` takes precedence over GitHub OIDC, which takes precedence over a saved login.
120
+
121
+ ## Promote a deployment
122
+
123
+ To promote a version deployed with `--skip-promotion`, run:
124
+
125
+ ```bash
126
+ npx trigger.dev@latest promote VERSION --auth-method oidc --env prod
127
+ ```
128
+
129
+ Use `--env staging` or `--env preview --branch BRANCH` for other environments. Promotion requires the target environment's trusted-publishing settings, including any GitHub Environment or additional-claim restrictions. It cannot promote a version from a different environment or roll back to an older version.
130
+
131
+ `preview archive` and `promote` use the same automatic OIDC selection and `--auth-method oidc` override as `deploy`. `preview archive` also accepts a parent Preview environment API key through `TRIGGER_ACCESS_TOKEN`.
132
+
133
+ ## Limits and troubleshooting
134
+
135
+ - Only full build-server builds are supported. Local builds, Depot builds, `--local-bundle`, `--from-bundle`, and `--dry-run` are not supported.
136
+ - The CLI receives no Trigger.dev API key or permission to read or sync environment variables. That work happens inside the build server. Authorized build and task code can still access the target environment's secrets.
137
+ - Submissions are not automatically retried. If a response is lost, check the dashboard before deploying again.
138
+ - If authorization fails, check the project ref, pinned IDs, saved environment settings, scope, additional claims, and `id-token: write` permission.
139
+
140
+ This is separate from [task OIDC](/oidc), which lets running tasks access external services. For API-key authentication, see [CI / GitHub Actions](/github-actions).
@@ -1,9 +1,9 @@
1
1
  ---
2
2
  title: "CI / GitHub Actions"
3
- description: "Deploy your tasks from GitHub Actions and other CI environments using an environment API key."
3
+ description: "Deploy your tasks from CI using trusted deploys or an environment API key."
4
4
  ---
5
5
 
6
- The instructions below are specific to GitHub Actions, but the same concepts apply to other CI systems. Use an environment API key rather than a Personal Access Token so deployments are not tied to an individual team member's account or permissions.
6
+ For GitHub Actions without stored credentials, use [Trusted publishing](/deployment/trusted-publishing) with OIDC. The API-key instructions below also apply to other CI systems. Use an environment API key rather than a Personal Access Token so deployments are not tied to an individual team member's account or permissions.
7
7
 
8
8
  <Tip>
9
9
  Check out our new [GitHub integration](/github-integration) for automatic deployments, without adding any GitHub Actions workflows.
@@ -72,6 +72,27 @@ The name of the preview branch matches the branch name of the pull request.
72
72
  Preview branch deployments require the preview environment to be enabled on your project. Learn more about [preview branches](/deployment/preview-branches).
73
73
  </Note>
74
74
 
75
+ ## Ignored paths
76
+
77
+ Skip builds for pushes that only touch files your tasks do not depend on, such as docs or another app in a monorepo.
78
+
79
+ Open **Integrations** in your project settings and add the patterns in the git settings panel below the branch fields, one per line. A push builds unless every file changed by the pushed commits matches a pattern. A newly opened pull request compares every file it changes against its base branch in the same way. Some pushes build regardless of the patterns, such as force pushes or pushes that change 300 or more files. Use **Test a path** to check which pattern, if any, ignores a given file.
80
+
81
+ ```text
82
+ docs/**
83
+ **/*.md
84
+ apps/web/**
85
+ .github/**
86
+ ```
87
+
88
+ Patterns are globs relative to the repository root and match like `paths-ignore` in GitHub Actions. `**` matches across folders and also matches dotfiles, so `**/*.md` ignores `.github/PULL_REQUEST_TEMPLATE.md`. Negation (`!`), braces (`{a,b}`), extglob groups like `+(...)` and `[!...]` are not supported; use `[^...]` to exclude characters. You can add up to 100 patterns of up to 256 characters each.
89
+
90
+ When a build is skipped, no deployment is created and the commit's Trigger.dev check is marked as skipped, with the matched patterns in its summary. Re-run that check from GitHub to build the commit anyway.
91
+
92
+ <Note>
93
+ Projects connected to Vercel always build. See [production waits for your tasks](/vercel-integration#production-waits-for-your-tasks).
94
+ </Note>
95
+
75
96
  ## Version skew protection
76
97
 
77
98
  Every deployment the GitHub integration creates is tagged with the commit SHA it was built from. That is the deploy half of [version skew protection](/deployment/atomic-deployment) — you get it for free.
@@ -0,0 +1,187 @@
1
+ ---
2
+ title: "Connect to Anthropic"
3
+ sidebarTitle: "Anthropic"
4
+ description: "Call Claude from your tasks and chat agents without storing an Anthropic API key."
5
+ ---
6
+
7
+ Use Anthropic's [workload identity federation](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation) to exchange a Trigger.dev OIDC token for a short-lived Claude API token. Your tasks and [chat agents](/ai-chat/overview) call Claude with no `ANTHROPIC_API_KEY` stored anywhere.
8
+
9
+ You configure Anthropic to trust your Trigger.dev environment, store three IDs as environment variables, and give the AI SDK's Anthropic provider a token function.
10
+
11
+ Follow the [OIDC prerequisites](/oidc#prerequisites). You also need the admin or owner role in your Anthropic organization.
12
+
13
+ ## Configure Anthropic
14
+
15
+ Go to the [OIDC](https://cloud.trigger.dev/_/oidc) page for your Trigger.dev environment and copy the issuer URL and subject. Then open [Workload identity](https://platform.claude.com/settings/workload-identity-federation) in the Claude Console, select **Connect workload**, and choose **Custom OIDC**.
16
+
17
+ <Steps>
18
+ <Step title="Issuer">
19
+ | Field | Value |
20
+ | --- | --- |
21
+ | **Issuer URL** | Your issuer URL, `https://oidc.trigger.dev/YOUR_ORG_SLUG`, with no trailing slash. |
22
+ | **Discovery URL override** | Leave blank. |
23
+ | **CA certificate** | Leave blank. |
24
+ | **Enforce single-use tokens** | Leave enabled. Trigger.dev tokens carry a unique `jti`. |
25
+ | **Maximum token lifetime** | Leave at 1 hour. Trigger.dev tokens expire after five minutes. |
26
+
27
+ Confirm that the discovery document and JWKS are reachable from the public internet, then continue. The Console fetches your signing keys at this step.
28
+ </Step>
29
+ <Step title="Federation rule">
30
+ Name the rule, then paste the **complete subject copied from the dashboard** into **Subject (sub) claim**. Leave **Additional claim condition** blank.
31
+
32
+ Under **Enable in workspaces**, select a single workspace. Tokens minted by the rule are billed to it and follow its rate limits.
33
+
34
+ The default scope, `workspace:developer`, matches a workspace API key. If your tasks only call the Messages API, open **Advanced rule options** and set it to `workspace:inference`.
35
+ </Step>
36
+ <Step title="Target">
37
+ Choose **Create a new one** and name the service account, for example `trigger-production`. It joins the rule's workspace automatically.
38
+ </Step>
39
+ <Step title="Test">
40
+ The Console shows a token exchange snippet. Copy the `federation_rule_id` (`fdrl_...`), `organization_id`, and `service_account_id` (`svac_...`) from it. The Console listens for a first exchange for 15 minutes; if that window passes, run the test again from the rule's page.
41
+ </Step>
42
+ </Steps>
43
+
44
+ Anthropic requires the audience `https://api.anthropic.com`, so request that audience when minting tokens for this rule.
45
+
46
+ ## Store the IDs
47
+
48
+ Add the three IDs as environment variables on the Trigger.dev environment. None of them is a secret.
49
+
50
+ ```bash .env
51
+ ANTHROPIC_FEDERATION_RULE_ID=fdrl_...
52
+ ANTHROPIC_ORGANIZATION_ID=00000000-0000-0000-0000-000000000000
53
+ ANTHROPIC_SERVICE_ACCOUNT_ID=svac_...
54
+ ```
55
+
56
+ The provider below always authenticates with the federated token, even if `ANTHROPIC_API_KEY` is set. Once federation works, delete the old API key in the Claude Console and remove it from the environment.
57
+
58
+ ## Install the packages
59
+
60
+ <CodeGroup>
61
+
62
+ ```bash npm
63
+ npm i @trigger.dev/sdk@latest @anthropic-ai/sdk@latest @ai-sdk/anthropic@latest ai@latest
64
+ ```
65
+
66
+ ```bash pnpm
67
+ pnpm add @trigger.dev/sdk@latest @anthropic-ai/sdk@latest @ai-sdk/anthropic@latest ai@latest
68
+ ```
69
+
70
+ ```bash bun
71
+ bun add @trigger.dev/sdk@latest @anthropic-ai/sdk@latest @ai-sdk/anthropic@latest ai@latest
72
+ ```
73
+
74
+ </CodeGroup>
75
+
76
+ ## Create the Claude provider
77
+
78
+ `oidcFederationProvider` from the Anthropic SDK performs the exchange, and `TokenCache` reuses the resulting token until shortly before it expires. The AI SDK's Anthropic provider calls `authToken` before each request.
79
+
80
+ ```ts /trigger/claude.ts
81
+ import { auth } from "@trigger.dev/sdk";
82
+ import { createAnthropic } from "@ai-sdk/anthropic";
83
+ import { oidcFederationProvider } from "@anthropic-ai/sdk/lib/credentials/oidc-federation";
84
+ import { TokenCache } from "@anthropic-ai/sdk/lib/credentials/token-cache";
85
+
86
+ export function claude() {
87
+ const anthropicToken = new TokenCache(
88
+ oidcFederationProvider({
89
+ // Anthropic accepts each token's jti once, so mint a fresh one per exchange.
90
+ identityTokenProvider: async () => {
91
+ const { token } = await auth.getOIDCToken({ audience: "https://api.anthropic.com" });
92
+ return token;
93
+ },
94
+ federationRuleId: process.env.ANTHROPIC_FEDERATION_RULE_ID!,
95
+ organizationId: process.env.ANTHROPIC_ORGANIZATION_ID!,
96
+ serviceAccountId: process.env.ANTHROPIC_SERVICE_ACCOUNT_ID!,
97
+ baseURL: "https://api.anthropic.com",
98
+ fetch,
99
+ })
100
+ );
101
+
102
+ return createAnthropic({ authToken: () => anthropicToken.getToken() });
103
+ }
104
+ ```
105
+
106
+ If your rule is enabled in more than one workspace, also pass `workspaceId` (`wrkspc_...`) to `oidcFederationProvider`.
107
+
108
+ ## Use it in a chat agent
109
+
110
+ Create the provider inside `run`, so a cached Anthropic token never outlives the run.
111
+
112
+ ```ts /trigger/chat.ts
113
+ import { chat } from "@trigger.dev/sdk/ai";
114
+ import { stepCountIs } from "ai";
115
+ import { claude } from "./claude";
116
+
117
+ export const supportChat = chat.agent({
118
+ id: "support-chat",
119
+ run: async ({ messages, signal, streamText }) => {
120
+ const anthropic = claude();
121
+
122
+ return streamText({
123
+ model: anthropic("claude-sonnet-5-5"),
124
+ messages,
125
+ abortSignal: signal,
126
+ stopWhen: stepCountIs(10),
127
+ });
128
+ },
129
+ });
130
+ ```
131
+
132
+ <Warning>
133
+ Don't create the provider at module scope or store it in [`chat.local`](/ai-chat/chat-local). A module-scope cache can serve one run's token to the next run in the same process, and `chat.local` values are copied into subtask metadata.
134
+ </Warning>
135
+
136
+ Each turn performs one exchange, and every model call in the turn, including tool-call steps, reuses that token.
137
+
138
+ ## Use it in a task
139
+
140
+ The same provider works with any AI SDK function:
141
+
142
+ ```ts /trigger/summarize.ts
143
+ import { task } from "@trigger.dev/sdk";
144
+ import { generateText } from "ai";
145
+ import { claude } from "./claude";
146
+
147
+ export const summarize = task({
148
+ id: "summarize",
149
+ run: async (payload: { text: string }) => {
150
+ const anthropic = claude();
151
+
152
+ const { text } = await generateText({
153
+ model: anthropic("claude-sonnet-5-5"),
154
+ prompt: `Summarize in two sentences:\n\n${payload.text}`,
155
+ });
156
+
157
+ return { summary: text };
158
+ },
159
+ });
160
+ ```
161
+
162
+ ## How tokens are refreshed
163
+
164
+ - **The exchange.** `oidcFederationProvider` posts the Trigger.dev token to `https://api.anthropic.com/v1/oauth/token` using the RFC 7523 `jwt-bearer` grant. Anthropic verifies it against your issuer's JWKS and the rule, then returns an access token prefixed `sk-ant-oat01-`.
165
+ - **Lifetime.** The Anthropic token lasts the shorter of the rule's token lifetime and twice the remaining lifetime of the Trigger.dev token, so expect about 10 minutes.
166
+ - **Refresh.** `TokenCache` returns the cached token until two minutes before expiry, then exchanges again in the background. Each exchange calls `identityTokenProvider`, which requests a new Trigger.dev token.
167
+
168
+ ## Verify the connection
169
+
170
+ Redeploy, then run `summarize` or send a message to `support-chat`. A successful exchange appears in the [authentication history](https://platform.claude.com/settings/workload-identity-federation?tab=history) in the Claude Console, attributed to the service account.
171
+
172
+ For local Development runs, which cannot mint OIDC tokens, use your own API key: when `ctx.environment.type === "DEVELOPMENT"`, return `createAnthropic()` instead, which reads `ANTHROPIC_API_KEY`.
173
+
174
+ ## Troubleshooting
175
+
176
+ ### Authentication failed
177
+
178
+ Anthropic returns the same `Authentication failed` error for every rejected exchange. Open the [authentication history](https://platform.claude.com/settings/workload-identity-federation?tab=history) to see the reason, then fix the mismatch:
179
+
180
+ - **Issuer mismatch:** the rule's issuer URL must equal the token's `iss` exactly, including the absence of a trailing slash.
181
+ - **Subject mismatch:** paste the complete subject from the dashboard. Preview branches use the individual branch's subject.
182
+ - **`jti_reused`:** a token was exchanged twice. Keep `identityTokenProvider` requesting a new token on every call instead of caching one.
183
+ - **`workspace_id_required`:** the rule is enabled in more than one workspace. Pass `workspaceId` to `oidcFederationProvider`.
184
+
185
+ ### Credit balance is too low
186
+
187
+ The exchange succeeded and the API accepted the token; the workspace has no credits. Add credits under **Plans & Billing** in the Claude Console.