chore(backend): Rename machine auth verification methods #7347

wobsoriano · 2025-12-02T19:38:49Z

Description

Unifies machine token verification method naming across all three machine authentication APIs. Previously, each API had a different method name for verification:

client.apiKeys.verifySecret()
client.m2m.verifyToken()
client.idPOAuthAccessToken.verifyAccessToken() (We dont have docs for this, but exposed publicly)

This PR introduces a consistent verify() method for all three APIs while deprecating the existing methods for backwards compatibility.

Resolves USER-4130

Checklist

pnpm test runs as expected.
pnpm build runs as expected.
(If applicable) JSDoc comments have been added or updated for any package exports
(If applicable) Documentation has been updated

Type of change

Summary by CodeRabbit

New Features
- Unified verification: a single verify() method now handles verification for machine tokens, API keys, and OAuth access tokens to simplify usage.
Deprecations
- Older verification methods are deprecated; migrate to verify() to ensure forward compatibility and receive deprecation notices.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

changeset-bot · 2025-12-02T19:38:53Z

🦋 Changeset detected

Latest commit: c8b3223

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

This PR includes changesets to release 11 packages

Name	Type
@clerk/backend	Minor
@clerk/agent-toolkit	Patch
@clerk/astro	Patch
@clerk/express	Patch
@clerk/fastify	Patch
@clerk/nextjs	Patch
@clerk/nuxt	Patch
@clerk/react-router	Patch
@clerk/remix	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 · 2025-12-02T19:38:55Z

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

Project	Deployment	Preview	Comments	Updated (UTC)
clerk-js-sandbox	Ready	Preview	Comment	Dec 2, 2025 8:34pm

coderabbitai · 2025-12-02T19:39:00Z

Walkthrough

This change unifies machine-token verification method names across the backend package by introducing verify() methods and providing deprecated wrappers (verifyToken, verifyAccessToken, verifySecret) that delegate to verify(). Tests and internal callers were updated and a changeset records the minor version bump.

Changes

Cohort / File(s)	Summary
Changeset `.changeset/spotty-wasps-smoke.md`	Added a changeset entry bumping `@clerk/backend` with description "Rename machine auth verification methods".
API endpoints `packages/backend/src/api/endpoints/M2MTokenApi.ts`, `packages/backend/src/api/endpoints/IdPOAuthAccessTokenApi.ts`, `packages/backend/src/api/endpoints/APIKeysApi.ts`	Added new `verify(...)` public methods. Added deprecated wrappers `verifyToken(...)`, `verifyAccessToken(...)`, and `verifySecret(...)` that call `verify(...)` and emit deprecation warnings.
Token verification logic `packages/backend/src/tokens/verify.ts`	Updated callers to use the new `verify()` methods for M2M, OAuth access tokens, and API keys instead of the old method names.
Tests `packages/backend/src/api/__tests__/M2MTokenApi.test.ts`, `packages/backend/src/api/__tests__/factory.test.ts`	Updated test suites and call sites to invoke `apiClient.*.verify(...)` instead of the previous method names; expectations and flows unchanged.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Check each API endpoint for consistent deprecation message formatting and proper deprecated import/use.
Verify the deprecated wrappers correctly delegate arguments and return values (including error paths).
Ensure all internal call sites (e.g., tokens/verify.ts) match the new signatures and tests reflect intended behavior.

Poem

🐰 I bounced through code with joyful cheer,
Old names whispering, "We'll still be near."
Now verify() hops into the light,
Deprecated friends waved out of sight,
A tidy trail of carrot-coded delight 🥕

Pre-merge checks and finishing touches

❌ 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%.	You can run `@coderabbitai generate docstrings` to improve docstring coverage.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title accurately describes the main change: renaming machine auth verification methods across three APIs to unify them under verify().
Linked Issues check	✅ Passed	The PR successfully implements all coding requirements from USER-4130: adds verify() methods to APIKeysAPI, M2MTokenApi, and IdPOAuthAccessTokenApi, deprecates existing methods for backwards compatibility, and updates all call sites.
Out of Scope Changes check	✅ Passed	All changes are directly related to the objective of renaming verification methods. No out-of-scope changes detected.

✨ Finishing touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Post copyable unit tests in a comment
Commit unit tests in branch rob/user-4130-rename-verification-methods

📜 Recent review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Disabled knowledge base sources:

Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between bac3b5b and c8b3223.

📒 Files selected for processing (1)

.changeset/spotty-wasps-smoke.md (1 hunks)

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

.changeset/spotty-wasps-smoke.md

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (5)

GitHub Check: Formatting | Dedupe | Changeset
GitHub Check: Build Packages
GitHub Check: Analyze (javascript-typescript)
GitHub Check: semgrep-cloud-platform/scan
GitHub Check: semgrep-cloud-platform/scan

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

pkg-pr-new · 2025-12-02T19:43:01Z

Open in StackBlitz

@clerk/agent-toolkit

npm i https://pkg.pr.new/@clerk/agent-toolkit@7347

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/dev-cli

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

@clerk/elements

npm i https://pkg.pr.new/@clerk/elements@7347

@clerk/clerk-expo

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/clerk-react

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

@clerk/react-router

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

@clerk/remix

npm i https://pkg.pr.new/@clerk/remix@7347

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/themes

npm i https://pkg.pr.new/@clerk/themes@7347

@clerk/types

npm i https://pkg.pr.new/@clerk/types@7347

@clerk/upgrade

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

@clerk/vue

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

commit: c8b3223

coderabbitai

Actionable comments posted: 5

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

packages/backend/src/api/endpoints/M2MTokenApi.ts (1)
98-111: Add explicit return type and JSDoc documentation.

This public API method is missing an explicit return type annotation and JSDoc documentation.

As per coding guidelines, apply this diff to add the return type:
-  async verify(params: VerifyM2MTokenParams) {
+  async verify(params: VerifyM2MTokenParams): Promise<M2MToken> {
Additionally, add JSDoc documentation above the method:
  /**
   * Verifies a machine-to-machine token.
   *
   * @param params - The verification parameters including the token and optional machine secret key.
   * @returns A promise that resolves to the verified M2M token.
   */
  async verify(params: VerifyM2MTokenParams): Promise<M2MToken> {

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Disabled knowledge base sources:

Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between e113464 and bac3b5b.

📒 Files selected for processing (7)

.changeset/spotty-wasps-smoke.md (1 hunks)
packages/backend/src/api/__tests__/M2MTokenApi.test.ts (4 hunks)
packages/backend/src/api/__tests__/factory.test.ts (3 hunks)
packages/backend/src/api/endpoints/APIKeysApi.ts (2 hunks)
packages/backend/src/api/endpoints/IdPOAuthAccessTokenApi.ts (1 hunks)
packages/backend/src/api/endpoints/M2MTokenApi.ts (3 hunks)
packages/backend/src/tokens/verify.ts (3 hunks)

🧰 Additional context used

📓 Path-based instructions (9)

**/*.{js,jsx,ts,tsx}