Overview & Authentication

Using the Trigger.dev SDK from your frontend application.

You can use our 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:

const publicToken = await auth.createPublicToken();

Scopes

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

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:

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

You can scope the token to only read certain tasks:

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

Or tags:

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

Or a specific batch of runs:

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

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

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:

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.

Expiration

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

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, 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:

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:

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:

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