docs(backend,expo,nextjs): Fix broken BAPI links in JSDoc comments (#8655)

alexisintech · wobsoriano · web-flow · commit 079691109fa1 · 2026-05-27T11:52:19.000-07:00
Co-authored-by: Robert Soriano &lt;sorianorobertc@gmail.com&gt;
diff --git a/.changeset/eager-experts-mate.md b/.changeset/eager-experts-mate.md
@@ -0,0 +1,2 @@
+---
+---
diff --git a/packages/backend/src/api/resources/AllowlistIdentifier.ts b/packages/backend/src/api/resources/AllowlistIdentifier.ts
@@ -2,7 +2,7 @@ import type { AllowlistIdentifierType } from './Enums';
 import type { AllowlistIdentifierJSON } from './JSON';
 
 /**
- * The Backend `AllowlistIdentifier` object represents an identifier that has been added to the allowlist of your application. The Backend `AllowlistIdentifier` object is used in the [Backend API](https://clerk.com/docs/reference/backend-api/tag/Allow-list-Block-list#operation/ListAllowlistIdentifiers) and is not directly accessible from the Frontend API.
+ * The Backend `AllowlistIdentifier` object represents an identifier that has been added to the allowlist of your application. The Backend `AllowlistIdentifier` object is used in the [Backend API](https://clerk.com/docs/reference/backend-api/model/AllowlistIdentifier) and is not directly accessible from the Frontend API.
  */
 export class AllowlistIdentifier {
   constructor(
diff --git a/packages/backend/src/api/resources/Client.ts b/packages/backend/src/api/resources/Client.ts
@@ -4,7 +4,7 @@ import type { ClientJSON } from './JSON';
 import { Session } from './Session';
 
 /**
- * The Backend `Client` object is similar to the [`Client`](https://clerk.com/docs/reference/objects/client) object as it holds information about the authenticated sessions in the current device. However, the Backend `Client` object is different from the `Client` object in that it is used in the [Backend API](https://clerk.com/docs/reference/backend-api/tag/Clients#operation/GetClient) and is not directly accessible from the Frontend API.
+ * The Backend `Client` object is similar to the [`Client`](https://clerk.com/docs/reference/objects/client) object as it holds information about the authenticated sessions in the current device. However, the Backend `Client` object is different from the `Client` object in that it is used in the [Backend API](https://clerk.com/docs/reference/backend-api/model/Client) and is not directly accessible from the Frontend API.
  */
 export class Client {
   constructor(
diff --git a/packages/backend/src/api/resources/CommercePlan.ts b/packages/backend/src/api/resources/CommercePlan.ts
@@ -4,7 +4,7 @@ import { Feature } from './Feature';
 import type { BillingPlanJSON } from './JSON';
 
 /**
- * The `BillingPlan` object is similar to the [`BillingPlanResource`](/docs/reference/types/billing-plan-resource) object as it holds information about a Plan, as well as methods for managing it. However, the `BillingPlan` object is different in that it is used in the [Backend API](https://clerk.com/docs/reference/backend-api/tag/commerce/get/commerce/plans) and is not directly accessible from the Frontend API.
+ * The `BillingPlan` object is similar to the [`BillingPlanResource`](/docs/reference/types/billing-plan-resource) object as it holds information about a Plan, as well as methods for managing it. However, the `BillingPlan` object is different in that it is used in the [Backend API](https://clerk.com/docs/reference/backend-api/tag/billing/GET/billing/plans) and is not directly accessible from the Frontend API.
  *
  * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
  */
diff --git a/packages/backend/src/api/resources/CommerceSubscription.ts b/packages/backend/src/api/resources/CommerceSubscription.ts
@@ -4,7 +4,7 @@ import { BillingSubscriptionItem } from './CommerceSubscriptionItem';
 import type { BillingSubscriptionJSON } from './JSON';
 
 /**
- * The `BillingSubscription` object is similar to the [`BillingSubscriptionResource`](/docs/reference/types/billing-subscription-resource) object as it holds information about a subscription, as well as methods for managing it. However, the `BillingSubscription` object is different in that it is used in the [Backend API](https://clerk.com/docs/reference/backend-api/tag/billing/get/organizations/%7Borganization_id%7D/billing/subscription) and is not directly accessible from the Frontend API.
+ * The `BillingSubscription` object is similar to the [`BillingSubscriptionResource`](/docs/reference/types/billing-subscription-resource) object as it holds information about a subscription, as well as methods for managing it. However, the `BillingSubscription` object is different in that it is used in the [Backend API](https://clerk.com/docs/reference/backend-api/tag/billing/GET/organizations/%7Borganization_id%7D/billing/subscription) and is not directly accessible from the Frontend API.
  *
  * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
  */
diff --git a/packages/backend/src/api/resources/CommerceSubscriptionItem.ts b/packages/backend/src/api/resources/CommerceSubscriptionItem.ts
@@ -4,7 +4,7 @@ import { BillingPlan } from './CommercePlan';
 import type { BillingSubscriptionItemJSON } from './JSON';
 
 /**
- * The `BillingSubscriptionItem` object is similar to the [`BillingSubscriptionItemResource`](/docs/reference/types/billing-subscription-item-resource) object as it holds information about a subscription item, as well as methods for managing it. However, the `BillingSubscriptionItem` object is different in that it is used in the [Backend API](https://clerk.com/docs/reference/backend-api/tag/commerce/get/commerce/subscription_items) and is not directly accessible from the Frontend API.
+ * The `BillingSubscriptionItem` object is similar to the [`BillingSubscriptionItemResource`](/docs/reference/types/billing-subscription-item-resource) object as it holds information about a subscription item, as well as methods for managing it. However, the `BillingSubscriptionItem` object is different in that it is used in the [Backend API](https://clerk.com/docs/reference/backend-api/tag/billing/GET/billing/subscription_items) and is not directly accessible from the Frontend API.
  *
  * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
  */
diff --git a/packages/backend/src/api/resources/Deserializer.ts b/packages/backend/src/api/resources/Deserializer.ts
@@ -114,7 +114,7 @@ function isPaginated(payload: unknown): payload is PaginatedResponseJSON {
  * formats. Once BAPI Proxy is updated to return the standard `data` property format,
  * this function can be safely removed.
  *
- * @see https://clerk.com/docs/reference/backend-api/tag/m2m-tokens/get/m2m_tokens
+ * @see https://clerk.com/docs/reference/backend-api/tag/m2m-tokens/GET/m2m_tokens
  */
 function isM2MTokenResponse(payload: unknown): payload is { m2m_tokens: unknown[]; total_count: number } {
   if (!payload || typeof payload !== 'object' || !('m2m_tokens' in payload)) {
diff --git a/packages/backend/src/api/resources/Organization.ts b/packages/backend/src/api/resources/Organization.ts
@@ -1,7 +1,7 @@
 import type { OrganizationJSON } from './JSON';
 
 /**
- * The Backend `Organization` object is similar to the [`Organization`](https://clerk.com/docs/reference/objects/organization) object as it holds information about an Organization, as well as methods for managing it. However, the Backend `Organization` object is different in that it is used in the [Backend API](https://clerk.com/docs/reference/backend-api/tag/Organizations#operation/ListOrganizations){{ target: '_blank' }} and is not directly accessible from the Frontend API.
+ * The Backend `Organization` object is similar to the [`Organization`](https://clerk.com/docs/reference/objects/organization) object as it holds information about an Organization, as well as methods for managing it. However, the Backend `Organization` object is different in that it is used in the [Backend API](https://clerk.com/docs/reference/backend-api/model/Organization){{ target: '_blank' }} and is not directly accessible from the Frontend API.
  */
 export class Organization {
   private _raw: OrganizationJSON | null = null;
diff --git a/packages/backend/src/api/resources/OrganizationInvitation.ts b/packages/backend/src/api/resources/OrganizationInvitation.ts
@@ -2,7 +2,7 @@ import type { OrganizationInvitationStatus, OrganizationMembershipRole } from '.
 import type { OrganizationInvitationJSON, PublicOrganizationDataJSON } from './JSON';
 
 /**
- * The Backend `OrganizationInvitation` object is similar to the [`OrganizationInvitation`](https://clerk.com/docs/reference/types/organization-invitation) object as it's the model around an Organization invitation. However, the Backend `OrganizationInvitation` object is different in that it's used in the [Backend API](https://clerk.com/docs/reference/backend-api/tag/Organization-Invitations#operation/CreateOrganizationInvitation){{ target: '_blank' }} and is not directly accessible from the Frontend API.
+ * The Backend `OrganizationInvitation` object is similar to the [`OrganizationInvitation`](https://clerk.com/docs/reference/types/organization-invitation) object as it's the model around an Organization invitation. However, the Backend `OrganizationInvitation` object is different in that it's used in the [Backend API](https://clerk.com/docs/reference/backend-api/model/OrganizationInvitation){{ target: '_blank' }} and is not directly accessible from the Frontend API.
  */
 export class OrganizationInvitation {
   private _raw: OrganizationInvitationJSON | null = null;
diff --git a/packages/backend/src/api/resources/OrganizationMembership.ts b/packages/backend/src/api/resources/OrganizationMembership.ts
@@ -3,7 +3,7 @@ import type { OrganizationMembershipRole } from './Enums';
 import type { OrganizationMembershipJSON, OrganizationMembershipPublicUserDataJSON } from './JSON';
 
 /**
- * The Backend `OrganizationMembership` object is similar to the [`OrganizationMembership`](https://clerk.com/docs/reference/types/organization-membership) object as it's the model around an Organization membership entity and describes the relationship between users and Organizations. However, the Backend `OrganizationMembership` object is different in that it's used in the [Backend API](https://clerk.com/docs/reference/backend-api/tag/Organization-Memberships#operation/CreateOrganizationMembership){{ target: '_blank' }} and is not directly accessible from the Frontend API.
+ * The Backend `OrganizationMembership` object is similar to the [`OrganizationMembership`](https://clerk.com/docs/reference/types/organization-membership) object as it's the model around an Organization membership entity and describes the relationship between users and Organizations. However, the Backend `OrganizationMembership` object is different in that it's used in the [Backend API](https://clerk.com/docs/reference/backend-api/model/OrganizationMembership){{ target: '_blank' }} and is not directly accessible from the Frontend API.
  */
 export class OrganizationMembership {
   private _raw: OrganizationMembershipJSON | null = null;
diff --git a/packages/backend/src/api/resources/Session.ts b/packages/backend/src/api/resources/Session.ts
@@ -54,7 +54,7 @@ export class SessionActivity {
 }
 
 /**
- * The Backend `Session` object is similar to the [`Session`](https://clerk.com/docs/reference/objects/session) object as it is an abstraction over an HTTP session and models the period of information exchange between a user and the server. However, the Backend `Session` object is different as it is used in the [Backend API](https://clerk.com/docs/reference/backend-api/tag/Sessions#operation/GetSessionList) and is not directly accessible from the Frontend API.
+ * The Backend `Session` object is similar to the [`Session`](https://clerk.com/docs/reference/objects/session) object as it is an abstraction over an HTTP session and models the period of information exchange between a user and the server. However, the Backend `Session` object is different as it is used in the [Backend API](https://clerk.com/docs/reference/backend-api/model/Session) and is not directly accessible from the Frontend API.
  */
 export class Session {
   constructor(
diff --git a/packages/backend/src/api/resources/User.ts b/packages/backend/src/api/resources/User.ts
@@ -6,7 +6,7 @@ import { PhoneNumber } from './PhoneNumber';
 import { Web3Wallet } from './Web3Wallet';
 
 /**
- * The Backend `User` object is similar to the `User` object as it holds information about a user of your application, such as their unique identifier, name, email addresses, phone numbers, and more. However, the Backend `User` object is different from the `User` object in that it is used in the [Backend API](https://clerk.com/docs/reference/backend-api/tag/Users#operation/GetUser){{ target: '_blank' }} and is not directly accessible from the Frontend API.
+ * The Backend `User` object is similar to the `User` object as it holds information about a user of your application, such as their unique identifier, name, email addresses, phone numbers, and more. However, the Backend `User` object is different from the `User` object in that it is used in the [Backend API](https://clerk.com/docs/reference/backend-api/model/User){{ target: '_blank' }} and is not directly accessible from the Frontend API.
  */
 export class User {
   private _raw: UserJSON | null = null;
diff --git a/packages/backend/src/tokens/verify.ts b/packages/backend/src/tokens/verify.ts
@@ -44,7 +44,7 @@ export type VerifyTokenOptions = Simplify<
  * > [!WARNING]
  * > This is a lower-level method intended for more advanced use-cases. It's recommended to use [`authenticateRequest()`](https://clerk.com/docs/reference/backend/authenticate-request), which fully authenticates a token passed from the `request` object.
  *
- * Verifies a Clerk-generated token signature. Networkless if the `jwtKey` is provided. Otherwise, performs a network call to retrieve the JWKS from the [Backend API](https://clerk.com/docs/reference/backend-api/tag/JWKS#operation/GetJWKS){{ target: '_blank' }}.
+ * Verifies a Clerk-generated token signature. Networkless if the `jwtKey` is provided. Otherwise, performs a network call to retrieve the JWKS from the [Backend API](https://clerk.com/docs/reference/backend-api/tag/jwks/GET/jwks){{ target: '_blank' }}.
  *
  * @param token - The token to verify.
  * @param options - Options for verifying the token. It is recommended to set these options as [environment variables](/docs/guides/development/clerk-environment-variables#api-and-sdk-configuration) where possible, and then pass them to the function. For example, you can set the `secretKey` option using the `CLERK_SECRET_KEY` environment variable, and then pass it to the function like this: `verifyToken(token, { secretKey: process.env.CLERK_SECRET_KEY })`.
diff --git a/packages/expo/src/hooks/useOAuth.ts b/packages/expo/src/hooks/useOAuth.ts
@@ -62,7 +62,7 @@ export function useOAuth(useOAuthParams: UseOAuthFlowParams) {
     // Create a redirect url for the current platform and environment.
     //
     // This redirect URL needs to be whitelisted for your Clerk production instance via
-    // https://clerk.com/docs/reference/backend-api/tag/Redirect-URLs#operation/CreateRedirectURL
+    // https://clerk.com/docs/reference/backend-api/tag/redirect-urls/POST/redirect_urls
     //
     // For more information go to:
     // https://docs.expo.dev/versions/latest/sdk/auth-session/#authsessionmakeredirecturi
diff --git a/packages/expo/src/hooks/useSSO.ts b/packages/expo/src/hooks/useSSO.ts
@@ -67,7 +67,7 @@ export function useSSO() {
      * Creates a redirect URL based on the application platform
      * It must be whitelisted, either via Clerk Dashboard, or BAPI, in order
      * to include the `rotating_token_nonce` on SSO callback
-     * @ref https://clerk.com/docs/reference/backend-api/tag/Redirect-URLs#operation/CreateRedirectURL
+     * @ref https://clerk.com/docs/reference/backend-api/tag/redirect-urls/POST/redirect_urls
      */
     const redirectUrl =
       startSSOFlowParams.redirectUrl ??
diff --git a/packages/nextjs/src/app-router/server/currentUser.ts b/packages/nextjs/src/app-router/server/currentUser.ts
@@ -12,7 +12,7 @@ type CurrentUserOptions = PendingSessionOptions;
  *
  * Under the hood, this helper:
  * - calls `fetch()`, so it is automatically deduped per request.
- * - uses the [`GET /v1/users/{user_id}`](https://clerk.com/docs/reference/backend-api/tag/Users#operation/GetUser) endpoint.
+ * - uses the [`GET /v1/users/{user_id}`](https://clerk.com/docs/reference/backend-api/tag/users/GET/users/%7Buser_id%7D) endpoint.
  * - counts towards the [Backend API request rate limit](https://clerk.com/docs/guides/how-clerk-works/system-limits).
  *
  * @example

Original file line number	Diff line number	Diff line change
`@@ -4,7 +4,7 @@ import { Feature } from './Feature';`
`4`	`4`	`import type { BillingPlanJSON } from './JSON';`
`5`	`5`
`6`	`6`	`/**`
`7`		- * The `BillingPlan` object is similar to the [`BillingPlanResource`](/docs/reference/types/billing-plan-resource) object as it holds information about a Plan, as well as methods for managing it. However, the `BillingPlan` object is different in that it is used in the [Backend API](https://clerk.com/docs/reference/backend-api/tag/commerce/get/commerce/plans) and is not directly accessible from the Frontend API.
	`7`	+ * The `BillingPlan` object is similar to the [`BillingPlanResource`](/docs/reference/types/billing-plan-resource) object as it holds information about a Plan, as well as methods for managing it. However, the `BillingPlan` object is different in that it is used in the [Backend API](https://clerk.com/docs/reference/backend-api/tag/billing/GET/billing/plans) and is not directly accessible from the Frontend API.
`8`	`8`	`*`
`9`	`9`	`* @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.`
`10`	`10`	`*/`
Original file line number	Diff line number	Diff line change
`@@ -4,7 +4,7 @@ import { BillingSubscriptionItem } from './CommerceSubscriptionItem';`
`4`	`4`	`import type { BillingSubscriptionJSON } from './JSON';`
`5`	`5`
`6`	`6`	`/**`
`7`		- * The `BillingSubscription` object is similar to the [`BillingSubscriptionResource`](/docs/reference/types/billing-subscription-resource) object as it holds information about a subscription, as well as methods for managing it. However, the `BillingSubscription` object is different in that it is used in the [Backend API](https://clerk.com/docs/reference/backend-api/tag/billing/get/organizations/%7Borganization_id%7D/billing/subscription) and is not directly accessible from the Frontend API.
	`7`	+ * The `BillingSubscription` object is similar to the [`BillingSubscriptionResource`](/docs/reference/types/billing-subscription-resource) object as it holds information about a subscription, as well as methods for managing it. However, the `BillingSubscription` object is different in that it is used in the [Backend API](https://clerk.com/docs/reference/backend-api/tag/billing/GET/organizations/%7Borganization_id%7D/billing/subscription) and is not directly accessible from the Frontend API.
`8`	`8`	`*`
`9`	`9`	`* @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.`
`10`	`10`	`*/`
Original file line number	Diff line number	Diff line change
`@@ -4,7 +4,7 @@ import { BillingPlan } from './CommercePlan';`
`4`	`4`	`import type { BillingSubscriptionItemJSON } from './JSON';`
`5`	`5`
`6`	`6`	`/**`
`7`		- * The `BillingSubscriptionItem` object is similar to the [`BillingSubscriptionItemResource`](/docs/reference/types/billing-subscription-item-resource) object as it holds information about a subscription item, as well as methods for managing it. However, the `BillingSubscriptionItem` object is different in that it is used in the [Backend API](https://clerk.com/docs/reference/backend-api/tag/commerce/get/commerce/subscription_items) and is not directly accessible from the Frontend API.
	`7`	+ * The `BillingSubscriptionItem` object is similar to the [`BillingSubscriptionItemResource`](/docs/reference/types/billing-subscription-item-resource) object as it holds information about a subscription item, as well as methods for managing it. However, the `BillingSubscriptionItem` object is different in that it is used in the [Backend API](https://clerk.com/docs/reference/backend-api/tag/billing/GET/billing/subscription_items) and is not directly accessible from the Frontend API.
`8`	`8`	`*`
`9`	`9`	`* @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.`
`10`	`10`	`*/`
Original file line number	Diff line number	Diff line change
`@@ -114,7 +114,7 @@ function isPaginated(payload: unknown): payload is PaginatedResponseJSON {`
`114`	`114`	* formats. Once BAPI Proxy is updated to return the standard `data` property format,
`115`	`115`	`* this function can be safely removed.`
`116`	`116`	`*`
`117`		`- * @see https://clerk.com/docs/reference/backend-api/tag/m2m-tokens/get/m2m_tokens`
	`117`	`+ * @see https://clerk.com/docs/reference/backend-api/tag/m2m-tokens/GET/m2m_tokens`
`118`	`118`	`*/`
`119`	`119`	`function isM2MTokenResponse(payload: unknown): payload is { m2m_tokens: unknown[]; total_count: number } {`
`120`	`120`	`if (!payload \|\| typeof payload !== 'object' \|\| !('m2m_tokens' in payload)) {`