---
title: Overview & Authentication
sidebarTitle: Overview & Auth
description: Using the Trigger.dev SDK from your frontend application.
---

You can use certain SDK functions in your frontend application to interact with the Trigger.dev API. This guide will show you how to authenticate your requests and use the SDK in your frontend application.

## Authentication

You must authenticate your requests using a "Public Access Token" when using the SDK in your frontend application. To create a Public Access Token, you can use the `auth.createPublicToken` function in your backend code:

```tsx
const publicToken = await auth.createPublicToken();
```

To use a Public Access Token in your frontend application, you can call the `auth.configure` function or the `auth.withAuth` function:

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

auth.configure({
  accessToken: publicToken,
});

// or
await auth.withAuth({ accessToken: publicToken }, async () => {
  // Your code here will use the public token
});
```

### Scopes

By default a Public Access Token has limited permissions. You can specify the scopes you need when creating a Public Access Token:

```ts
const publicToken = await auth.createPublicToken({
  scopes: {
    read: {
      runs: true,
    },
  },
});
```

This will allow the token to read all runs, which is probably not what you want. You can specify only certain runs by passing an array of run IDs:

```ts
const publicToken = await auth.createPublicToken({
  scopes: {
    read: {
      runs: ["run_1234", "run_5678"],
    },
  },
});
```

You can scope the token to only read certain tasks:

```ts
const publicToken = await auth.createPublicToken({
  scopes: {
    read: {
      tasks: ["my-task-1", "my-task-2"],
    },
  },
});
```

Or tags:

```ts
const publicToken = await auth.createPublicToken({
  scopes: {
    read: {
      tags: ["my-tag-1", "my-tag-2"],
    },
  },
});
```

Or a specific batch of runs:

```ts
const publicToken = await auth.createPublicToken({
  scopes: {
    read: {
      batch: "batch_1234",
    },
  },
});
```

You can also combine scopes. For example, to read only certain tasks and tags:

```ts
const publicToken = await auth.createPublicToken({
  scopes: {
    read: {
      tasks: ["my-task-1", "my-task-2"],
      tags: ["my-tag-1", "my-tag-2"],
    },
  },
});
```

### Expiration

By default, Public Access Token's expire after 15 minutes. You can specify a different expiration time when creating a Public Access Token:

```ts
const publicToken = await auth.createPublicToken({
  expirationTime: "1hr",
});
```

- If `expirationTime` is a string, it will be treated as a time span
- If `expirationTime` is a number, it will be treated as a Unix timestamp
- If `expirationTime` is a `Date`, it will be treated as a date

The format used for a time span is the same as the [jose package](https://github.com/panva/jose), which is a number followed by a unit. Valid units are: "sec", "secs", "second", "seconds", "s", "minute", "minutes", "min", "mins", "m", "hour", "hours", "hr", "hrs", "h", "day", "days", "d", "week", "weeks", "w", "year", "years", "yr", "yrs", and "y". It is not possible to specify months. 365.25 days is used as an alias for a year. If the string is suffixed with "ago", or prefixed with a "-", the resulting time span gets subtracted from the current unix timestamp. A "from now" suffix can also be used for readability when adding to the current unix timestamp.

## Auto-generated tokens

When triggering a task from your backend, the `handle` received from the `trigger` function now includes a `publicAccessToken` field. This token can be used to authenticate requests in your frontend application:

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

const handle = await tasks.trigger("my-task", { some: "data" });

console.log(handle.publicAccessToken);
```

By default, tokens returned from the `trigger` function expire after 15 minutes and have a read scope for that specific run, and any tags associated with it. You can customize the expiration of the auto-generated tokens by passing a `publicTokenOptions` object to the `trigger` function:

```ts
const handle = await tasks.trigger(
  "my-task",
  { some: "data" },
  {
    tags: ["my-tag"],
  },
  {
    publicAccessToken: {
      expirationTime: "1hr",
    },
  }
);
```

You will also get back a Public Access Token when using the `batchTrigger` function:

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

const handle = await tasks.batchTrigger("my-task", [
  { payload: { some: "data" } },
  { payload: { some: "data" } },
  { payload: { some: "data" } },
]);

console.log(handle.publicAccessToken);
```

## Available SDK functions

Currently the following functions are available in the frontend SDK:

### runs.retrieve

The `runs.retrieve` function allows you to retrieve a run by its ID.

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

// Somewhere in your backend code
const handle = await tasks.trigger("my-task", { some: "data" });

// In your frontend code
auth.configure({
  accessToken: handle.publicAccessToken,
});

const run = await runs.retrieve(handle.id);
```

Learn more about the `runs.retrieve` function in the [runs.retrieve doc](/management/runs/retrieve).

### runs.subscribeToRun

The `runs.subscribeToRun` function allows you to subscribe to a run by its ID, and receive updates in real-time when the run changes.

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

// Somewhere in your backend code
const handle = await tasks.trigger("my-task", { some: "data" });

// In your frontend code
auth.configure({
  accessToken: handle.publicAccessToken,
});

for await (const run of runs.subscribeToRun(handle.id)) {
  // This will log the run every time it changes
  console.log(run);
}
```

See the [Realtime doc](/realtime) for more information.

### runs.subscribeToRunsWithTag

The `runs.subscribeToRunsWithTag` function allows you to subscribe to runs with a specific tag, and receive updates in real-time when the runs change.

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

// Somewhere in your backend code
const handle = await tasks.trigger("my-task", { some: "data" }, { tags: ["my-tag"] });

// In your frontend code
auth.configure({
  accessToken: handle.publicAccessToken,
});

for await (const run of runs.subscribeToRunsWithTag("my-tag")) {
  // This will log the run every time it changes
  console.log(run);
}
```

See the [Realtime doc](/realtime) for more information.

## React hooks

We also provide React hooks to make it easier to use the SDK in your React application. See our [React hooks](/frontend/react-hooks) documentation for more information.

## Triggering tasks

We don't currently support triggering tasks from the frontend SDK. If this is something you need, please let us know by [upvoting the feature](https://feedback.trigger.dev/p/ability-to-trigger-tasks-from-frontend).
