Skip to main content
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: 
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: 
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: 
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"],
    },
  },
});

​
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);

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

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