Overview & Authentication
Using the Trigger.dev SDK from your frontend application.
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:
To use a Public Access Token in your frontend application, you can call the auth.configure
function or the auth.withAuth
function:
Scopes
By default a Public Access Token has limited permissions. You can specify the scopes you need when creating a Public Access Token:
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:
You can scope the token to only read certain tasks:
Or tags:
Or a specific batch of runs:
You can also combine scopes. For example, to read only certain tasks and tags:
Expiration
By default, Public Access Token’s expire after 15 minutes. You can specify a different expiration time when creating a Public Access Token:
- 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 aDate
, 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:
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:
You will also get back a Public Access Token when using the batchTrigger
function:
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.
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.
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.
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.
Was this page helpful?