docs: document auth.withAuth scoped authentication helper

[isshaddad]

No description provided.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 56c884b

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]

Walkthrough

A new documentation section was added to docs/management/authentication.mdx that introduces the auth.withAuth API for temporarily scoping SDK authentication to a callback with an overridden token. The documentation includes an example with runs.list, clarifies that overridden credentials apply only within the callback scope, provides guidance on avoiding per-request usage on long-running servers, explains the process-wide global configuration behavior, warns about potential token leakage from overlapping withAuth calls, and references an issue tracking an async-context isolation solution.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The pull request description is completely empty. The required template sections (Closes #issue, Checklist, Testing, Changelog, Screenshots) are entirely missing.	Add a complete pull request description following the repository template, including issue reference, completed checklist, testing details, and changelog entry.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately and specifically describes the main change: documentation for the auth.withAuth scoped authentication helper.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/auth-with-auth

---

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 and usage tips.}

[coderabbitai]

🧹 Nitpick comments (1)

docs/management/authentication.mdx (1)

184-186: Minor: "looking block-scoped" phrasing and overlap warning.

The prose is accurate per the implementation (runWithConfig swaps a process-wide global and restores it in finally), but consider tightening the Warning above to explicitly call out Promise.all / concurrent request handlers — right now that critical caveat lives only in the body paragraph below the Warning, where readers skimming the callout may miss it.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/management/authentication.mdx` around lines 184 - 186, Update the
Warning callout to explicitly mention the concurrency caveat: say that
auth.withAuth (which uses runWithConfig to swap a process-wide global) is not
safe for overlapping concurrent usage such as Promise.all or concurrent request
handlers, because the most recently installed config is shared; move or
duplicate that sentence from the paragraph into the Warning so readers who skim
the callout see the explicit examples and risk immediately.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@docs/management/authentication.mdx`:
- Around line 184-186: Update the Warning callout to explicitly mention the
concurrency caveat: say that auth.withAuth (which uses runWithConfig to swap a
process-wide global) is not safe for overlapping concurrent usage such as
Promise.all or concurrent request handlers, because the most recently installed
config is shared; move or duplicate that sentence from the paragraph into the
Warning so readers who skim the callout see the explicit examples and risk
immediately.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 9a595b99-3912-4269-88e4-f560fcd97a2e

📥 Commits

Reviewing files that changed from the base of the PR and between 41434b5 and 56c884b.

📒 Files selected for processing (1)

• docs/management/authentication.mdx

📜 Review details

🧰 Additional context used

📓 Path-based instructions (1)

docs/**/*.mdx

📄 CodeRabbit inference engine (docs/CLAUDE.md)

docs/**/*.mdx: MDX documentation pages must include frontmatter with title (required), description (required), and sidebarTitle (optional) in YAML format
Use Mintlify components for structured content: , , , , , , /, /
Always import from @trigger.dev/sdk in code examples (never from @trigger.dev/sdk/v3)
Code examples must be complete and runnable where possible
Use language tags in code fences: typescript, bash, json

Files:

• docs/management/authentication.mdx

🧠 Learnings (5)

📓 Common learnings

Learnt from: nicktrn
Repo: triggerdotdev/trigger.dev PR: 3200
File: docs/config/config-file.mdx:353-368
Timestamp: 2026-03-10T12:44:19.869Z
Learning: In the triggerdotdev/trigger.dev repository, docs PRs are often written as companions to implementation PRs (e.g., PR `#3200` documents features being added in PR `#3196`). When reviewing docs PRs, the documented features may exist in a companion/companion PR branch rather than main. Always check companion PRs referenced in the PR description before flagging missing implementations.

📚 Learning: 2026-03-25T15:29:25.889Z

Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2026-03-25T15:29:25.889Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : Use `task()` from `trigger.dev/sdk` for basic task definitions with `id` and `run` properties

Applied to files:

• docs/management/authentication.mdx

📚 Learning: 2025-08-14T10:53:54.526Z

Learnt from: myftija
Repo: triggerdotdev/trigger.dev PR: 2391
File: apps/webapp/app/services/organizationAccessToken.server.ts:50-0
Timestamp: 2025-08-14T10:53:54.526Z
Learning: In the Trigger.dev codebase, token service functions (like revokePersonalAccessToken and revokeOrganizationAccessToken) don't include tenant scoping in their database queries. Instead, authorization and tenant scoping happens at a higher level in the authentication flow (typically in route handlers) before these service functions are called. This is a consistent pattern across both Personal Access Tokens (PATs) and Organization Access Tokens (OATs).

Applied to files:

• docs/management/authentication.mdx

📚 Learning: 2026-03-25T15:29:25.889Z

Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2026-03-25T15:29:25.889Z
Learning: Applies to trigger.config.ts : Configure the Trigger.dev project using `defineConfig()` with properties like `project`, `dirs`, `retries`, `runtime`, and `build`

Applied to files:

• docs/management/authentication.mdx

📚 Learning: 2026-03-10T12:44:14.176Z

Learnt from: nicktrn
Repo: triggerdotdev/trigger.dev PR: 3200
File: docs/config/config-file.mdx:353-368
Timestamp: 2026-03-10T12:44:14.176Z
Learning: In the trigger.dev repo, docs PRs are often companions to implementation PRs. When reviewing docs PRs (MDX files under docs/), check the PR description for any companion/related PR references and verify that the documented features exist in those companion PRs before flagging missing implementations. This ensures docs stay in sync with code changes across related PRs.

Applied to files:

• docs/management/authentication.mdx

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
trigger	🟢 Ready	View Preview	Apr 23, 2026, 5:28 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no potential bugs to report.

View in Devin Review to see 1 additional finding.