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.

To access AWS or another external service from a deployed task without stored cloud keys, use workload identity. Trigger.dev API keys cannot mint OIDC tokens.

Create an API key

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.

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 Create API key, enter a descriptive name, and choose when it expires: in 30 days, 90 days (the default), or 1 year, on a custom date, or never. Names can contain up to 64 characters. To restrict the key to your servers, list their IP addresses.

Choose its access

Select the narrowest access preset that supports the integration. For task-aware presets, choose all tasks or up to 10 task identifiers. When no single preset fits, switch to Custom and combine presets or set each area’s level.

Copy and store the secret

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

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({
  accessToken: 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_sk_…"
TRIGGER_API_URL="https://trigger.example.com"

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

Access presets

Access presets define what a key can do. Every preset is available on every plan.

Preset	Access
Trigger only	Trigger runs and batches for all or selected tasks, and upload large payloads. Trigger responses include scoped public access tokens for the runs and batches they create
Task operator	Trigger all or selected tasks, upload large payloads, and inspect or operate on their runs
Observer	Read runs, tasks, batches, logs, traces, queues, errors, webhooks, sessions, and prompts
Operator	Observe and operate on runs, queues, errors, webhooks, sessions, and waitpoints, close sessions, send to and wait on input streams, read tagged runs and prompts, upload large payloads, and trigger tasks
Webhooks only	Read and write webhooks. Replaying deliveries that trigger tasks and creating webhook waiters require task or waitpoint scopes
Waitpoints only	Create, read, and complete waitpoint tokens, and create and cancel webhook waiters. No task or run access
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, 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. When no single preset fits, such as a CI key that operates on runs and also deploys, build the key’s access with custom access. Your organization can also save custom access as its own preset.

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

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.

Restrict a key to IP addresses

Give a key a list of allowed IP addresses to limit where it can be used. Requests using the key from any other address are rejected, so a leaked key is useless outside your network. They get the same Invalid API key error as a key that doesn’t exist, so the response never confirms the key is real. If a working key suddenly returns that error, check its allowed IP addresses.

Enter one IPv4 or IPv6 address or CIDR range per line, for example 203.0.113.9 or 203.0.113.0/24. A key can have up to 50 ranges.
Leave the list empty to allow any IP address.
Private and reserved ranges, such as 10.0.0.0/8 or 192.168.0.0/16, are not accepted. Use the public addresses your requests come from.
Set the list when you create the key, or change it later with Edit allowed IPs in the key’s menu. Changes take effect immediately.
The API keys page shows the IP address each key was last used from, so you can check it before saving a list.
Public Access Tokens created with the key are not IP-restricted, since they are meant for browsers. Creating one still requires an allowed IP address.

To lock down an environment, give each backend its own IP-restricted key, move your applications to those keys, then hide the root key. Your tasks keep working because they don’t authenticate with your API keys.

Change a key’s access

To change what an existing key can do, click the key on the API keys page to open its details, then click Edit access. The key’s menu has the same option. Pick another preset or switch to Custom, then click Save access. The dialog lists what the key gains and loses before you confirm. The key’s secret doesn’t change, so nothing needs redeploying, and the new access applies to the key’s next request. Name, expiry and allowed IP addresses stay as they are. Editing access needs permission to manage API keys in that environment. The root key and revoked or expired keys can’t be edited. To remove access a key never uses, click Narrow to what it used in the key’s details. See See what a key uses.

When a key’s access differs from its preset

A key keeps the access it was created with. If a preset later grants more or less, keys created before the change don’t follow it. When a preset now grants more than a key has, the API keys page marks the key with a dot after the preset name in the Access column. Click the key to see which areas the preset now grants, then click Update to current preset and Save access to update the key.

Expire and revoke keys

Set an expiration date when creating a key if the integration only needs temporary access. A key with a custom date works until the end of that day in UTC. 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.

Create public access tokens

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

Revoking or expiring an API key does not revoke tokens it already created. Those tokens remain valid until their own expiration.

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, custom access, saved presets and key usage are available in Trigger.dev Cloud. IP allowlists use the last address in the X-Forwarded-For header, so run the webapp behind a reverse proxy that appends the client IP to that header. To allow private ranges because your clients reach the instance over a private network, set API_KEY_ALLOW_PRIVATE_IP_RANGES=1. 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.

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.
Restrict keys used from servers with fixed IP addresses to those addresses.
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

Webhooks

Configuration

Deployment

Private networking

Realtime

CLI

Observability

Using the Dashboard

Troubleshooting

Self-hosting

Open source

Help

Create an API key

Open the API keys page

Create the key

Choose its access

Copy and store the secret

Configure the SDK

Access presets

Deploy with an API key

Restrict a key to IP addresses

Change a key’s access

When a key’s access differs from its preset

Expire and revoke keys

Create public access tokens

Target Preview and Development branches

Self-hosting

Security recommendations

Next steps

Trigger tasks

Realtime authentication

​Create an API key

Open the API keys page

Create the key

Choose its access

Copy and store the secret

​Configure the SDK

​Access presets

​Deploy with an API key

​Restrict a key to IP addresses

​Change a key’s access

​When a key’s access differs from its preset

​Expire and revoke keys

​Create public access tokens

​Target Preview and Development branches

​Self-hosting

​Security recommendations

​Next steps

Trigger tasks

Realtime authentication

Create an API key

Configure the SDK

Access presets

Deploy with an API key

Restrict a key to IP addresses

Change a key’s access

When a key’s access differs from its preset

Expire and revoke keys

Create public access tokens

Target Preview and Development branches

Self-hosting

Security recommendations

Next steps