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

# Authentication

> Authenticating with the Trigger.dev management API

There are two methods of authenticating with the management API: using a secret key associated with a specific environment in a project (`secretKey`), or using a personal access token (`personalAccessToken`). Both methods should only be used in a backend server, as they provide full access to the project.

<Note>
  There is a separate authentication strategy when making requests from your frontend application.
  See the [Realtime guide](/realtime/overview) for more information. This guide is for backend usage
  only.
</Note>

Certain API functions work with both authentication methods, but require different arguments depending on the method used. For example, the `runs.list` function can be called using either a `secretKey` or a `personalAccessToken`, but the `projectRef` argument is required when using a `personalAccessToken`:

```ts theme={"theme":"css-variables"}
import { configure, runs } from "@trigger.dev/sdk";

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

function secretKeyExample() {
  return runs.list({
    limit: 10,
    status: ["COMPLETED"],
  });
}

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

function personalAccessTokenExample() {
  // Notice the projectRef argument is required when using a personalAccessToken
  return runs.list("prof_1234", {
    limit: 10,
    status: ["COMPLETED"],
    projectRef: "tr_proj_1234567890",
  });
}
```

<Accordion title="View endpoint support">
  Consult the following table to see which endpoints support each authentication method.

  | Endpoint               | Secret key | Personal Access Token |
  | ---------------------- | ---------- | --------------------- |
  | `task.trigger`         | ✅          |                       |
  | `task.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`        | ✅          |                       |
</Accordion>

### Secret key

Secret key authentication scopes the API access to a specific environment in a project, and works with certain endpoints. You can read our [API Keys guide](/apikeys) for more information.

### Personal Access Token (PAT)

A PAT is a token associated with a specific user, and gives access to all the orgs, projects, and environments that the user has access to. You can identify a PAT by the `tr_pat_` prefix. Because a PAT does not scope access to a specific environment, you must provide the `projectRef` argument when using a PAT (and sometimes the environment as well).

For example, when uploading environment variables using a PAT, you must provide the `projectRef` and `environment` arguments:

```ts theme={"theme":"css-variables"}
import { configure, envvars } from "@trigger.dev/sdk";

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

await envvars.upload("proj_1234", "dev", {
  variables: {
    MY_ENV_VAR: "MY_ENV_VAR_VALUE",
  },
  override: true,
});
```

### Preview branch targeting

When working with preview branches, you may need to target a specific branch when making API calls. This is particularly useful for managing environment variables or other resources that are scoped to individual preview branches.

<Tabs>
  <Tab title="SDK">
    To target a specific preview branch, include the `previewBranch` option in your SDK configuration:

    ```ts theme={"theme":"css-variables"}
    import { configure, envvars } from "@trigger.dev/sdk";

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

    await envvars.update("proj_1234", "preview", "DATABASE_URL", {
      value: "your_preview_database_url",
    });
    ```
  </Tab>

  <Tab title="cURL">
    To target a specific preview branch, include the `x-trigger-branch` header in your API requests with the branch name as the value:

    ```bash theme={"theme":"css-variables"}
    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": "your_preview_database_url"
      }'
    ```
  </Tab>
</Tabs>

This will set the `DATABASE_URL` environment variable specifically for the `feature-xyz` preview branch.

<Note>
  The `x-trigger-branch` header is only relevant when working with the `preview` environment (`{env}
      ` parameter set to `preview`). It has no effect when working with `dev`, `staging`, or `prod`
  environments.
</Note>

#### SDK usage with preview branches

When using the SDK to manage preview branch environment variables, the branch targeting is handled automatically when you're running in a preview environment with the `TRIGGER_PREVIEW_BRANCH` environment variable set. However, you can also specify the branch explicitly:

```ts theme={"theme":"css-variables"}
import { configure, envvars } from "@trigger.dev/sdk";

configure({
  secretKey: process.env["TRIGGER_ACCESS_TOKEN"], // starts with tr_pat_
  previewBranch: "feature-xyz", // Optional: specify the branch
});

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

### Scoped authentication with `auth.withAuth`

`auth.withAuth` runs a callback with a temporary API client configuration, then restores the previous configuration when the callback resolves or rejects. It's useful when a single process needs to make calls across multiple Trigger.dev projects or environments without mutating the global config manually.

```ts theme={"theme":"css-variables"}
import { auth, runs } from "@trigger.dev/sdk";

const projectBRuns = await auth.withAuth(
  { accessToken: process.env.TRIGGER_SECRET_KEY_PROJECT_B },
  async () => {
    return runs.list({ limit: 10 });
  },
);
```

Any SDK call inside the callback uses the overridden token. Calls outside the callback continue to use whatever was set by `configure` (or picked up from `TRIGGER_SECRET_KEY`).

<Warning>
  Avoid `auth.withAuth` as a per-request authentication strategy on long-running servers. Use it
  only for sequential, non-overlapping scopes.
</Warning>

#### How scoping actually works

Despite looking block-scoped, `auth.withAuth` stores the overridden configuration in a process-wide global (not [AsyncLocalStorage](https://nodejs.org/api/async_context.html)). It saves the previous config, installs the new one globally, runs the callback, and restores the previous config in a `finally`. This means sequential, non-overlapping usage is safe, but concurrent usage is not — if two `auth.withAuth` calls overlap (for example inside `Promise.all` with different tokens, or across concurrent request handlers on a long-running server) both will share whichever configuration was installed most recently, and SDK calls in one scope can silently use the other scope's token.

A fix using async context isolation is tracked in [issue #3298](https://github.com/triggerdotdev/trigger.dev/issues/3298).