Skip to main content
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

EndpointSecret keyPersonal 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). 
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://...",
});
The x-trigger-branch header only applies to the preview environment. It has no effect on dev, staging, or prod.

Build docs developers (and LLMs) love

Get started for freeTalk to us