> ## Documentation Index
> Fetch the complete documentation index at: https://trigger.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# API keys

> Authenticate backend requests with environment-specific 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.

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

> [!TIP]
>
> To access AWS or another external service from a deployed task without stored cloud keys, use
> [workload identity](https://trigger.dev/docs/oidc.md). 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.

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

### 1. Open the API keys page

Select the project and environment the integration needs to access, then open [**API keys**](https://cloud.trigger.dev/_/apikeys).

### 2. Create the key

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

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

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

```bash .env theme={"theme":"css-variables"}
TRIGGER_SECRET_KEY="tr_prod_sk_…"
```

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

```ts Your backend code theme={"theme":"css-variables"}
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`:

```bash .env theme={"theme":"css-variables"}
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. On the Free and Hobby plans only the **No restrictions** preset is available. All other presets require the Pro or Enterprise plan.

| 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, queues, errors, and webhooks |
| **Operator** | Observe and operate on runs, queues, errors, and webhooks, and trigger tasks |
| **Webhooks only** | Read and write [webhooks](https://trigger.dev/docs/webhooks/overview.md). Replaying deliveries that trigger tasks and creating webhook waiters require task or waitpoint scopes |
| **Waitpoints only** | Create, list, and retrieve [waitpoint tokens](https://trigger.dev/docs/wait-for-token.md). 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.

## Deploy with an API key

Set a key in `TRIGGER_ACCESS_TOKEN` to authenticate `trigger deploy` without logging in.

```bash npm theme={"theme":"css-variables"}
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.

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

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

## Create public access tokens

API keys can be used to create scoped [Public Access Tokens](https://trigger.dev/docs/realtime/auth.md) 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).

> [!NOTE]
>
> 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:

```bash .env theme={"theme":"css-variables"}
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. 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.
* 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](https://trigger.dev/docs/realtime/auth.md) for client-side access.

## Next steps

> [card] [Trigger tasks](https://trigger.dev/docs/triggering.md)
>
> Trigger tasks from your backend with an environment API key.

> [card] [Realtime authentication](https://trigger.dev/docs/realtime/auth.md)
>
> Create scoped public tokens for frontend and realtime access.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.