Skip to content

Commit 11216bf

Browse files
cardernecarderne
committed
docs: document additional environment API keys
1 parent 44eca4d commit 11216bf

1 file changed

Lines changed: 161 additions & 27 deletions

File tree

‎docs/apikeys.mdx‎

Lines changed: 161 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -1,54 +1,188 @@
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 and restrict additional keys to the access each integration needs."
44
---
55

6-
### Authentication and your secret keys
6+
**API keys authenticate backend requests to a specific Trigger.dev project and environment.** Each environment has a root key, and you can create additional named keys for separate services and integrations.
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+
## Root and additional keys
1114

12-
![How to find your secret key](/images/api-keys.png)
15+
Each environment has two types of API key:
16+
17+
| Key type | Access | Secret visibility | Lifecycle |
18+
| --- | --- | --- | --- |
19+
| **Root key** | Full access to the environment | Available to copy from the dashboard | Regenerate it with a 24-hour grace period for the previous value |
20+
| **Additional key** | Full or restricted access | Shown once when created, then stored as a hash and displayed only by its suffix | Set an optional expiration date or revoke it immediately |
21+
22+
Root keys use prefixes such as `tr_dev_`, `tr_stg_`, `tr_prod_`, and `tr_preview_`. Additional keys include `_sk_` after the environment, for example `tr_prod_sk_…`.
23+
24+
Use additional keys to give each backend service, deployment pipeline, or external integration its own credential. This lets you revoke one integration without rotating the environment's root key.
25+
26+
## Find your API keys
27+
28+
Open your project in the dashboard, select an environment, and open the **API keys** page.
29+
30+
API keys belong to one environment. A Development key cannot access Production, and a Production key cannot access Staging.
1331

1432
<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.
33+
Every team member has their own Development environment and keys. Copy the Development key from
34+
your own API keys page so local requests run against your machine.
1735
</Note>
1836

19-
### Automatically Configuring the SDK
37+
## Configure the SDK
2038

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`).
39+
Set `TRIGGER_SECRET_KEY` in your backend environment. The SDK reads it automatically for operations such as triggering tasks and retrieving runs.
2240

2341
```bash .env
24-
TRIGGER_SECRET_KEY="tr_dev_…"
25-
TRIGGER_PREVIEW_BRANCH="my-branch" # Only needed for preview branches
42+
TRIGGER_SECRET_KEY="tr_prod_…"
43+
```
44+
45+
Additional keys use the same environment variable:
46+
47+
```bash .env
48+
TRIGGER_SECRET_KEY="tr_prod_sk_…"
49+
```
50+
51+
To configure the SDK in code, pass the key to `configure`:
52+
53+
```ts Your backend code
54+
import { configure, tasks } from "@trigger.dev/sdk";
55+
56+
configure({
57+
secretKey: process.env.TRIGGER_SECRET_KEY,
58+
});
59+
60+
await tasks.trigger("send-email", {
61+
to: "user@example.com",
62+
});
2663
```
2764

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

3067
```bash .env
68+
TRIGGER_SECRET_KEY="tr_prod_…"
3169
TRIGGER_API_URL="https://trigger.example.com"
32-
TRIGGER_PREVIEW_BRANCH="my-branch" # Only needed for preview branches
3370
```
3471

35-
The default URL is `https://api.trigger.dev`.
72+
The default API URL is `https://api.trigger.dev`.
3673

37-
### Manually Configuring the SDK
74+
## Create an additional key
3875

39-
If you prefer to manually configure the SDK, you can call the `configure` method:
76+
Create a separate key for each service or integration that accesses Trigger.dev.
4077

41-
```ts
42-
import { configure } from "@trigger.dev/sdk";
43-
import { myTask } from "./trigger/myTasks";
78+
<Note>
79+
Creating and revoking keys requires permission to manage API keys for the selected environment.
80+
The dashboard disables these actions when your role does not have permission.
81+
</Note>
4482

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-
});
83+
<Steps titleSize="h3">
84+
<Step title="Open the API keys page">
85+
Select the project and environment the integration needs to access, then open **API keys**.
86+
</Step>
87+
<Step title="Create the key">
88+
Click **New API key**, enter a descriptive name, and optionally set an expiration date. Names can
89+
contain up to 64 characters.
90+
</Step>
91+
<Step title="Choose its access">
92+
Select an access preset. For task-aware presets, choose all tasks or up to 10 task identifiers.
93+
</Step>
94+
<Step title="Copy and store the secret">
95+
Copy the key into your secret manager or backend environment. Trigger.dev shows the complete
96+
value only once.
97+
</Step>
98+
</Steps>
99+
100+
The dashboard displays the key's status, access, creator, creation time, and last-used time without storing or revealing its plaintext value.
101+
102+
## Access presets
103+
104+
Access presets define what an additional key can do. The dashboard shows which presets are available for your plan.
105+
106+
| Preset | Access |
107+
| --- | --- |
108+
| **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 |
109+
| **Task operator** | Trigger all or selected tasks and inspect or operate on their runs |
110+
| **Environment observer** | Read runs, tasks, batches, logs, traces, and queues |
111+
| **Environment operator** | Observe and operate on runs and queues, and trigger tasks |
112+
| **Deploy only** | Deploy new versions, read deployment status, and read environment variables |
113+
| **Environment variables only** | Read and write environment variables in this environment |
114+
| **No restrictions** | Full access to the environment, matching the root key |
50115

51-
async function triggerTask() {
52-
await myTask.trigger({ userId: "1234" }); // This will use the secret key and base URL you configured
53-
}
116+
**Trigger only** and **Task operator** can be restricted to selected tasks. Task restrictions use task identifiers, such as `send-email`, and continue to apply across deployments. A request involving multiple tasks succeeds only when the key can access every task in the request.
117+
118+
Access is fixed when you create a key. Changes to a preset do not alter existing keys. To change a key's access, revoke it and create a replacement.
119+
120+
<Warning>
121+
Streamed batch ingestion is not atomic. When using a task-restricted key, earlier items may be
122+
accepted before a later item fails validation or authorization.
123+
</Warning>
124+
125+
## Expire and revoke additional keys
126+
127+
Set an expiration date when creating a key if the integration only needs temporary access. An expired key stops authenticating automatically.
128+
129+
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.
130+
131+
Removing a team member does not revoke additional keys they created. Review and revoke their keys separately when their access changes.
132+
133+
## Regenerate the root key
134+
135+
Regenerating the root key creates a new value immediately. The previous root key remains valid for 24 hours so you can update services without downtime, then stops authenticating.
136+
137+
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. Additional-key revocation does not have a grace period.
138+
139+
## Create public access tokens
140+
141+
Additional keys can create scoped [Public Access Tokens](/realtime/auth) without receiving the environment's root key. Use `@trigger.dev/sdk` version 4.5.8 or later with additional keys.
142+
143+
When an additional key calls `auth.createPublicToken()`:
144+
145+
- The token must request at least one scope.
146+
- Its scopes cannot exceed the additional key's access.
147+
- It expires after 15 minutes by default.
148+
- Its expiration cannot exceed 30 days.
149+
- A numeric `expirationTime` is a Unix timestamp in seconds.
150+
151+
Revoking or expiring an additional key does not revoke tokens it already created. Those tokens remain valid until their own expiration, unless the environment's root key is regenerated first.
152+
153+
## Target Preview and Development branches
154+
155+
Preview and named Development branches use their parent environment's key set. Select the branch by setting `TRIGGER_PREVIEW_BRANCH` alongside the environment key:
156+
157+
```bash .env
158+
TRIGGER_SECRET_KEY="tr_preview_…"
159+
TRIGGER_PREVIEW_BRANCH="feature/new-checkout"
54160
```
161+
162+
The SDK sends the branch automatically. When calling the API directly, send the same value in the `x-trigger-branch` header.
163+
164+
## Self-hosting
165+
166+
Self-hosted installations support multiple additional keys with **No restrictions**. The restricted access presets are available in Trigger.dev Cloud.
167+
168+
Keep your instance and SDK current before creating additional keys. Calling a public-token API with an additional key on a server that does not support server-minted tokens returns an upgrade error; use the root key until the server is upgraded.
169+
170+
## Security recommendations
171+
172+
- Create one additional key per service or integration instead of sharing the root key.
173+
- Choose the narrowest access preset and task selection that supports the integration.
174+
- Store keys in a secret manager and inject them as backend environment variables.
175+
- Set expiration dates for temporary integrations and deployment credentials.
176+
- Revoke keys when an integration or team member no longer needs access.
177+
- Never put an API key in frontend code. Use scoped [Public Access Tokens](/realtime/auth) for client-side access.
178+
179+
## Next steps
180+
181+
<CardGroup cols={2}>
182+
<Card title="Trigger tasks" icon="bolt" href="/triggering">
183+
Trigger tasks from your backend with an environment API key.
184+
</Card>
185+
<Card title="Realtime authentication" icon="key" href="/realtime/auth">
186+
Create scoped public tokens for frontend and realtime access.
187+
</Card>
188+
</CardGroup>

0 commit comments

Comments
 (0)