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(); // 👈 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:

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:

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:

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:

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:

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:

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:

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