Realtime authentication

To use the Realtime API, you need to authenticate your requests with Public Access Tokens or Trigger Tokens. These tokens provide secure, scoped access to your runs and can be used in both frontend and backend applications.

Token Types

There are two types of tokens you can use with the Realtime API:

Public Access Tokens - Used to read and subscribe to run data. Can be used in both the frontend and backend.
Trigger Tokens - Used to trigger tasks from your frontend. These are more secure, single-use tokens that can only be used in the frontend.

Public Access Tokens (for subscribing to runs)

Use Public Access Tokens to subscribe to runs and receive real-time updates in your frontend or backend.

Creating Public Access Tokens

You can create a Public Access Token using the auth.createPublicToken function in your backend code:

// Somewhere in your backend code
import { auth } from "@trigger.dev/sdk";

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:

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

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:

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

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:

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

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:

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

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:

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

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:

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

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:

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

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 in seconds
If expirationTime is a Date, it will be treated as a date

When using non-root API keys (recommended), the expiration cannot be more than 30 days in the future. 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.

Refreshing an expired token

A realtime stream subscription can outlive its token. Pass a refreshAccessToken callback and a subscription rejected with a 401/403 re-mints once and reconnects, instead of failing. With no refresher, auth errors stay terminal. Mint the fresh token from your backend, where your secret key lives:

import { useRealtimeStream } from "@trigger.dev/react-hooks";

const { parts } = useRealtimeStream<{ url: string }>(runId, "frames", {
  accessToken,
  refreshAccessToken: async () => {
    const res = await fetch("/api/realtime-token"); // your backend calls auth.createPublicToken
    return (await res.json()).token;
  },
});

refreshAccessToken is available on every realtime hook, and on useApiClient and TriggerAuthContext so hooks under a provider share one refresher.

Auto-generated tokens

When you trigger tasks from your backend, the handle received includes a publicAccessToken field. This token can be used to authenticate real-time requests in your frontend application. By default, auto-generated tokens expire after 15 minutes and have a read scope for the specific run(s) that were triggered. You can customize the expiration by passing a publicTokenOptions object to the trigger function. See our triggering documentation for detailed examples of how to trigger tasks and get auto-generated tokens.

Where should I create tokens? The standard pattern is to create tokens in your backend code (API route, server action) after triggering a task, then pass the token to your frontend. The handle.publicAccessToken returned by tasks.trigger() already does this for you. You rarely need to create tokens inside a task itself.

Subscribing to runs with Public Access Tokens

Once you have a Public Access Token, you can use it to authenticate requests to the Realtime API in both backend and frontend applications. Backend usage: See our backend documentation for examples of what you can do with Realtime in your backend once you have authenticated with a token. Frontend usage: See our React hooks documentation for examples of using tokens with frontend components.

Trigger Tokens (for frontend triggering only)

For triggering tasks from your frontend, you need special “trigger” tokens. These tokens can only be used once to trigger a task and are more secure than regular Public Access Tokens.

Creating Trigger Tokens

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

// Somewhere in your backend code
const triggerToken = await auth.createTriggerPublicToken("my-task");

Multiple tasks

You can pass multiple tasks to create a token that can trigger multiple tasks:

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

// Somewhere in your backend code
const triggerToken = await auth.createTriggerPublicToken(["my-task-1", "my-task-2"]);

Multiple use

You can also create tokens that can be used multiple times:

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

// Somewhere in your backend code
const triggerToken = await auth.createTriggerPublicToken("my-task", {
  multipleUse: true, // ❌ Use this with caution!
});

Expiration

These tokens also expire, with the default expiration time being 15 minutes. You can specify a custom expiration time:

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

// Somewhere in your backend code
const triggerToken = await auth.createTriggerPublicToken("my-task", {
  expirationTime: "24hr",
});

Triggering tasks from the frontend with Trigger Tokens

Check out our React hooks documentation for examples of how to use Trigger Tokens in your frontend applications.

Getting started

Fundamentals

Building with AI

Writing tasks

Agents

Configuration

Deployment

Private networking

Realtime

CLI

Observability

Using the Dashboard

Troubleshooting

Self-hosting

Open source

Help

Realtime authentication

Token Types

Public Access Tokens (for subscribing to runs)

Creating Public Access Tokens

Scopes

Expiration

Refreshing an expired token

Auto-generated tokens

Subscribing to runs with Public Access Tokens

Trigger Tokens (for frontend triggering only)

Creating Trigger Tokens

Multiple tasks

Multiple use

Expiration

Triggering tasks from the frontend with Trigger Tokens

​Token Types

​Public Access Tokens (for subscribing to runs)

​Creating Public Access Tokens

​Scopes

​Expiration

​Refreshing an expired token

​Auto-generated tokens

​Subscribing to runs with Public Access Tokens

​Trigger Tokens (for frontend triggering only)

​Creating Trigger Tokens

​Multiple tasks

​Multiple use

​Expiration

​Triggering tasks from the frontend with Trigger Tokens

Token Types

Public Access Tokens (for subscribing to runs)

Creating Public Access Tokens

Scopes

Expiration

Refreshing an expired token

Auto-generated tokens

Subscribing to runs with Public Access Tokens

Trigger Tokens (for frontend triggering only)

Creating Trigger Tokens

Multiple tasks

Multiple use

Expiration

Triggering tasks from the frontend with Trigger Tokens