docs/apikeys.mdx
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.
<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>Open your project in the dashboard, select an environment, and open the API keys page.
API keys belong to one environment. A Development key cannot access Production, and a Production key cannot access Staging.
<Note> 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>Set TRIGGER_SECRET_KEY in your backend environment. The SDK reads it automatically for operations such as triggering tasks and retrieving runs.
TRIGGER_SECRET_KEY="tr_prod_sk_…"
To configure the SDK in code, pass the key to configure:
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: "[email protected]",
});
If you self-host Trigger.dev, set TRIGGER_API_URL or pass baseURL to configure:
TRIGGER_SECRET_KEY="tr_prod_…"
TRIGGER_API_URL="https://trigger.example.com"
The default API URL is https://api.trigger.dev.
Create a separate key for each service or integration that accesses Trigger.dev.
<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> <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 define what a key can do. Some presets require a paid plan. The dashboard shows which presets your organization can use — see 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.
Set a key in TRIGGER_ACCESS_TOKEN to authenticate trigger deploy without logging in.
TRIGGER_ACCESS_TOKEN="tr_prod_sk_…" npx trigger.dev@latest deploy
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.
Set an expiration date when creating a key if the integration only needs temporary access. An expired key stops authenticating automatically.
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.
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.
API keys can be used to create scoped Public Access Tokens 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:
Preview and named Development branches use their parent environment's keys. Select the branch by setting TRIGGER_PREVIEW_BRANCH alongside the environment key:
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-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.