Skip to content

Commit 7d9f1a3

Browse files
cardernecarderne
authored
docs: document additional environment API keys (#4406)
1 parent 6e77102 commit 7d9f1a3

2 files changed

Lines changed: 162 additions & 28 deletions

File tree

‎docs/apikeys.mdx‎

Lines changed: 159 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -1,54 +1,186 @@
11
---
22
title: "API keys"
3-
description: "How to authenticate with Trigger.dev so you can trigger tasks."
3+
description: "Authenticate backend requests with environment-specific API keys."
44
---
55

6-
### Authentication and your secret keys
6+
**API keys authenticate backend requests to a specific Trigger.dev project and environment.** Each environment can have multiple keys, with optional scopes and restrictions attached.
77

8-
When you [trigger a task](/triggering) from your backend code, you need to set the `TRIGGER_SECRET_KEY` environment variable.
8+
<Warning>
9+
API keys grant access to your Trigger.dev environment. Store them in a secret manager or backend
10+
environment variable, never commit them to source control, and never expose them in frontend code.
11+
</Warning>
912

10-
Each environment has its own secret key. You can find the value on the API keys page in the Trigger.dev dashboard:
13+
## Find your API keys
1114

12-
![How to find your secret key](/images/api-keys.png)
15+
Open your project in the dashboard, select an environment, and open the [**API keys**](https://cloud.trigger.dev/_/apikeys) page.
16+
17+
API keys belong to one environment. A Development key cannot access Production, and a Production key cannot access Staging.
1318

1419
<Note>
15-
For preview branches, you need to also set the `TRIGGER_PREVIEW_BRANCH` environment variable as
16-
well. You can find the value on the API keys page when you're on the preview branch.
20+
Every team member has their own Development environment and keys. Copy the Development key from
21+
your own API keys page so local requests run against your machine.
1722
</Note>
1823

19-
### Automatically Configuring the SDK
24+
## Configure the SDK
2025

21-
To automatically configure the SDK with your secret key, you can set the `TRIGGER_SECRET_KEY` environment variable. The SDK will automatically use this value when calling API methods (like `trigger`).
26+
Set `TRIGGER_SECRET_KEY` in your backend environment. The SDK reads it automatically for operations such as triggering tasks and retrieving runs.
2227

2328
```bash .env
24-
TRIGGER_SECRET_KEY="tr_dev_…"
25-
TRIGGER_PREVIEW_BRANCH="my-branch" # Only needed for preview branches
29+
TRIGGER_SECRET_KEY="tr_prod_sk_…"
30+
```
31+
32+
To configure the SDK in code, pass the key to `configure`:
33+
34+
```ts Your backend code
35+
import { configure, tasks } from "@trigger.dev/sdk";
36+
import type { sendEmail } from "./trigger/send-email";
37+
38+
configure({
39+
secretKey: process.env.TRIGGER_SECRET_KEY,
40+
previewBranch: "my-branch", // Only needed for preview branches
41+
baseURL: "https://mytrigger.example.com", // Optional
42+
});
43+
44+
await tasks.trigger<typeof sendEmail>("send-email", {
45+
to: "user@example.com",
46+
});
2647
```
2748

28-
You can do the same if you are self-hosting and need to change the default URL by using `TRIGGER_API_URL`.
49+
If you self-host Trigger.dev, set `TRIGGER_API_URL` or pass `baseURL` to `configure`:
2950

3051
```bash .env
52+
TRIGGER_SECRET_KEY="tr_prod_…"
3153
TRIGGER_API_URL="https://trigger.example.com"
32-
TRIGGER_PREVIEW_BRANCH="my-branch" # Only needed for preview branches
3354
```
3455

35-
The default URL is `https://api.trigger.dev`.
56+
The default API URL is `https://api.trigger.dev`.
57+
58+
## Create a key
3659

37-
### Manually Configuring the SDK
60+
Create a separate key for each service or integration that accesses Trigger.dev.
3861

39-
If you prefer to manually configure the SDK, you can call the `configure` method:
62+
<Note>
63+
Creating and revoking keys requires permission to manage API keys for the selected environment.
64+
The dashboard disables these actions when your role does not have permission.
65+
</Note>
4066

41-
```ts
42-
import { configure } from "@trigger.dev/sdk";
43-
import { myTask } from "./trigger/myTasks";
67+
<Steps titleSize="h3">
68+
<Step title="Open the API keys page">
69+
Select the project and environment the integration needs to access, then open [**API keys**](https://cloud.trigger.dev/_/apikeys).
70+
</Step>
71+
<Step title="Create the key">
72+
Click **New API key**, enter a descriptive name, and optionally set an expiration date. Names can
73+
contain up to 64 characters.
74+
</Step>
75+
<Step title="Choose its access">
76+
Select an access preset. For task-aware presets, choose all tasks or up to 10 task identifiers.
77+
</Step>
78+
<Step title="Copy and store the secret">
79+
Copy the key into your secret manager or backend environment. Trigger.dev shows the complete
80+
value only once.
81+
</Step>
82+
</Steps>
83+
84+
## Access presets
85+
86+
Access presets define what a key can do. Some presets require a paid plan. The dashboard shows which presets your organization can use — see [pricing](https://trigger.dev/pricing).
87+
88+
| Preset | Access |
89+
| --- | --- |
90+
| **Trigger only** | Trigger runs and batches for all or selected tasks. Trigger responses include scoped public access tokens for the runs and batches they create |
91+
| **Task operator** | Trigger all or selected tasks and inspect or operate on their runs |
92+
| **Observer** | Read runs, tasks, batches, logs, traces, and queues |
93+
| **Operator** | Observe and operate on runs and queues, and trigger tasks |
94+
| **Deploy only** | Deploy versions, sync environment variables, and manage Preview branches |
95+
| **Variables only** | Read and write environment variables in this environment |
96+
| **No restrictions** | Full access to the environment |
97+
98+
**Trigger only** and **Task operator** can be restricted to selected tasks. Task restrictions use task identifiers, such as `send-email`. A request involving multiple tasks — such as a batch trigger — succeeds only when the key can access every task in the request, so a task-restricted key can batch-trigger only its selected tasks.
99+
100+
## Deploy with an API key
101+
102+
Set a key in `TRIGGER_ACCESS_TOKEN` to authenticate `trigger deploy` without logging in.
103+
104+
<CodeGroup>
105+
106+
```bash npm
107+
TRIGGER_ACCESS_TOKEN="tr_prod_sk_…" npx trigger.dev@latest deploy
108+
```
109+
</CodeGroup>
44110

45-
configure({
46-
secretKey: "tr_dev_1234", // WARNING: Never actually hardcode your secret key like this
47-
previewBranch: "my-branch", // Only needed for preview branches
48-
baseURL: "https://mytrigger.example.com", // Optional
49-
});
111+
The key must belong to the target environment. Use a Production key for the default deployment, a Staging key with `--env staging`, or a key from the Preview environment with `--env preview`. A Preview deployment key can create and archive Preview branches and sync their environment variables.
112+
113+
<Note>
114+
The deploy CLI reads environment API keys from `TRIGGER_ACCESS_TOKEN`, not
115+
`TRIGGER_SECRET_KEY`. Setting an API key in `TRIGGER_ACCESS_TOKEN` takes precedence over a saved
116+
CLI login.
117+
</Note>
118+
119+
## Expire and revoke keys
120+
121+
Set an expiration date when creating a key if the integration only needs temporary access. An expired key stops authenticating automatically.
50122

51-
async function triggerTask() {
52-
await myTask.trigger({ userId: "1234" }); // This will use the secret key and base URL you configured
53-
}
123+
Revoking a key takes effect immediately and cannot be reversed. Requests using the key fail, and the key can no longer create public access tokens. Create a replacement before revoking a key when you need to rotate it without interrupting the integration.
124+
125+
Removing a team member does not revoke keys they created. Review and revoke their keys separately when their access changes.
126+
127+
## Root keys
128+
129+
<Warning>
130+
Root keys are legacy, and are likely to be deprecated in the future. We recommend against using them.
131+
</Warning>
132+
133+
Each environment has a single legacy root key. It can be regenerated, which creates a new value immediately. The previous root key remains valid for 24 hours so you can update services without downtime, then stops authenticating.
134+
135+
Public access tokens signed with the previous root key remain valid until the earlier of their own expiration and the end of the 24-hour grace period.
136+
137+
## Create public access tokens
138+
139+
API keys can be used to create scoped [Public Access Tokens](/realtime/auth) using `auth.createPublicToken()`.
140+
141+
To do so with the newer non-root keys, you must use `@trigger.dev/sdk` version 4.5.8 or later. Creating public tokens with non-root keys has the following restrictions:
142+
143+
- The token must request at least one scope.
144+
- Its scopes cannot exceed the key's access.
145+
- Its expiration cannot exceed 30 days.
146+
147+
<Note>
148+
Revoking or expiring an API key does not revoke tokens it already created. Those tokens remain valid until their own expiration, unless the environment's root key is regenerated.
149+
</Note>
150+
151+
## Target Preview and Development branches
152+
153+
Preview and named Development branches use their parent environment's keys. Select the branch by setting `TRIGGER_PREVIEW_BRANCH` alongside the environment key:
154+
155+
```bash .env
156+
TRIGGER_SECRET_KEY="tr_preview_sk_…"
157+
TRIGGER_PREVIEW_BRANCH="feature/new-checkout"
54158
```
159+
160+
The SDK sends the branch automatically. When calling the API directly, send the same value in the `x-trigger-branch` header.
161+
162+
## Self-hosting
163+
164+
Self-hosted installations support multiple keys with **No restrictions**. The restricted access presets are available in Trigger.dev Cloud.
165+
166+
Keep your instance and SDK current before creating keys. Calling a public-token API with a key on a server that does not support server-minted tokens returns an upgrade error; use the root key until the server is upgraded.
167+
168+
## Security recommendations
169+
170+
- Create one key per service or integration instead of sharing keys.
171+
- Choose the narrowest access preset and task selection that supports the integration.
172+
- Store keys in a secret manager and inject them as backend environment variables.
173+
- Set expiration dates for temporary integrations and deployment credentials.
174+
- Revoke keys when an integration or team member no longer needs access.
175+
- Never put an API key in frontend code. Use scoped [Public Access Tokens](/realtime/auth) for client-side access.
176+
177+
## Next steps
178+
179+
<CardGroup cols={2}>
180+
<Card title="Trigger tasks" icon="bolt" href="/triggering">
181+
Trigger tasks from your backend with an environment API key.
182+
</Card>
183+
<Card title="Realtime authentication" icon="key" href="/realtime/auth">
184+
Create scoped public tokens for frontend and realtime access.
185+
</Card>
186+
</CardGroup>

‎docs/realtime/auth.mdx‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -128,9 +128,11 @@ const publicToken = await auth.createPublicToken({
128128
```
129129

130130
- If `expirationTime` is a string, it will be treated as a time span
131-
- If `expirationTime` is a number, it will be treated as a Unix timestamp
131+
- If `expirationTime` is a number, it will be treated as a Unix timestamp in **seconds**
132132
- If `expirationTime` is a `Date`, it will be treated as a date
133133

134+
When using non-root API keys (recommended), the expiration cannot be more than 30 days in the future.
135+
134136
The format used for a time span is the same as the [jose package](https://github.com/panva/jose), 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.
135137

136138
### Auto-generated tokens

0 commit comments

Comments
 (0)