@trigger.dev/sdk 4.8.4 → 4.8.6

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 (187) hide show
  1. package/dist/commonjs/v3/ai.d.ts +29 -5
  2. package/dist/commonjs/v3/ai.js +160 -114
  3. package/dist/commonjs/v3/ai.js.map +1 -1
  4. package/dist/commonjs/v3/auth.d.ts +4 -4
  5. package/dist/commonjs/v3/auth.js +21 -75
  6. package/dist/commonjs/v3/auth.js.map +1 -1
  7. package/dist/commonjs/v3/chat-client.d.ts +1 -1
  8. package/dist/commonjs/v3/chat.d.ts +1 -1
  9. package/dist/commonjs/v3/prompt.js +6 -8
  10. package/dist/commonjs/v3/prompt.js.map +1 -1
  11. package/dist/commonjs/v3/runs.d.ts +5 -1
  12. package/dist/commonjs/v3/runs.js.map +1 -1
  13. package/dist/commonjs/v3/sessions.js +10 -7
  14. package/dist/commonjs/v3/sessions.js.map +1 -1
  15. package/dist/commonjs/v3/shared.d.ts +2 -2
  16. package/dist/commonjs/v3/shared.js +16 -15
  17. package/dist/commonjs/v3/shared.js.map +1 -1
  18. package/dist/commonjs/v3/steeringContext.d.ts +35 -10
  19. package/dist/commonjs/v3/steeringContext.js +35 -12
  20. package/dist/commonjs/v3/steeringContext.js.map +1 -1
  21. package/dist/commonjs/v3/streams.js +10 -8
  22. package/dist/commonjs/v3/streams.js.map +1 -1
  23. package/dist/commonjs/v3/tasks.d.ts +2 -2
  24. package/dist/commonjs/v3/tasks.js.map +1 -1
  25. package/dist/commonjs/v3/test/mock-chat-agent.js +24 -13
  26. package/dist/commonjs/v3/test/mock-chat-agent.js.map +1 -1
  27. package/dist/commonjs/v3/webhooks.d.ts +8 -2
  28. package/dist/commonjs/v3/webhooks.js +20 -11
  29. package/dist/commonjs/v3/webhooks.js.map +1 -1
  30. package/dist/commonjs/version.js +1 -1
  31. package/dist/esm/v3/ai.d.ts +29 -5
  32. package/dist/esm/v3/ai.js +162 -117
  33. package/dist/esm/v3/ai.js.map +1 -1
  34. package/dist/esm/v3/auth.d.ts +4 -4
  35. package/dist/esm/v3/auth.js +22 -76
  36. package/dist/esm/v3/auth.js.map +1 -1
  37. package/dist/esm/v3/chat-client.d.ts +1 -1
  38. package/dist/esm/v3/chat.d.ts +1 -1
  39. package/dist/esm/v3/prompt.js +6 -8
  40. package/dist/esm/v3/prompt.js.map +1 -1
  41. package/dist/esm/v3/runs.d.ts +5 -1
  42. package/dist/esm/v3/runs.js.map +1 -1
  43. package/dist/esm/v3/sessions.js +10 -7
  44. package/dist/esm/v3/sessions.js.map +1 -1
  45. package/dist/esm/v3/shared.d.ts +2 -2
  46. package/dist/esm/v3/shared.js +16 -15
  47. package/dist/esm/v3/shared.js.map +1 -1
  48. package/dist/esm/v3/steeringContext.d.ts +35 -10
  49. package/dist/esm/v3/steeringContext.js +34 -12
  50. package/dist/esm/v3/steeringContext.js.map +1 -1
  51. package/dist/esm/v3/streams.js +10 -8
  52. package/dist/esm/v3/streams.js.map +1 -1
  53. package/dist/esm/v3/tasks.d.ts +2 -2
  54. package/dist/esm/v3/tasks.js.map +1 -1
  55. package/dist/esm/v3/test/mock-chat-agent.js +25 -14
  56. package/dist/esm/v3/test/mock-chat-agent.js.map +1 -1
  57. package/dist/esm/v3/webhooks.d.ts +8 -2
  58. package/dist/esm/v3/webhooks.js +20 -11
  59. package/dist/esm/v3/webhooks.js.map +1 -1
  60. package/dist/esm/version.js +1 -1
  61. package/docs/ai/observability.mdx +25 -19
  62. package/docs/ai/prompts.mdx +25 -19
  63. package/docs/ai-chat/actions.mdx +1 -1
  64. package/docs/ai-chat/anatomy.mdx +1 -1
  65. package/docs/ai-chat/backend.mdx +24 -24
  66. package/docs/ai-chat/background-injection.mdx +5 -5
  67. package/docs/ai-chat/chat-local.mdx +2 -2
  68. package/docs/ai-chat/compaction.mdx +38 -15
  69. package/docs/ai-chat/custom-agents.mdx +4 -4
  70. package/docs/ai-chat/error-handling.mdx +4 -4
  71. package/docs/ai-chat/fast-starts.mdx +8 -7
  72. package/docs/ai-chat/frontend.mdx +6 -2
  73. package/docs/ai-chat/lifecycle-hooks.mdx +11 -11
  74. package/docs/ai-chat/migrating-from-a-route-handler.mdx +4 -4
  75. package/docs/ai-chat/migrating-from-hydrate-messages.mdx +1 -1
  76. package/docs/ai-chat/overview.mdx +1 -1
  77. package/docs/ai-chat/patterns/branching-conversations.mdx +1 -1
  78. package/docs/ai-chat/patterns/database-persistence.mdx +2 -2
  79. package/docs/ai-chat/patterns/human-in-the-loop.mdx +1 -1
  80. package/docs/ai-chat/patterns/native-compaction.mdx +29 -9
  81. package/docs/ai-chat/patterns/persistence-and-replay.mdx +1 -1
  82. package/docs/ai-chat/patterns/redacting-telemetry.mdx +2 -2
  83. package/docs/ai-chat/patterns/skills.mdx +2 -2
  84. package/docs/ai-chat/patterns/sub-agents.mdx +1 -1
  85. package/docs/ai-chat/patterns/tool-result-auditing.mdx +1 -1
  86. package/docs/ai-chat/patterns/trusted-edge-signals.mdx +2 -2
  87. package/docs/ai-chat/patterns/version-upgrades.mdx +2 -2
  88. package/docs/ai-chat/pending-messages.mdx +5 -5
  89. package/docs/ai-chat/prompt-caching.mdx +7 -7
  90. package/docs/ai-chat/quick-start.mdx +2 -2
  91. package/docs/ai-chat/testing.mdx +9 -9
  92. package/docs/ai-chat/tools.mdx +9 -5
  93. package/docs/ai-chat/transcript-storage.mdx +2 -2
  94. package/docs/ai-chat/types.mdx +10 -3
  95. package/docs/apikeys.mdx +2 -1
  96. package/docs/cli-login-commands.mdx +12 -0
  97. package/docs/concurrency.mdx +40 -0
  98. package/docs/database-connections.mdx +1 -1
  99. package/docs/deploy-environment-variables.mdx +84 -2
  100. package/docs/deployment/trusted-publishing.mdx +4 -0
  101. package/docs/errors-retrying.mdx +25 -18
  102. package/docs/github-actions.mdx +1 -1
  103. package/docs/github-integration.mdx +21 -0
  104. package/docs/how-it-works.mdx +4 -2
  105. package/docs/introduction.mdx +1 -1
  106. package/docs/mcp-introduction.mdx +7 -1
  107. package/docs/mcp-remote.mdx +90 -0
  108. package/docs/oidc/azure.mdx +81 -0
  109. package/docs/oidc/databricks.mdx +99 -0
  110. package/docs/oidc/doppler.mdx +60 -0
  111. package/docs/oidc/gcp.mdx +109 -0
  112. package/docs/oidc/hugging-face.mdx +90 -0
  113. package/docs/oidc/openrouter.mdx +91 -0
  114. package/docs/oidc/snowflake.mdx +91 -0
  115. package/docs/oidc/vault.mdx +71 -0
  116. package/docs/oidc.mdx +2 -0
  117. package/docs/runs/metadata.mdx +1 -1
  118. package/docs/self-hosting/docker.mdx +2 -0
  119. package/docs/self-hosting/env/webapp.mdx +4 -1
  120. package/docs/self-hosting/kubernetes.mdx +2 -0
  121. package/docs/tasks/schemaTask.mdx +26 -13
  122. package/docs/tasks/streams.mdx +2 -2
  123. package/docs/troubleshooting.mdx +7 -0
  124. package/docs/webhooks/channels.mdx +6 -6
  125. package/docs/webhooks/connect.mdx +9 -75
  126. package/docs/webhooks/custom-providers.mdx +87 -0
  127. package/docs/webhooks/deliveries.mdx +7 -7
  128. package/docs/webhooks/filters.mdx +2 -2
  129. package/docs/webhooks/how-it-works.mdx +58 -0
  130. package/docs/webhooks/human-in-the-loop.mdx +3 -3
  131. package/docs/webhooks/linear.mdx +5 -3
  132. package/docs/webhooks/overview.mdx +20 -71
  133. package/docs/webhooks/own-handler.mdx +62 -0
  134. package/docs/webhooks/pricing-and-limits.mdx +13 -0
  135. package/docs/webhooks/providers/attio.mdx +38 -0
  136. package/docs/webhooks/providers/autumn.mdx +40 -0
  137. package/docs/webhooks/providers/cal-com.mdx +41 -0
  138. package/docs/webhooks/providers/calendly.mdx +41 -0
  139. package/docs/webhooks/providers/clerk.mdx +40 -0
  140. package/docs/webhooks/providers/discord.mdx +45 -0
  141. package/docs/webhooks/providers/docusign.mdx +41 -0
  142. package/docs/webhooks/providers/elevenlabs.mdx +41 -0
  143. package/docs/webhooks/providers/firecrawl.mdx +54 -0
  144. package/docs/webhooks/providers/github.mdx +46 -0
  145. package/docs/webhooks/providers/gitlab.mdx +41 -0
  146. package/docs/webhooks/providers/granola.mdx +44 -0
  147. package/docs/webhooks/providers/hookdeck.mdx +98 -0
  148. package/docs/webhooks/providers/infisical.mdx +41 -0
  149. package/docs/webhooks/providers/jira.mdx +41 -0
  150. package/docs/webhooks/providers/langfuse.mdx +40 -0
  151. package/docs/webhooks/providers/linear.mdx +45 -0
  152. package/docs/webhooks/providers/loops.mdx +40 -0
  153. package/docs/webhooks/providers/metronome.mdx +42 -0
  154. package/docs/webhooks/providers/mux.mdx +40 -0
  155. package/docs/webhooks/providers/openai.mdx +40 -0
  156. package/docs/webhooks/providers/pagerduty.mdx +40 -0
  157. package/docs/webhooks/providers/plain.mdx +41 -0
  158. package/docs/webhooks/providers/planetscale.mdx +40 -0
  159. package/docs/webhooks/providers/recall-ai.mdx +54 -0
  160. package/docs/webhooks/providers/replicate.mdx +41 -0
  161. package/docs/webhooks/providers/resend.mdx +44 -0
  162. package/docs/webhooks/providers/retell.mdx +41 -0
  163. package/docs/webhooks/providers/sentry.mdx +41 -0
  164. package/docs/webhooks/providers/shopify.mdx +49 -0
  165. package/docs/webhooks/providers/slack.mdx +48 -0
  166. package/docs/webhooks/providers/square.mdx +40 -0
  167. package/docs/webhooks/providers/stripe.mdx +86 -0
  168. package/docs/webhooks/providers/supabase.mdx +41 -0
  169. package/docs/webhooks/providers/tailscale.mdx +43 -0
  170. package/docs/webhooks/providers/typeform.mdx +42 -0
  171. package/docs/webhooks/providers/vapi.mdx +47 -0
  172. package/docs/webhooks/providers/vercel.mdx +40 -0
  173. package/docs/webhooks/providers/whatsapp.mdx +45 -0
  174. package/docs/webhooks/providers/workos.mdx +41 -0
  175. package/docs/webhooks/providers/zendesk.mdx +41 -0
  176. package/docs/webhooks/providers.mdx +53 -0
  177. package/docs/webhooks/quick-start.mdx +131 -0
  178. package/docs/webhooks/session-routing.mdx +6 -6
  179. package/docs/webhooks/signing-secrets.mdx +80 -0
  180. package/docs/webhooks/slack.mdx +11 -2
  181. package/docs/webhooks/verification.mdx +139 -0
  182. package/docs/webhooks/waiters.mdx +2 -2
  183. package/docs/webhooks/webhook-tasks.mdx +46 -0
  184. package/package.json +4 -5
  185. package/docs/migrating-from-v3.mdx +0 -332
  186. package/docs/webhooks/public-beta.mdx +0 -70
  187. package/docs/webhooks/sources.mdx +0 -252
@@ -0,0 +1,90 @@
1
+ ---
2
+ title: "Remote MCP server"
3
+ sidebarTitle: "Remote server"
4
+ description: "Connect AI assistants to your Trigger.dev projects over HTTP with OAuth, with no local install."
5
+ ---
6
+
7
+ **The remote MCP server exposes Trigger.dev tools over HTTP at `https://mcp.trigger.dev/mcp`, so an assistant can read runs, trigger tasks, and manage resources without running the CLI.**
8
+
9
+ You sign in with OAuth. Tools that change state need your approval in the dashboard before they run.
10
+
11
+ ## Remote vs. CLI
12
+
13
+ The [CLI MCP server](/mcp-introduction) runs on your machine through `npx trigger.dev@latest mcp`. The remote server runs on Trigger.dev and has no access to your local files or processes.
14
+
15
+ Use the remote server when your client supports HTTP MCP servers, or when you cannot install the CLI. Keep the CLI server for anything that touches your machine. These tools exist only in the CLI server:
16
+
17
+ - `deploy`
18
+ - `start_dev_server`, `stop_dev_server`, `dev_server_status`
19
+ - `whoami`, `list_profiles`, `switch_profile`
20
+ - `initialize_project`
21
+
22
+ Every other tool on the [tools page](/mcp-tools) is available remotely. The endpoint accepts POST only. Other methods return `405`.
23
+
24
+ ## Connect with OAuth
25
+
26
+ OAuth is the default. Your client opens a browser, you approve access on a consent page, and the client stores the tokens.
27
+
28
+ <Tabs>
29
+ <Tab title="Claude Code">
30
+ ```bash
31
+ claude mcp add --transport http trigger https://mcp.trigger.dev/mcp
32
+ ```
33
+
34
+ Run `/mcp` in Claude Code and choose **Authenticate** for `trigger`.
35
+ </Tab>
36
+ <Tab title="Cursor">
37
+ ```json .cursor/mcp.json
38
+ {
39
+ "mcpServers": {
40
+ "trigger": {
41
+ "url": "https://mcp.trigger.dev/mcp"
42
+ }
43
+ }
44
+ }
45
+ ```
46
+ </Tab>
47
+ <Tab title="claude.ai">
48
+ Open **Settings**, then **Connectors**, and add a custom connector with the URL `https://mcp.trigger.dev/mcp`.
49
+ </Tab>
50
+ </Tabs>
51
+
52
+ The server publishes its protected resource metadata at `/.well-known/oauth-protected-resource`. Clients find the authorization server from there. It supports dynamic client registration, client ID metadata documents, and PKCE with `S256`. Composio and similar platforms connect the same way as any other client, through dynamic client registration.
53
+
54
+ An OAuth grant stops working after 30 days without use, and 90 days after it was created. Self-hosters can change both limits (see [self-hosting](#self-hosting)). When a grant expires, the client prompts you to sign in again.
55
+
56
+ ## Scopes
57
+
58
+ Each OAuth grant carries a list of scopes. A tool call is denied if the scopes or your role in the organization don't allow it.
59
+
60
+ | Kind | Scopes |
61
+ | ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
62
+ | Read | `read:alerts`, `read:branches`, `read:deployments`, `read:organizations`, `read:projects`, `read:prompts`, `read:query`, `read:runs`, `read:sessions`, `read:webhooks` |
63
+ | Write | `trigger:tasks`, `update:prompts`, `write:alerts`, `write:projects`, `write:query`, `write:runs`, `write:sessions`, `write:webhooks` |
64
+
65
+ ## Write confirmation
66
+
67
+ Every tool that changes state asks you to approve the exact call first, such as `trigger_task`, `cancel_run`, `replay_run`, or `create_alert`. Read tools never ask.
68
+
69
+ 1. The assistant calls the tool. The server doesn't run it and returns a confirmation link instead.
70
+ 2. Open the link and sign in to the dashboard. The page shows the tool, the organization, project, and environment, and the arguments. Values under keys like `secret`, `token`, or `password` are hidden.
71
+ 3. Select **Approve**.
72
+ 4. Tell the assistant to retry. It calls the same tool with identical arguments, and the call runs once.
73
+
74
+ An approval expires after 10 minutes. It only applies to the same user, token, tool, and arguments, so changing an argument asks again.
75
+
76
+ By default the link comes back as a URL elicitation error, which clients that support it show as a prompt. With `MCP_CONFIRMATION_ERROR_MODE=tool-error` it comes back as a normal tool error with the link in the message.
77
+
78
+ ## Self-hosting
79
+
80
+ The remote server is off by default. Set these environment variables on the webapp:
81
+
82
+ | Variable | Meaning |
83
+ | ----------------------------- | ------------------------------------------------------------------------------------------------- |
84
+ | `MCP_SERVER_ENABLED` | Turns on the `/mcp` endpoint and the OAuth server. Default `false`. |
85
+ | `MCP_ORIGIN` | Origin the MCP server is reached on. Defaults to `APP_ORIGIN`. |
86
+ | `MCP_CONFIRMATION_ERROR_MODE` | How a pending confirmation is reported: `rpc-error` (default) or `tool-error`. |
87
+ | `OAUTH_GRANT_IDLE_DAYS` | Days without use before an OAuth grant stops working. Default `30`. |
88
+ | `OAUTH_GRANT_ABSOLUTE_DAYS` | Maximum lifetime in days of an OAuth grant. Default `90`. |
89
+
90
+ Confirmations are stored in the cache Redis, so the webapp needs the `CACHE_REDIS_*` variables.
@@ -0,0 +1,81 @@
1
+ ---
2
+ title: "Connect to Microsoft Azure"
3
+ sidebarTitle: "Azure"
4
+ description: "Authenticate to Azure from your tasks with a federated identity credential instead of a client secret or certificate."
5
+ ---
6
+
7
+ Use Microsoft Entra [workload identity federation](https://learn.microsoft.com/en-us/entra/workload-id/workload-identity-federation) to exchange a Trigger.dev OIDC token for an Entra access token. Your tasks authenticate as an app registration with no `AZURE_CLIENT_SECRET` or client certificate stored anywhere.
8
+
9
+ Follow the [OIDC prerequisites](/oidc#prerequisites), then go to the [OIDC](https://cloud.trigger.dev/_/oidc) page for your environment and copy the issuer URL and subject.
10
+
11
+ ## Configure Azure
12
+
13
+ 1. [Register an app](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app) in Microsoft Entra ID, or reuse one, and grant it access to the Azure resources your task uses (for the example below, the **Storage Blob Data Reader** role on a storage account).
14
+ 2. In the app registration, open **Certificates & secrets**, select the **Federated credentials** tab, select **Add credential**, and choose the **Other issuer** scenario. Fill in the [federated identity credential](https://learn.microsoft.com/en-us/entra/workload-id/workload-identity-federation-create-trust):
15
+
16
+ | Azure field | Value |
17
+ | ---------------------- | --------------------------------------------------------------------------- |
18
+ | **Issuer** | Your issuer URL, `https://oidc.trigger.dev/YOUR_ORG_SLUG`. |
19
+ | **Subject identifier** | The **complete subject copied from the dashboard**. |
20
+ | **Audience** | `api://AzureADTokenExchange`, Microsoft's recommended value. |
21
+ | **Name** | A name for the credential, for example `trigger-production`. |
22
+
23
+ 3. Copy the app's **Application (client) ID** and **Directory (tenant) ID** from its **Overview** page.
24
+
25
+ Azure compares the issuer and subject exactly and doesn't support wildcards, so each environment needs its own federated credential. An app registration holds at most 20 federated credentials, so use one app per group of environments rather than one credential per Preview branch.
26
+
27
+ ## Use the credential in your task
28
+
29
+ <CodeGroup>
30
+
31
+ ```bash npm
32
+ npm i @trigger.dev/sdk@latest @azure/identity @azure/storage-blob
33
+ ```
34
+
35
+ ```bash pnpm
36
+ pnpm add @trigger.dev/sdk@latest @azure/identity @azure/storage-blob
37
+ ```
38
+
39
+ ```bash bun
40
+ bun add @trigger.dev/sdk@latest @azure/identity @azure/storage-blob
41
+ ```
42
+
43
+ </CodeGroup>
44
+
45
+ `ClientAssertionCredential` from `@azure/identity` calls your function whenever it needs a new Entra token. Return a fresh Trigger.dev OIDC token from it:
46
+
47
+ ```ts /trigger/read-from-azure.ts
48
+ import { auth, task } from "@trigger.dev/sdk";
49
+ import { ClientAssertionCredential } from "@azure/identity";
50
+ import { BlobServiceClient } from "@azure/storage-blob";
51
+
52
+ export const readFromAzure = task({
53
+ id: "read-from-azure",
54
+ run: async () => {
55
+ const credential = new ClientAssertionCredential(
56
+ "YOUR_TENANT_ID",
57
+ "YOUR_CLIENT_ID",
58
+ async () => (await auth.getOIDCToken({ audience: "api://AzureADTokenExchange" })).token
59
+ );
60
+
61
+ const blobs = new BlobServiceClient(
62
+ "https://YOUR_STORAGE_ACCOUNT.blob.core.windows.net",
63
+ credential
64
+ );
65
+ const blob = blobs.getContainerClient("YOUR_CONTAINER").getBlobClient("example.txt");
66
+ const contents = await blob.downloadToBuffer();
67
+
68
+ return { contents: contents.toString() };
69
+ },
70
+ });
71
+ ```
72
+
73
+ The tenant and client IDs aren't secrets. Keep them in `AZURE_TENANT_ID` and `AZURE_CLIENT_ID` if you prefer.
74
+
75
+ Create the credential inside `run` so one run's tokens are never reused by another. Redeploy and start a new run on that deployment.
76
+
77
+ ## Remove the old credential
78
+
79
+ Once runs in every deployed environment authenticate this way, delete `AZURE_CLIENT_SECRET`, `AZURE_CLIENT_CERTIFICATE_PATH`, and `AZURE_CLIENT_CERTIFICATE_PASSWORD` from those environments on the Environment Variables page, then delete the secret or certificate from the app registration.
80
+
81
+ Local Development runs can't mint OIDC tokens. Use your own Azure sign-in there, such as `DefaultAzureCredential` with the Azure CLI, when `ctx.environment.type === "DEVELOPMENT"`.
@@ -0,0 +1,99 @@
1
+ ---
2
+ title: "Connect to Databricks"
3
+ sidebarTitle: "Databricks"
4
+ description: "Authenticate to Databricks from your tasks with a federation policy instead of a personal access token or client secret."
5
+ ---
6
+
7
+ Use Databricks [workload identity federation](https://docs.databricks.com/aws/dev-tools/auth/oauth-federation-policy) to exchange a Trigger.dev OIDC token for a Databricks OAuth token. Your tasks run queries as a service principal with no `DATABRICKS_TOKEN` or `DATABRICKS_CLIENT_SECRET` stored anywhere.
8
+
9
+ Follow the [OIDC prerequisites](/oidc#prerequisites), then go to the [OIDC](https://cloud.trigger.dev/_/oidc) page for your environment and copy the issuer URL and subject.
10
+
11
+ ## Configure Databricks
12
+
13
+ Create a service principal (or reuse one), grant it access to the warehouse and data your task uses, and add a federation policy with the Databricks CLI. Replace the numeric service principal ID, your organization slug, account ID, and the subject:
14
+
15
+ ```bash
16
+ databricks account service-principal-federation-policy create YOUR_SERVICE_PRINCIPAL_NUMERIC_ID --json '{
17
+ "oidc_policy": {
18
+ "issuer": "https://oidc.trigger.dev/YOUR_ORG_SLUG",
19
+ "audiences": ["YOUR_DATABRICKS_ACCOUNT_ID"],
20
+ "subject": "YOUR_ENVIRONMENT_SUBJECT"
21
+ }
22
+ }'
23
+ ```
24
+
25
+ Use the **complete subject copied from the dashboard**. The audience shown is Databricks' default; any value works if the task requests the same one. A service principal holds at most 20 federation policies.
26
+
27
+ ## Query Databricks in your task
28
+
29
+ <CodeGroup>
30
+
31
+ ```bash npm
32
+ npm i @trigger.dev/sdk@latest @databricks/sql
33
+ ```
34
+
35
+ ```bash pnpm
36
+ pnpm add @trigger.dev/sdk@latest @databricks/sql
37
+ ```
38
+
39
+ ```bash bun
40
+ bun add @trigger.dev/sdk@latest @databricks/sql
41
+ ```
42
+
43
+ </CodeGroup>
44
+
45
+ Exchange the OIDC token at your workspace's [token endpoint](https://docs.databricks.com/aws/en/dev-tools/auth/oauth-federation-exchange), then pass the access token to the SQL driver:
46
+
47
+ ```ts /trigger/query-databricks.ts
48
+ import { auth, task } from "@trigger.dev/sdk";
49
+ import { DBSQLClient } from "@databricks/sql";
50
+
51
+ const host = "YOUR_WORKSPACE.cloud.databricks.com";
52
+
53
+ export const queryDatabricks = task({
54
+ id: "query-databricks",
55
+ run: async () => {
56
+ const { token: subjectToken } = await auth.getOIDCToken({
57
+ audience: "YOUR_DATABRICKS_ACCOUNT_ID",
58
+ });
59
+
60
+ const exchange = await fetch(`https://${host}/oidc/v1/token`, {
61
+ method: "POST",
62
+ body: new URLSearchParams({
63
+ client_id: "YOUR_SERVICE_PRINCIPAL_UUID",
64
+ subject_token: subjectToken,
65
+ subject_token_type: "urn:ietf:params:oauth:token-type:jwt",
66
+ grant_type: "urn:ietf:params:oauth:grant-type:token-exchange",
67
+ scope: "all-apis",
68
+ }),
69
+ });
70
+ if (!exchange.ok) throw new Error(`Databricks exchange failed: ${exchange.status}`);
71
+ const { access_token } = await exchange.json();
72
+
73
+ const client = new DBSQLClient();
74
+ await client.connect({ host, path: "/sql/1.0/warehouses/YOUR_WAREHOUSE_ID", token: access_token });
75
+ const session = await client.openSession();
76
+ const operation = await session.executeStatement("SELECT current_user()");
77
+ const rows = await operation.fetchAll();
78
+ await operation.close();
79
+ await session.close();
80
+ await client.close();
81
+
82
+ return { rows };
83
+ },
84
+ });
85
+ ```
86
+
87
+ `client_id` is the service principal's UUID (its application ID), not the numeric ID used in the CLI command.
88
+
89
+ <Note>
90
+ The Databricks access token expires when the OIDC token it was exchanged for does, which is five
91
+ minutes for Trigger.dev tokens, and there's no refresh token. For longer work, request a new OIDC
92
+ token and exchange it again.
93
+ </Note>
94
+
95
+ ## Remove the old credential
96
+
97
+ Once runs in every deployed environment authenticate this way, delete `DATABRICKS_TOKEN` and `DATABRICKS_CLIENT_SECRET` from those environments on the Environment Variables page, then revoke the token or OAuth secret in Databricks.
98
+
99
+ Local Development runs can't mint OIDC tokens. Use your own Databricks login there when `ctx.environment.type === "DEVELOPMENT"`.
@@ -0,0 +1,60 @@
1
+ ---
2
+ title: "Connect to Doppler"
3
+ sidebarTitle: "Doppler"
4
+ description: "Fetch secrets from Doppler in your tasks with a service account identity instead of a stored Doppler token."
5
+ ---
6
+
7
+ Use a Doppler [service account identity](https://docs.doppler.com/docs/service-account-identities) to exchange a Trigger.dev OIDC token for a short-lived Doppler API token. Your tasks fetch secrets with no `DOPPLER_TOKEN` stored anywhere. Service account identities are available on Doppler's Team and Enterprise plans.
8
+
9
+ Follow the [OIDC prerequisites](/oidc#prerequisites), then go to the [OIDC](https://cloud.trigger.dev/_/oidc) page for your environment and copy the issuer URL and subject.
10
+
11
+ ## Configure Doppler
12
+
13
+ 1. In Doppler, create a service account (or reuse one) and give it read access to the project and config your task needs.
14
+ 2. On the service account, add an **Identity** of type OIDC with a custom discovery URL:
15
+
16
+ | Doppler field | Value |
17
+ | ----------------- | ------------------------------------------------------------------------ |
18
+ | **Discovery URL** | Your issuer URL, `https://oidc.trigger.dev/YOUR_ORG_SLUG`. |
19
+ | **Audience** (`aud`) | A value your task requests, for example `https://api.doppler.com`. |
20
+ | **Subject** (`sub`) | The **complete subject copied from the dashboard**. |
21
+
22
+ Doppler requires both the audience and subject claim rules. Use exact values.
23
+
24
+ 3. Copy the **Identity ID**. It's a configuration value, not a secret.
25
+
26
+ ## Fetch secrets in your task
27
+
28
+ ```ts /trigger/read-from-doppler.ts
29
+ import { auth, task } from "@trigger.dev/sdk";
30
+
31
+ export const readFromDoppler = task({
32
+ id: "read-from-doppler",
33
+ run: async () => {
34
+ const { token: oidcToken } = await auth.getOIDCToken({ audience: "https://api.doppler.com" });
35
+
36
+ const exchange = await fetch("https://api.doppler.com/v3/auth/oidc", {
37
+ method: "POST",
38
+ headers: { "Content-Type": "application/json" },
39
+ body: JSON.stringify({ identity: "YOUR_IDENTITY_ID", token: oidcToken }),
40
+ });
41
+ if (!exchange.ok) throw new Error(`Doppler exchange failed: ${exchange.status}`);
42
+ const { token } = await exchange.json();
43
+
44
+ const response = await fetch(
45
+ "https://api.doppler.com/v3/configs/config/secrets/download?project=YOUR_PROJECT&config=prd&format=json",
46
+ { headers: { Authorization: `Bearer ${token}` } }
47
+ );
48
+ const secrets = await response.json();
49
+ // Use secrets.API_KEY here. Never log or return it.
50
+ },
51
+ });
52
+ ```
53
+
54
+ The exchange returns a short-lived API `token` and its `expires_at`. The second request uses Doppler's [download secrets](https://docs.doppler.com/reference/secrets-download) endpoint. Exchange inside `run`, and exchange again if the run outlives `expires_at`.
55
+
56
+ ## Remove the old credential
57
+
58
+ Once runs in every deployed environment fetch secrets this way, delete `DOPPLER_TOKEN` from those environments on the Environment Variables page and revoke the old service token in Doppler.
59
+
60
+ Local Development runs can't mint OIDC tokens. Use the Doppler CLI or your own token there when `ctx.environment.type === "DEVELOPMENT"`.
@@ -0,0 +1,109 @@
1
+ ---
2
+ title: "Connect to Google Cloud"
3
+ sidebarTitle: "Google Cloud"
4
+ description: "Authenticate to Google Cloud from your tasks with workload identity federation instead of a service account key."
5
+ ---
6
+
7
+ Use Google Cloud [workload identity federation](https://docs.cloud.google.com/iam/docs/workload-identity-federation-with-other-providers) to exchange a Trigger.dev OIDC token for a short-lived Google access token. Your tasks call Google Cloud APIs with no service account key in `GOOGLE_APPLICATION_CREDENTIALS` or `GOOGLE_CREDENTIALS`.
8
+
9
+ Follow the [OIDC prerequisites](/oidc#prerequisites), then go to the [OIDC](https://cloud.trigger.dev/_/oidc) page for your environment and copy the issuer URL and subject.
10
+
11
+ ## Configure Google Cloud
12
+
13
+ ### Create a pool and provider
14
+
15
+ Create a workload identity pool, then an OIDC provider in it. Replace the IDs, your organization slug, and your project number:
16
+
17
+ ```bash
18
+ gcloud iam workload-identity-pools create trigger-dev \
19
+ --location="global" \
20
+ --display-name="Trigger.dev"
21
+
22
+ gcloud iam workload-identity-pools providers create-oidc trigger-dev \
23
+ --location="global" \
24
+ --workload-identity-pool="trigger-dev" \
25
+ --issuer-uri="https://oidc.trigger.dev/YOUR_ORG_SLUG" \
26
+ --allowed-audiences="https://iam.googleapis.com/projects/YOUR_PROJECT_NUMBER/locations/global/workloadIdentityPools/trigger-dev/providers/trigger-dev" \
27
+ --attribute-mapping="google.subject=assertion.sub"
28
+ ```
29
+
30
+ The allowed audience is the provider's own resource URL, which your task requests below. The mapping makes each Trigger.dev environment subject a distinct Google principal.
31
+
32
+ <Warning>
33
+ Google limits `google.subject` to [127 characters](https://docs.cloud.google.com/iam/docs/workload-identity-federation).
34
+ Production and Staging subjects are well under that. A Preview subject ends with the branch's
35
+ slug, so a long branch name can push it over the limit and Google rejects the token. Check the
36
+ length of the subject you copy before using it for a Preview environment.
37
+ </Warning>
38
+
39
+ ### Grant access to the subject
40
+
41
+ Grant roles to the principal for the **complete subject copied from the dashboard**. For the example below, allow reading objects in a bucket:
42
+
43
+ ```bash
44
+ gcloud storage buckets add-iam-policy-binding gs://YOUR_BUCKET \
45
+ --role="roles/storage.objectViewer" \
46
+ --member="principal://iam.googleapis.com/projects/YOUR_PROJECT_NUMBER/locations/global/workloadIdentityPools/trigger-dev/subject/YOUR_ENVIRONMENT_SUBJECT"
47
+ ```
48
+
49
+ Some Google APIs don't accept federated principals directly. For those, grant the principal `roles/iam.workloadIdentityUser` on a service account and impersonate it (see `service_account_impersonation_url` below).
50
+
51
+ ## Use the identity in your task
52
+
53
+ <CodeGroup>
54
+
55
+ ```bash npm
56
+ npm i @trigger.dev/sdk@latest google-auth-library @google-cloud/storage
57
+ ```
58
+
59
+ ```bash pnpm
60
+ pnpm add @trigger.dev/sdk@latest google-auth-library @google-cloud/storage
61
+ ```
62
+
63
+ ```bash bun
64
+ bun add @trigger.dev/sdk@latest google-auth-library @google-cloud/storage
65
+ ```
66
+
67
+ </CodeGroup>
68
+
69
+ `IdentityPoolClient` from `google-auth-library` asks a [subject token supplier](https://github.com/googleapis/google-auth-library-nodejs#accessing-resources-from-an-oidc-or-saml20-identity-provider-using-a-custom-supplier) for a token whenever it needs a new Google access token. Return a fresh Trigger.dev OIDC token from it:
70
+
71
+ ```ts /trigger/read-from-gcs.ts
72
+ import { auth, task } from "@trigger.dev/sdk";
73
+ import { IdentityPoolClient } from "google-auth-library";
74
+ import { Storage } from "@google-cloud/storage";
75
+
76
+ const providerUrl =
77
+ "//iam.googleapis.com/projects/YOUR_PROJECT_NUMBER/locations/global/workloadIdentityPools/trigger-dev/providers/trigger-dev";
78
+
79
+ export const readFromGcs = task({
80
+ id: "read-from-gcs",
81
+ run: async () => {
82
+ const authClient = new IdentityPoolClient({
83
+ audience: providerUrl,
84
+ subject_token_type: "urn:ietf:params:oauth:token-type:jwt",
85
+ subject_token_supplier: {
86
+ getSubjectToken: async () =>
87
+ (await auth.getOIDCToken({ audience: `https:${providerUrl}` })).token,
88
+ },
89
+ // To impersonate a service account instead of using the principal directly:
90
+ // service_account_impersonation_url: "https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/YOUR_SA_EMAIL:generateAccessToken",
91
+ });
92
+
93
+ const storage = new Storage({ projectId: "YOUR_PROJECT_ID", authClient });
94
+ const [contents] = await storage.bucket("YOUR_BUCKET").file("example.txt").download();
95
+
96
+ return { contents: contents.toString() };
97
+ },
98
+ });
99
+ ```
100
+
101
+ The STS `audience` is the provider URL without a scheme; the OIDC token's audience is the same URL with `https:`, matching `--allowed-audiences`.
102
+
103
+ Create the client inside `run` so one run's tokens are never reused by another. Redeploy and start a new run on that deployment.
104
+
105
+ ## Remove the old credential
106
+
107
+ Once runs in every deployed environment authenticate this way, delete `GOOGLE_APPLICATION_CREDENTIALS` and `GOOGLE_CREDENTIALS` from those environments on the Environment Variables page, then [delete the service account key](https://docs.cloud.google.com/iam/docs/keys-create-delete#deleting) in Google Cloud.
108
+
109
+ Local Development runs can't mint OIDC tokens. Use your own credentials there, such as `gcloud auth application-default login`, when `ctx.environment.type === "DEVELOPMENT"`.
@@ -0,0 +1,90 @@
1
+ ---
2
+ title: "Connect to Hugging Face"
3
+ sidebarTitle: "Hugging Face"
4
+ description: "Exchange a Trigger.dev OIDC token for a short-lived Hugging Face token to run inference, download gated models or read one repo, without storing an HF_TOKEN."
5
+ ---
6
+
7
+ Use Hugging Face [Trusted Publishers](https://huggingface.co/docs/hub/trusted-publishers) to exchange a Trigger.dev OIDC token for a Hugging Face token that lasts one hour. Your tasks call Inference Providers, download gated models, or read and write one repo with no `HF_TOKEN` stored anywhere.
8
+
9
+ The exchanged token covers less than a user access token. Pick the flavor that matches what your task does:
10
+
11
+ | Configure | On | The token can |
12
+ | --- | --- | --- |
13
+ | CI/CD identity | Your account's [Authentication settings](https://huggingface.co/settings/authentication#ci-cd-access), CI/CD Access | Read gated repos you have access to, and call Inference Providers if you tick **Allow Inference Providers calls** (billed to your account) |
14
+ | Repo trusted publisher | A repo's **Settings**, Trusted Publishers | Write to that one repo, or only read it if you tick **Read-only** |
15
+
16
+ A CI/CD identity token can't read your private repos or write anything; use a repo publisher for those ([security model](https://huggingface.co/docs/hub/trusted-publishers#security-model)).
17
+
18
+ Follow the [OIDC prerequisites](/oidc#prerequisites), then go to the [OIDC](https://cloud.trigger.dev/_/oidc) page for your environment and copy the issuer URL and subject.
19
+
20
+ ## Configure Hugging Face
21
+
22
+ Add a CI/CD identity or a repo trusted publisher, as in the table above. The settings list presets for CI providers, but [any OIDC-compliant provider works](https://huggingface.co/docs/hub/trusted-publishers#supported-ci-providers):
23
+
24
+ - **Issuer**: the issuer URL copied from the dashboard.
25
+ - **Claims**: `sub` set to the **complete subject copied from the dashboard**. Hugging Face matches claims exactly, so each environment needs its own identity or publisher.
26
+
27
+ The audience is fixed: Hugging Face only accepts tokens whose `aud` is `https://huggingface.co`.
28
+
29
+ ## Call Hugging Face in your task
30
+
31
+ <CodeGroup>
32
+
33
+ ```bash npm
34
+ npm i @trigger.dev/sdk@latest @huggingface/inference
35
+ ```
36
+
37
+ ```bash pnpm
38
+ pnpm add @trigger.dev/sdk@latest @huggingface/inference
39
+ ```
40
+
41
+ ```bash bun
42
+ bun add @trigger.dev/sdk@latest @huggingface/inference
43
+ ```
44
+
45
+ </CodeGroup>
46
+
47
+ Exchange the OIDC token at Hugging Face's [token endpoint](https://huggingface.co/docs/hub/trusted-publishers#api-reference), then use the access token wherever you used `HF_TOKEN`. `resource` is your Hugging Face username for a CI/CD identity, or the repo (`namespace/name`, `datasets/namespace/name`) for a repo publisher:
48
+
49
+ ```ts /trigger/hugging-face-inference.ts
50
+ import { auth, task } from "@trigger.dev/sdk";
51
+ import { InferenceClient } from "@huggingface/inference";
52
+
53
+ export const huggingFaceInference = task({
54
+ id: "hugging-face-inference",
55
+ run: async (payload: { prompt: string }) => {
56
+ const { token: subjectToken } = await auth.getOIDCToken({
57
+ audience: "https://huggingface.co",
58
+ });
59
+
60
+ const exchange = await fetch("https://huggingface.co/oauth/token", {
61
+ method: "POST",
62
+ headers: { "Content-Type": "application/json" },
63
+ body: JSON.stringify({
64
+ grant_type: "urn:ietf:params:oauth:grant-type:token-exchange",
65
+ subject_token_type: "urn:ietf:params:oauth:token-type:id_token",
66
+ subject_token: subjectToken,
67
+ resource: "YOUR_HF_USERNAME",
68
+ }),
69
+ });
70
+ if (!exchange.ok) throw new Error(`Hugging Face exchange failed: ${exchange.status}`);
71
+ const { access_token } = await exchange.json();
72
+
73
+ const client = new InferenceClient(access_token);
74
+ const result = await client.chatCompletion({
75
+ model: "meta-llama/Llama-3.1-8B-Instruct",
76
+ messages: [{ role: "user", content: payload.prompt }],
77
+ });
78
+
79
+ return { reply: result.choices[0].message.content };
80
+ },
81
+ });
82
+ ```
83
+
84
+ A failed exchange returns `400` with `invalid_grant` when the issuer, subject or audience doesn't match the identity or publisher. The token lasts 60 minutes with no refresh token, so exchange again for longer work.
85
+
86
+ ## Remove the old credential
87
+
88
+ Once runs in every deployed environment authenticate this way, delete `HF_TOKEN`, `HUGGING_FACE_HUB_TOKEN` and `HUGGINGFACEHUB_API_TOKEN` from those environments on the Environment Variables page, then revoke the access token in your Hugging Face [token settings](https://huggingface.co/settings/tokens).
89
+
90
+ Local Development runs can't mint OIDC tokens. Use your own Hugging Face token there when `ctx.environment.type === "DEVELOPMENT"`.
@@ -0,0 +1,91 @@
1
+ ---
2
+ title: "Connect to OpenRouter"
3
+ sidebarTitle: "OpenRouter"
4
+ description: "Exchange a Trigger.dev OIDC token for a short-lived OpenRouter access token, so your tasks call models without an OPENROUTER_API_KEY."
5
+ ---
6
+
7
+ Use OpenRouter [workload identity federation](https://openrouter.ai/docs/guides/overview/auth/workload-identity-federation) to exchange a Trigger.dev OIDC token for an OpenRouter access token. Your tasks call models with no `OPENROUTER_API_KEY` stored anywhere, and usage is billed to the API key the federation policy acts as, as if that key made the request.
8
+
9
+ <Note>
10
+ Workload identity federation is available on OpenRouter's Business and Enterprise plans, under
11
+ **Settings**, Workload identity.
12
+ </Note>
13
+
14
+ Follow the [OIDC prerequisites](/oidc#prerequisites), then go to the [OIDC](https://cloud.trigger.dev/_/oidc) page for your environment and copy the issuer URL and subject.
15
+
16
+ ## Configure OpenRouter
17
+
18
+ An organization admin sets this up under **Settings**, Workload identity ([set up trust](https://openrouter.ai/docs/guides/overview/auth/workload-identity-federation#set-up-trust)):
19
+
20
+ 1. **Add an issuer.** Set **Issuer URL** to the issuer URL copied from the dashboard and leave **JWKS URL** empty: OpenRouter reads the keys from the issuer's discovery document.
21
+ 2. **Add a policy** for that issuer:
22
+ - **Subject**: the **complete subject copied from the dashboard**. It must match exactly.
23
+ - **Audience**: any value, for example `https://openrouter.ai`. It's required, and your task must request the same one.
24
+ - **Acts as API key**: the workspace API key your tasks use today. A workspace key grants the `inference` scope.
25
+
26
+ Copy the policy's id, shown under its name. Your task sends it with every exchange.
27
+
28
+ ## Call OpenRouter in your task
29
+
30
+ <CodeGroup>
31
+
32
+ ```bash npm
33
+ npm i @trigger.dev/sdk@latest openai
34
+ ```
35
+
36
+ ```bash pnpm
37
+ pnpm add @trigger.dev/sdk@latest openai
38
+ ```
39
+
40
+ ```bash bun
41
+ bun add @trigger.dev/sdk@latest openai
42
+ ```
43
+
44
+ </CodeGroup>
45
+
46
+ Exchange the OIDC token at OpenRouter's [token endpoint](https://openrouter.ai/docs/api/api-reference/oauth/exchange-a-workload-identity-token), then pass the access token as the API key to the OpenAI SDK pointed at [OpenRouter's base URL](https://openrouter.ai/docs/quickstart):
47
+
48
+ ```ts /trigger/openrouter-chat.ts
49
+ import { auth, task } from "@trigger.dev/sdk";
50
+ import OpenAI from "openai";
51
+
52
+ export const openrouterChat = task({
53
+ id: "openrouter-chat",
54
+ run: async (payload: { prompt: string }) => {
55
+ const { token: subjectToken } = await auth.getOIDCToken({
56
+ audience: "https://openrouter.ai",
57
+ });
58
+
59
+ const exchange = await fetch("https://openrouter.ai/api/v1/oauth/token", {
60
+ method: "POST",
61
+ body: new URLSearchParams({
62
+ grant_type: "urn:ietf:params:oauth:grant-type:token-exchange",
63
+ subject_token_type: "urn:ietf:params:oauth:token-type:jwt",
64
+ subject_token: subjectToken,
65
+ federation_policy_id: "YOUR_FEDERATION_POLICY_ID",
66
+ }),
67
+ });
68
+ if (!exchange.ok) throw new Error(`OpenRouter exchange failed: ${exchange.status}`);
69
+ const { access_token } = await exchange.json();
70
+
71
+ const openrouter = new OpenAI({
72
+ baseURL: "https://openrouter.ai/api/v1",
73
+ apiKey: access_token,
74
+ });
75
+ const completion = await openrouter.chat.completions.create({
76
+ model: "openai/gpt-6-luna",
77
+ messages: [{ role: "user", content: payload.prompt }],
78
+ });
79
+
80
+ return { reply: completion.choices[0].message.content };
81
+ },
82
+ });
83
+ ```
84
+
85
+ The access token never outlives the OIDC token it was exchanged for, which is five minutes for Trigger.dev tokens. For longer work, request a new OIDC token and exchange it again. A rejected exchange returns `400` with `invalid_grant` whichever claim failed, so compare the issuer, subject and audience with the policy when it does.
86
+
87
+ ## Remove the old credential
88
+
89
+ Once runs in every deployed environment authenticate this way, delete `OPENROUTER_API_KEY` from those environments on the Environment Variables page. The key itself stays: the policy acts as it. To stop anyone using it directly, create a new workspace key for the policy and delete the old one in OpenRouter.
90
+
91
+ Local Development runs can't mint OIDC tokens. Use your own OpenRouter API key there when `ctx.environment.type === "DEVELOPMENT"`.