fix(backend): Improve satellite auth redirect failures

[jescalan]

Summary

Improves the debugging experience for production satellite-domain auth failures when the handshake redirect_url points at a host that is not associated with the instance, such as a dynamic preview deployment. FAPI now returns a dedicated host-scoped error for this case and renders a readable HTML response for document handshakes, while the backend SDK logs satellite-specific guidance when this condition turns into a redirect loop.

Changes in this repo

Updates the backend SDK handshake redirect-loop diagnostic to show satellite-domain and preview-deployment guidance for SatelliteCookieNeedsSyncing loops, with a focused authenticateRequest regression test.

Companion PRs

• clerk_go: https://github.com/clerk/clerk_go/pull/19088

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	May 22, 2026 10:05pm

[changeset-bot]

⚠️ No Changeset found

Latest commit: e64e5f0

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

[jescalan]

@codex review

[coderabbitai]

Warning

Rate limit exceeded

@jescalan has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 13 minutes and 5 seconds before requesting another review.

You’ve run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro

Run ID: 6951c25f-1d3f-4f7b-81c1-3b4914238436

📥 Commits

Reviewing files that changed from the base of the PR and between fe5a49c and e64e5f0.

📒 Files selected for processing (2)

• packages/backend/src/tokens/__tests__/request.test.ts
• packages/backend/src/tokens/request.ts

---

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

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Keep it up!

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[pkg-pr-new]

Open in StackBlitz

@clerk/astro

npm i https://pkg.pr.new/@clerk/astro@8636

@clerk/backend

npm i https://pkg.pr.new/@clerk/backend@8636

@clerk/chrome-extension

npm i https://pkg.pr.new/@clerk/chrome-extension@8636

@clerk/clerk-js

npm i https://pkg.pr.new/@clerk/clerk-js@8636

@clerk/dev-cli

npm i https://pkg.pr.new/@clerk/dev-cli@8636

@clerk/expo

npm i https://pkg.pr.new/@clerk/expo@8636

@clerk/expo-passkeys

npm i https://pkg.pr.new/@clerk/expo-passkeys@8636

@clerk/express

npm i https://pkg.pr.new/@clerk/express@8636

@clerk/fastify

npm i https://pkg.pr.new/@clerk/fastify@8636

@clerk/hono

npm i https://pkg.pr.new/@clerk/hono@8636

@clerk/localizations

npm i https://pkg.pr.new/@clerk/localizations@8636

@clerk/nextjs

npm i https://pkg.pr.new/@clerk/nextjs@8636

@clerk/nuxt

npm i https://pkg.pr.new/@clerk/nuxt@8636

@clerk/react

npm i https://pkg.pr.new/@clerk/react@8636

@clerk/react-router

npm i https://pkg.pr.new/@clerk/react-router@8636

@clerk/shared

npm i https://pkg.pr.new/@clerk/shared@8636

@clerk/tanstack-react-start

npm i https://pkg.pr.new/@clerk/tanstack-react-start@8636

@clerk/testing

npm i https://pkg.pr.new/@clerk/testing@8636

@clerk/ui

npm i https://pkg.pr.new/@clerk/ui@8636

@clerk/upgrade

npm i https://pkg.pr.new/@clerk/upgrade@8636

@clerk/vue

npm i https://pkg.pr.new/@clerk/vue@8636

commit: e64e5f0