API 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.

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.

Find your API keys

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.

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.

Configure the SDK

Set TRIGGER_SECRET_KEY in your backend environment. The SDK reads it automatically for operations such as triggering tasks and retrieving runs.

.env

TRIGGER_SECRET_KEY="tr_prod_sk_…"

To configure the SDK in code, pass the key to configure:

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",
});

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

.env

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

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

Create a key

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

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.

Open the API keys page

Select the project and environment the integration needs to access, then open API keys.

Create the key

Click New API key, enter a descriptive name, and optionally set an expiration date. Names can contain up to 64 characters.

Choose its access

Select an access preset. For task-aware presets, choose all tasks or up to 10 task identifiers.

Copy and store the secret

Copy the key into your secret manager or backend environment. Trigger.dev shows the complete value only once.

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.

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.

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.

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.

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. 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

Root keys are legacy, and are likely to be deprecated in the future. We recommend against using them.

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 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.

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.

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:

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

Getting started

Fundamentals

Building with AI

Writing tasks

Agents

Configuration

Deployment

Private networking

Realtime

CLI

Observability

Using the Dashboard

Troubleshooting

Self-hosting

Open source

Help

Find your API keys

Configure the SDK

Create a key

Open the API keys page

Create the key

Choose its access

Copy and store the secret

Access presets

Deploy with an API key

Expire and revoke keys

Root keys

Create public access tokens

Target Preview and Development branches

Self-hosting

Security recommendations

Next steps

Trigger tasks

Realtime authentication

​Find your API keys

​Configure the SDK

​Create a key

Open the API keys page

Create the key

Choose its access

Copy and store the secret

​Access presets

​Deploy with an API key

​Expire and revoke keys

​Root keys

​Create public access tokens

​Target Preview and Development branches

​Self-hosting

​Security recommendations

​Next steps

Trigger tasks

Realtime authentication

Find your API keys

Configure the SDK

Create a key

Access presets

Deploy with an API key

Expire and revoke keys

Root keys

Create public access tokens

Target Preview and Development branches

Self-hosting

Security recommendations

Next steps