@trigger.dev/sdk 4.5.11 → 4.5.12

package/docs/apikeys.mdx

@@ -1,54 +1,186 @@
 ---
 title: "API keys"
-description: "How to authenticate with Trigger.dev so you can trigger tasks."
+description: "Authenticate backend requests with environment-specific API keys."
 ---
 
-### Authentication and your secret keys
+**API keys authenticate backend requests to a specific Trigger.dev project and environment.** Each environment can have multiple keys, with optional scopes and restrictions attached.
 
-When you [trigger a task](/triggering) from your backend code, you need to set the `TRIGGER_SECRET_KEY` environment variable.
+<Warning>
+  API keys grant access to your Trigger.dev environment. Store them in a secret manager or backend
+  environment variable, never commit them to source control, and never expose them in frontend code.
+</Warning>
 
-Each environment has its own secret key. You can find the value on the API keys page in the Trigger.dev dashboard:
+## Find your API keys
 
-![How to find your secret key](/images/api-keys.png)
+Open your project in the dashboard, select an environment, and open the [**API keys**](https://cloud.trigger.dev/_/apikeys) page.
+
+API keys belong to one environment. A Development key cannot access Production, and a Production key cannot access Staging.
 
 <Note>
-  For preview branches, you need to also set the `TRIGGER_PREVIEW_BRANCH` environment variable as
-  well. You can find the value on the API keys page when you're on the preview branch.
+  Every team member has their own Development environment and keys. Copy the Development key from
+  your own API keys page so local requests run against your machine.
 </Note>
 
-### Automatically Configuring the SDK
+## Configure the SDK
 
-To automatically configure the SDK with your secret key, you can set the `TRIGGER_SECRET_KEY` environment variable. The SDK will automatically use this value when calling API methods (like `trigger`).
+Set `TRIGGER_SECRET_KEY` in your backend environment. The SDK reads it automatically for operations such as triggering tasks and retrieving runs.
 
 ```bash .env
-TRIGGER_SECRET_KEY="tr_dev_…"
-TRIGGER_PREVIEW_BRANCH="my-branch" # Only needed for preview branches
+TRIGGER_SECRET_KEY="tr_prod_sk_…"
+```
+
+To configure the SDK in code, pass the key to `configure`:
+
+```ts Your backend code
+import { configure, tasks } from "@trigger.dev/sdk";
+import type { sendEmail } from "./trigger/send-email";
+
+configure({
+  secretKey: process.env.TRIGGER_SECRET_KEY,
+  previewBranch: "my-branch", // Only needed for preview branches
+  baseURL: "https://mytrigger.example.com", // Optional
+});
+
+await tasks.trigger<typeof sendEmail>("send-email", {
+  to: "user@example.com",
+});
 ```
 
-You can do the same if you are self-hosting and need to change the default URL by using `TRIGGER_API_URL`.
+If you self-host Trigger.dev, set `TRIGGER_API_URL` or pass `baseURL` to `configure`:
 
 ```bash .env
+TRIGGER_SECRET_KEY="tr_prod_…"
 TRIGGER_API_URL="https://trigger.example.com"
-TRIGGER_PREVIEW_BRANCH="my-branch" # Only needed for preview branches
 ```
 
-The default URL is `https://api.trigger.dev`.
+The default API URL is `https://api.trigger.dev`.
+
+## Create a key
 
-### Manually Configuring the SDK
+Create a separate key for each service or integration that accesses Trigger.dev.
 
-If you prefer to manually configure the SDK, you can call the `configure` method:
+<Note>
+  Creating and revoking keys requires permission to manage API keys for the selected environment.
+  The dashboard disables these actions when your role does not have permission.
+</Note>
 
-```ts
-import { configure } from "@trigger.dev/sdk";
-import { myTask } from "./trigger/myTasks";
+<Steps titleSize="h3">
+  <Step title="Open the API keys page">
+    Select the project and environment the integration needs to access, then open [**API keys**](https://cloud.trigger.dev/_/apikeys).
+  </Step>
+  <Step title="Create the key">
+    Click **New API key**, enter a descriptive name, and optionally set an expiration date. Names can
+    contain up to 64 characters.
+  </Step>
+  <Step title="Choose its access">
+    Select an access preset. For task-aware presets, choose all tasks or up to 10 task identifiers.
+  </Step>
+  <Step title="Copy and store the secret">
+    Copy the key into your secret manager or backend environment. Trigger.dev shows the complete
+    value only once.
+  </Step>
+</Steps>
+
+## Access presets
+
+Access presets define what a key can do. Some presets require a paid plan. The dashboard shows which presets your organization can use — see [pricing](https://trigger.dev/pricing).
+
+| Preset | Access |
+| --- | --- |
+| **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 |
+| **Task operator** | Trigger all or selected tasks and inspect or operate on their runs |
+| **Observer** | Read runs, tasks, batches, logs, traces, and queues |
+| **Operator** | Observe and operate on runs and queues, and trigger tasks |
+| **Deploy only** | Deploy versions, sync environment variables, and manage Preview branches |
+| **Variables only** | Read and write environment variables in this environment |
+| **No restrictions** | Full access to the environment |
+
+**Trigger only** and **Task operator** can be restricted to selected tasks. 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.
+
+## Deploy with an API key
+
+Set a key in `TRIGGER_ACCESS_TOKEN` to authenticate `trigger deploy` without logging in.
+
+<CodeGroup>
+
+```bash npm
+TRIGGER_ACCESS_TOKEN="tr_prod_sk_…" npx trigger.dev@latest deploy
+```
+</CodeGroup>
 
-configure({
-  secretKey: "tr_dev_1234", // WARNING: Never actually hardcode your secret key like this
-  previewBranch: "my-branch", // Only needed for preview branches
-  baseURL: "https://mytrigger.example.com", // Optional
-});
+The key must belong to the target environment. Use a Production key for the default deployment, a Staging key with `--env staging`, or a key from the Preview environment with `--env preview`. A Preview deployment key can create and archive Preview branches and sync their environment variables.
+
+<Note>
+  The deploy CLI reads environment API keys from `TRIGGER_ACCESS_TOKEN`, not
+  `TRIGGER_SECRET_KEY`. Setting an API key in `TRIGGER_ACCESS_TOKEN` takes precedence over a saved
+  CLI login.
+</Note>
+
+## Expire and revoke keys
+
+Set an expiration date when creating a key if the integration only needs temporary access. An expired key stops authenticating automatically.
 
-async function triggerTask() {
-  await myTask.trigger({ userId: "1234" }); // This will use the secret key and base URL you configured
-}
+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.
+
+Removing a team member does not revoke keys they created. Review and revoke their keys separately when their access changes.
+
+## Root keys
+
+<Warning>
+  Root keys are legacy, and are likely to be deprecated in the future. We recommend against using them.
+</Warning>
+
+Each environment has a single legacy root key. It can be regenerated, which creates a new value immediately. The previous root key remains valid for 24 hours so you can update services without downtime, then stops authenticating.
+
+Public access tokens signed with the previous root key remain valid until the earlier of their own expiration and the end of the 24-hour grace period.
+
+## Create public access tokens
+
+API keys can be used to create scoped [Public Access Tokens](/realtime/auth) using `auth.createPublicToken()`.
+
+To do so with the newer non-root keys, you must use `@trigger.dev/sdk` version 4.5.8 or later. Creating public tokens with non-root keys has the following restrictions:
+
+- The token must request at least one scope.
+- Its scopes cannot exceed the key's access.
+- Its expiration cannot exceed 30 days.
+
+<Note>
+Revoking or expiring an API key does not revoke tokens it already created. Those tokens remain valid until their own expiration, unless the environment's root key is regenerated.
+</Note>
+
+## Target Preview and Development branches
+
+Preview and named Development branches use their parent environment's keys. Select the branch by setting `TRIGGER_PREVIEW_BRANCH` alongside the environment key:
+
+```bash .env
+TRIGGER_SECRET_KEY="tr_preview_sk_…"
+TRIGGER_PREVIEW_BRANCH="feature/new-checkout"
 ```
+
+The SDK sends the branch automatically. When calling the API directly, send the same value in the `x-trigger-branch` header.
+
+## Self-hosting
+
+Self-hosted installations support multiple keys with **No restrictions**. The restricted access presets are available in Trigger.dev Cloud.
+
+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; use the root key until the server is upgraded.
+
+## Security recommendations
+
+- Create one key per service or integration instead of sharing keys.
+- Choose the narrowest access preset and task selection that supports the integration.
+- Store keys in a secret manager and inject them as backend environment variables.
+- Set expiration dates for temporary integrations and deployment credentials.
+- Revoke keys when an integration or team member no longer needs access.
+- Never put an API key in frontend code. Use scoped [Public Access Tokens](/realtime/auth) for client-side access.
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Trigger tasks" icon="bolt" href="/triggering">
+    Trigger tasks from your backend with an environment API key.
+  </Card>
+  <Card title="Realtime authentication" icon="key" href="/realtime/auth">
+    Create scoped public tokens for frontend and realtime access.
+  </Card>
+</CardGroup>

package/docs/realtime/auth.mdx

@@ -128,9 +128,11 @@ const publicToken = await auth.createPublicToken({
 ```
 
 - If `expirationTime` is a string, it will be treated as a time span
-- If `expirationTime` is a number, it will be treated as a Unix timestamp
+- If `expirationTime` is a number, it will be treated as a Unix timestamp in **seconds**
 - If `expirationTime` is a `Date`, it will be treated as a date
 
+When using non-root API keys (recommended), the expiration cannot be more than 30 days in the future.
+
 The format used for a time span is the same as the [jose package](https://github.com/panva/jose), which is a number followed by a unit. Valid units are: "sec", "secs", "second", "seconds", "s", "minute", "minutes", "min", "mins", "m", "hour", "hours", "hr", "hrs", "h", "day", "days", "d", "week", "weeks", "w", "year", "years", "yr", "yrs", and "y". It is not possible to specify months. 365.25 days is used as an alias for a year. If the string is suffixed with "ago", or prefixed with a "-", the resulting time span gets subtracted from the current unix timestamp. A "from now" suffix can also be used for readability when adding to the current unix timestamp.
 
 ### Auto-generated tokens

package/docs/self-hosting/env/supervisor.mdx

@@ -48,6 +48,7 @@ mode: "wide"
 | `KUBERNETES_NAMESPACE`                      | No       | default     | The namespace that runs should be in.                       |
 | `KUBERNETES_WORKER_NODETYPE_LABEL`          | No       | v4-worker   | Nodes for runs need `nodetype=<this>`. Empty: any node.     |
 | `KUBERNETES_RUNNER_TOLERATIONS`             | No       | —           | Run pod tolerations. CSV: `key=value:effect`/`key:effect`.  |
+| `KUBERNETES_ORG_PLACEMENT_OVERRIDES`        | No       | —           | Per-org run pod placement. JSON keyed by internal org ID.   |
 | `KUBERNETES_IMAGE_PULL_SECRETS`             | No       | —           | Image pull secrets (CSV).                                   |
 | `KUBERNETES_EPHEMERAL_STORAGE_SIZE_LIMIT`   | No       | 10Gi        | Ephemeral storage size limit. Applies to all runs.          |
 | `KUBERNETES_EPHEMERAL_STORAGE_SIZE_REQUEST` | No       | 2Gi         | Ephemeral storage size request. Applies to all runs.        |

package/docs/tasks/scheduled.mdx

@@ -140,6 +140,50 @@ To use imperative schedules you need to do two things:
 1. Define a task in your code using `schedules.task()`.
 2. Attach 1+ schedules to the task either using the dashboard or the SDK.
 
+## Spreading runs with windows
+
+By default a schedule runs at its exact cron time. When many schedules share the same cron pattern, such as a daily `0 9 * * *`, they all fire at the same time and load your downstream systems as well as ours. A **window** spreads those runs out: each schedule is assigned a stable time within the window after its cron time, so the load is smoothed while each schedule keeps firing at a predictable, repeatable moment.
+
+The assigned time is deterministic. A given schedule always lands at the same offset for a given interval, so runs don't jump around between occurrences. And you can always see exactly when the next run will start.
+
+Set a `window` as either:
+
+- **An absolute duration** in whole minutes or hours, up to 24 hours: `"30m"`, `"2h"`, `"24h"`. Absolute windows are capped at the next cron time, so a run is never delayed past its following occurrence.
+- **A percentage** of the interval between runs: `"30%"`, `"100%"`. A `"50%"` window on an hourly schedule spreads runs across the first 30 minutes of each hour.
+
+Set `"0m"` (or `"0%"`) for no spreading — the run fires at its exact cron time.
+
+Declarative schedules set the window on the `cron` object:
+
+```ts
+export const dailyReport = schedules.task({
+  id: "daily-report",
+  cron: {
+    pattern: "0 0 * * *",
+    // spread this run across the 30 minutes after midnight
+    window: "30m",
+  },
+  run: async (payload) => {},
+});
+```
+
+Imperative schedules set it when creating or updating a schedule, either in the dashboard form or through the SDK:
+
+```ts
+const createdSchedule = await schedules.create({
+  task: dailyReport.id,
+  cron: "0 0 * * *",
+  window: "30m",
+  deduplicationKey: "user_123456-daily-report",
+});
+```
+
+<Note>
+  The payload `timestamp` and `upcoming` values are always the nominal cron times, not the assigned
+  times. When you retrieve a schedule, `nextRun` is the nominal cron time and `nextRunEffectiveAt`
+  is the assigned time the run will actually start.
+</Note>
+
 ## Supported cron syntax
 
 ```
@@ -198,6 +242,7 @@ These are the options when creating a schedule:
 | Task              | The id of the task you want to attach to.                                                     |
 | Cron pattern      | The schedule in cron format. You can also describe it in natural language and press "Generate" to fill this in. |
 | Timezone          | The timezone the schedule will run in. Defaults to "UTC"                                      |
+| Window            | An optional [window](#spreading-runs-with-windows) to spread runs after their cron time, e.g. `30m`, `2h`, or `50%`. |
 | External id       | An optional external id, usually you'd use a userId.                                          |
 | Deduplication key | An optional deduplication key. If you pass the same value, it will update rather than create. Scoped per project, not per environment. |
 | Environments      | The environments this schedule will run in.                                                   |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trigger.dev/sdk",
-  "version": "4.5.11",
+  "version": "4.5.12",
   "description": "trigger.dev Node.JS SDK",
   "license": "MIT",
   "publishConfig": {
@@ -66,30 +66,18 @@
   "dependencies": {
     "@opentelemetry/api": "1.9.1",
     "@opentelemetry/semantic-conventions": "1.41.1",
-    "@trigger.dev/core": "4.5.11",
-    "chalk": "^5.2.0",
-    "cronstrue": "^2.21.0",
-    "debug": "^4.3.4",
-    "evt": "^2.4.13",
-    "slug": "^6.0.0",
-    "ulid": "^2.3.0",
-    "uncrypto": "^0.1.3",
-    "ws": "^8.11.0"
+    "@trigger.dev/core": "4.5.12",
+    "uncrypto": "^0.1.3"
   },
   "devDependencies": {
     "@ai-sdk/provider": "3.0.8",
     "@arethetypeswrong/cli": "^0.18.5",
-    "@types/debug": "^4.1.7",
     "@types/react": "^19.2.14",
-    "@types/slug": "^5.0.3",
-    "@types/ws": "^8.5.3",
     "ai": "^6.0.116",
     "ai-v7": "npm:ai@7.0.0-canary.159",
-    "encoding": "^0.1.13",
     "rimraf": "^6.0.1",
     "tshy": "^4.1.3",
     "tsx": "4.17.0",
-    "typed-emitter": "^2.1.0",
     "typescript": "7.0.2",
     "zod": "3.25.76"
   },