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.

Create a separate named key for each service or integration that accesses Trigger.dev.

API keys belong to one environment. A Development key cannot access Production, and a Production key cannot access Staging. Every team member has their own Development environment, so create local-development keys in your own environment.

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: "user@example.com",
});

If you self-host Trigger.dev, set TRIGGER_API_URL or pass baseURL to configure:

TRIGGER_SECRET_KEY="tr_prod_sk_…"
TRIGGER_API_URL="https://trigger.example.com"

The default API URL is https://api.trigger.dev.

Access presets define what a key can do. On the Free and Hobby plans only the No restrictions preset is available. All other presets require the Pro or Enterprise plan.

Trigger only and Task operator can be restricted to selected tasks, up to 10 tasks per key. Task restrictions use task identifiers, such as send-email. A request involving multiple tasks — such as a batch trigger — succeeds only when the key can access every task in the request, so a task-restricted key can batch-trigger only its selected tasks.

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 --env prod

The key must belong to the target environment. Use a Production key with --env prod, a Staging key with --env staging, or a key from the Preview environment with --env preview. If you leave out --env, the CLI deploys to the key's environment, and a --env that doesn't match the key is an error. 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.

API keys can be used to create scoped Public Access Tokens using auth.createPublicToken().

Use @trigger.dev/sdk version 4.5.8 or later to create public tokens with environment API keys. Public tokens have 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 (the default is 15 minutes).

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. Upgrade the instance before creating public tokens with an environment API key.

• 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 for client-side access.