---
title: Overview & Authentication
sidebarTitle: Overview & Authentication
description: Using the Trigger.dev v3 management API
---

## Installation

The management API is available through the same `@trigger.dev/sdk` package used in defining and triggering tasks. If you have already installed the package in your project, you can skip this step.

<CodeGroup>

```bash npm
npm i @trigger.dev/sdk@latest
```

```bash pnpm
pnpm add @trigger.dev/sdk@latest
```

```bash yarn
yarn add @trigger.dev/sdk@latest
```

</CodeGroup>

## Usage

All `v3` functionality is provided through the `@trigger.dev/sdk/v3` module. You can import the entire module or individual resources as needed.

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

configure({
  // this is the default and if the `TRIGGER_SECRET_KEY` environment variable is set, can omit calling configure
  secretKey: process.env["TRIGGER_SECRET_KEY"],
});

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

main().catch(console.error);
```

## Authentication

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 [Frontend guide](/frontend/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
import { configure, runs } from "@trigger.dev/sdk/v3";

// 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
import { configure, envvars } from "@trigger.dev/sdk/v3";

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,
});
```

## Handling errors

When the SDK method is unable to connect to the API server, or the API server returns a non-successful response, the SDK will throw an `ApiError` that you can catch and handle:

```ts
import { runs, APIError } from "@trigger.dev/sdk/v3";

async function main() {
  try {
    const run = await runs.retrieve("run_1234");
  } catch (error) {
    if (error instanceof ApiError) {
      console.error(`API error: ${error.status}, ${error.headers}, ${error.body}`);
    } else {
      console.error(`Unknown error: ${error.message}`);
    }
  }
}
```

## Retries

The SDK will automatically retry requests that fail due to network errors or server errors. By default, the SDK will retry requests up to 3 times, with an exponential backoff delay between retries.

You can customize the retry behavior by passing a `requestOptions` option to the `configure` function:

```ts
import { configure } from "@trigger.dev/sdk/v3";

configure({
  requestOptions: {
    retry: {
      maxAttempts: 5,
      minTimeoutInMs: 1000,
      maxTimeoutInMs: 5000,
      factor: 1.8,
      randomize: true,
    },
  },
});
```

All SDK functions also take a `requestOptions` parameter as the last argument, which can be used to customize the request options. You can use this to disable retries for a specific request:

```ts
import { runs } from "@trigger.dev/sdk/v3";

async function main() {
  const run = await runs.retrieve("run_1234", {
    retry: {
      maxAttempts: 1, // Disable retries
    },
  });
}
```

<Note>
  When running inside a task, the SDK ignores customized retry options for certain functions (e.g.,
  `task.trigger`, `task.batchTrigger`), and uses retry settings optimized for task execution.
</Note>

## Auto-pagination

All list endpoints in the management API support auto-pagination.
You can use `for await … of` syntax to iterate through items across all pages:

```ts
import { runs } from "@trigger.dev/sdk/v3";

async function fetchAllRuns() {
  const allRuns = [];

  for await (const run of runs.list({ limit: 10 })) {
    allRuns.push(run);
  }

  return allRuns;
}
```

You can also use helpers on the return value from any `list` method to get the next/previous page of results:

```ts
import { runs } from "@trigger.dev/sdk/v3";

async function main() {
  let page = await runs.list({ limit: 10 });

  for (const run of page.data) {
    console.log(run);
  }

  while (page.hasNextPage()) {
    page = await page.getNextPage();
    // ... do something with the next page
  }
}
```

## Advanced usage

### Accessing raw HTTP responses

All API methods return a `Promise` subclass `ApiPromise` that includes helpers for accessing the underlying HTTP response:

```ts
import { runs } from "@trigger.dev/sdk/v3";

async function main() {
  const { data: run, response: raw } = await runs.retrieve("run_1234").withResponse();

  console.log(raw.status);
  console.log(raw.headers);

  const response = await runs.retrieve("run_1234").asResponse(); // Returns a Response object

  console.log(response.status);
  console.log(response.headers);
}
```