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

You can use our [React hooks](/frontend/react-hooks) in your frontend application to interact with the Trigger.dev API. This guide will show you how to generate Public Access Tokens that can be used to authenticate your requests.

## Authentication

To create a Public Access Token, you can use the `auth.createPublicToken` function in your **backend** code:

```tsx
const publicToken = await auth.createPublicToken(); // 👈 this public access token has no permissions, so is pretty useless!
```

### Scopes

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

```ts
const publicToken = await auth.createPublicToken({
  scopes: {
    read: {
      runs: true, // ❌ this token can read all runs, possibly useful for debugging/testing
    },
  },
});
```

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"], // ✅ this token can read only these runs
    },
  },
});
```

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"], // 👈 this token can read all runs of these tasks
    },
  },
});
```

Or tags:

```ts
const publicToken = await auth.createPublicToken({
  scopes: {
    read: {
      tags: ["my-tag-1", "my-tag-2"], // 👈 this token can read all runs with these tags
    },
  },
});
```

Or a specific batch of runs:

```ts
const publicToken = await auth.createPublicToken({
  scopes: {
    read: {
      batch: "batch_1234", // 👈 this token can read all runs in this batch
    },
  },
});
```

You can also combine scopes. For example, to read runs with specific tags and for specific tasks:

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

### Write scopes

You can also specify write scopes, which is required for triggering tasks from your frontend application:

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

This will allow the token to trigger the specified tasks. `tasks` is the only write scope available at the moment.

We **strongly** recommend creating short-lived tokens for write scopes, as they can be used to trigger tasks from your frontend application:

```ts
const publicToken = await auth.createPublicToken({
  scopes: {
    write: {
      tasks: ["my-task-1"], // ✅ this token can trigger this task
    },
  },
  expirationTime: "1m", // ✅ this token will expire after 1 minute
});
```

### 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. 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);
```

## Usage

To learn how to use these Public Access Tokens, see our [React hooks](/frontend/react-hooks) guide.