fix(backend): warn once for azp-less cookie token instead of per request

[jacekradko]

@clerk/backend warns when a cookie session token has no azp claim. The warning sits on the per-request verify path, so a single azp-less token (which gets reused until it refreshes) logs the same line on every authenticated request, tens of thousands of times a day in #8231's case.

logger.warnOnce keeps the heads-up but collapses it to one line per process. Auth is unchanged: the token still verifies and the user stays signed in.

[changeset-bot]

🦋 Changeset detected

Latest commit: 008ff97

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 10 packages

Name	Type
@clerk/backend	Patch
@clerk/astro	Patch
@clerk/express	Patch
@clerk/fastify	Patch
@clerk/hono	Patch
@clerk/nextjs	Patch
@clerk/nuxt	Patch
@clerk/react-router	Patch
@clerk/tanstack-react-start	Patch
@clerk/testing	Patch

Not sure what this means? Click here to learn what changesets are.

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

[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 28, 2026 8:31pm

[coderabbitai]

Actionable comments posted: 0

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

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

Review profile: CHILL

Plan: Pro

Run ID: 2bdfae66-c2a5-420a-974b-61f3ed0e2362

📥 Commits

Reviewing files that changed from the base of the PR and between 37535f9 and 008ff97.

📒 Files selected for processing (3)

• .changeset/azp-cookie-warning-warn-once.md
• packages/backend/src/tokens/__tests__/request_azp.test.ts
• packages/backend/src/tokens/request.ts

---

📝 Walkthrough

Walkthrough

This PR updates the @clerk/backend package to throttle a session-token warning. When a session token lacks the azp claim, the code now emits the warning once per process using logger.warnOnce instead of calling console.warn on every authenticated request. The test is updated to verify that two consecutive requests with the same azp-less cookie trigger the warning only once. A changeset entry documents this as a patch behavior change.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: switching from per-request warnings to a single warning per process for azp-less cookie tokens.
Description check	✅ Passed	The description provides relevant context about the issue being fixed, explains the problem the change addresses, and clarifies that authentication behavior remains unchanged.
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.}

---

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

[github-actions]

Snapi: no API changes detected in @clerk/backend, @clerk/clerk-js, @clerk/nextjs, @clerk/react, @clerk/shared, @clerk/ui.

[pkg-pr-new]

Open in StackBlitz

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/dev-cli

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

@clerk/expo

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/hono

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: 008ff97