Authentication

There are two ways to authenticate with the management API:

Secret key (tr_dev_… / tr_prod_…) — scoped to a single environment in a project.
Personal Access Token (PAT) (tr_pat_…) — tied to a user account and can access all orgs, projects, and environments that user has permission to.

Both methods should only be used in backend server code. They provide full access to the project. See the Realtime guide for frontend authentication.

Secret key

Secret key authentication scopes API access to a specific environment. Obtain a secret key from your project’s API Keys page in the Trigger.dev dashboard.

import { configure, runs } from "@trigger.dev/sdk";

configure({
  secretKey: process.env["TRIGGER_SECRET_KEY"], // starts with tr_dev_ or tr_prod_
});

const page = await runs.list({ limit: 10, status: ["COMPLETED"] });

Send the key as a Bearer token in the Authorization header for direct HTTP requests:

curl https://api.trigger.dev/api/v1/runs \
  -H "Authorization: Bearer tr_dev_1234..."

Personal Access Token (PAT)

A PAT grants access to all the orgs, projects, and environments the user has permission to. Because a PAT does not scope access to a specific environment, you must provide the projectRef (and sometimes the environment) for calls that require it.

import { configure, runs } from "@trigger.dev/sdk";

configure({
  secretKey: process.env["TRIGGER_ACCESS_TOKEN"], // starts with tr_pat_
});

// projectRef is required when using a PAT
const page = await runs.list("proj_1234", {
  limit: 10,
  status: ["COMPLETED"],
});

Endpoint support matrix

View which endpoints support each authentication method

Endpoint	Secret key	Personal Access Token
`tasks.trigger`	✅
`tasks.batchTrigger`	✅
`runs.list`	✅	✅
`runs.retrieve`	✅
`runs.cancel`	✅
`runs.replay`	✅
`envvars.list`	✅	✅
`envvars.retrieve`	✅	✅
`envvars.upload`	✅	✅
`envvars.create`	✅	✅
`envvars.update`	✅	✅
`envvars.del`	✅	✅
`schedules.list`	✅
`schedules.create`	✅
`schedules.retrieve`	✅
`schedules.update`	✅
`schedules.activate`	✅
`schedules.deactivate`	✅
`schedules.del`	✅

Preview branch targeting

When working with preview branches you can target a specific branch by including the x-trigger-branch header (HTTP) or the previewBranch option (SDK).

SDK
cURL

import { configure, envvars } from "@trigger.dev/sdk";

configure({
  secretKey: process.env["TRIGGER_ACCESS_TOKEN"], // tr_pat_…
  previewBranch: "feature-xyz",
});

await envvars.update("proj_1234", "preview", "DATABASE_URL", {
  value: "postgres://...",
});

curl --request PUT \
  --url https://api.trigger.dev/api/v1/projects/{projectRef}/envvars/preview/DATABASE_URL \
  --header 'Authorization: Bearer <token>' \
  --header 'x-trigger-branch: feature-xyz' \
  --header 'Content-Type: application/json' \
  --data '{"value": "postgres://..."}'

The x-trigger-branch header only applies to the preview environment. It has no effect on dev, staging, or prod.

Overview

Tasks & Runs

Schedules & Queues

Waitpoints & Env Vars

Secret key

Personal Access Token (PAT)

Endpoint support matrix

Preview branch targeting

​Secret key

​Personal Access Token (PAT)

​Endpoint support matrix

​Preview branch targeting

Secret key

Personal Access Token (PAT)

Endpoint support matrix

Preview branch targeting