docs: document additional environment API keys

[carderne]

Summary

Expands the API key guide to cover root and additional environment keys. It explains how to configure the SDK, create keys with limited access, manage expiration and revocation, rotate the root key, and use keys with public tokens and branch environments.

Design

The guide describes access presets at the product level without exposing authorization internals. It also documents copy-once secrets, immutable access policies, task-selection limits, public-token lifetimes, streamed-batch behavior, and the supported self-hosted configuration.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 0ab9813

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 6e7bf60e-f362-4b2a-ae1c-4d95ada0a016

📥 Commits

Reviewing files that changed from the base of the PR and between 8cab73f and 0f1a46e.

📒 Files selected for processing (1)

• docs/apikeys.mdx

🚧 Files skipped from review as they are similar to previous changes (1)

• docs/apikeys.mdx

---

Walkthrough

Updates API key documentation with environment scoping, SDK and self-hosted configuration, key creation, access presets, deployment authentication, expiration, revocation, public tokens, branch targeting, root-key regeneration, and security guidance. Clarifies that numeric public-token expiration values use Unix timestamps in seconds and cannot exceed 30 days.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description explains the documentation changes but omits the required issue reference, checklist, testing, changelog, and screenshots sections.	Add the required template sections and complete the checklist, testing steps, changelog, screenshots, and issue reference.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the primary change: documenting additional environment API keys.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/api-keys-overhaul

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Note

GitHub couldn't provide a complete incremental comparison for this pull request, so CodeRabbit is performing a full review instead. This review may take a little longer.

[pkg-pr-new]

Open in StackBlitz

@trigger.dev/build

npm i https://pkg.pr.new/@trigger.dev/build@0ab9813

trigger.dev

npm i https://pkg.pr.new/trigger.dev@0ab9813

@trigger.dev/core

npm i https://pkg.pr.new/@trigger.dev/core@0ab9813

@trigger.dev/python

npm i https://pkg.pr.new/@trigger.dev/python@0ab9813

@trigger.dev/react-hooks

npm i https://pkg.pr.new/@trigger.dev/react-hooks@0ab9813

@trigger.dev/redis-worker

npm i https://pkg.pr.new/@trigger.dev/redis-worker@0ab9813

@trigger.dev/rsc

npm i https://pkg.pr.new/@trigger.dev/rsc@0ab9813

@trigger.dev/schema-to-json

npm i https://pkg.pr.new/@trigger.dev/schema-to-json@0ab9813

@trigger.dev/sdk

npm i https://pkg.pr.new/@trigger.dev/sdk@0ab9813

commit: 0ab9813

[coderabbitai]

Note

GitHub couldn't provide a complete incremental comparison for this pull request, so CodeRabbit is performing a full review instead. This review may take a little longer.

[devin-ai-integration]

Devin Review found 1 new potential issue.

[devin-ai-integration]

🔍 Self-hosting claim may not hold with the additional-key lookup feature flag off by default

The doc states self-hosted installs support multiple keys with No restrictions. On the server side, resolving an additional (non-root) key is gated by additionalApiKeyLookupEnabled, which is derived from a feature flag that defaults to false (apps/webapp/app/services/authFeatureControls.ts:11), and resolveEnvironmentByApiKey returns { ok: false, reason: "disabled" } when it is off (apps/webapp/app/models/runtimeEnvironment.server.ts:131-134). Worth confirming whether self-hosted deployments enable this flag by default; otherwise the section should mention the required flag/config.

---

Was this helpful? React with 👍 or 👎 to provide feedback.