From a3e19edcf158754d3b68d1b3b43b19c8197417fe Mon Sep 17 00:00:00 2001
From: wobsoriano <sorianorobertc@gmail.com>
Date: Tue, 1 Jul 2025 07:41:59 -0700
Subject: [PATCH 1/3] chore: use explicit configuration for skipping api
 version in url

---
 packages/backend/src/api/factory.ts | 30 ++++++++++++++---------------
 packages/backend/src/api/request.ts | 12 +++++++++++-
 2 files changed, 25 insertions(+), 17 deletions(-)

diff --git a/packages/backend/src/api/factory.ts b/packages/backend/src/api/factory.ts
index 876d57486f6..5283aafbc09 100644
--- a/packages/backend/src/api/factory.ts
+++ b/packages/backend/src/api/factory.ts
@@ -43,36 +43,34 @@ export function createBackendApiClient(options: CreateBackendApiOptions) {
     ),
     actorTokens: new ActorTokenAPI(request),
     allowlistIdentifiers: new AllowlistIdentifierAPI(request),
+    apiKeys: new APIKeysAPI(
+      buildRequest({
+        ...options,
+        skipApiVersionInUrl: true,
+      }),
+    ),
     betaFeatures: new BetaFeaturesAPI(request),
     blocklistIdentifiers: new BlocklistIdentifierAPI(request),
     clients: new ClientAPI(request),
     domains: new DomainAPI(request),
     emailAddresses: new EmailAddressAPI(request),
-    instance: new InstanceAPI(request),
-    invitations: new InvitationAPI(request),
-    // Using "/" instead of an actual version since they're bapi-proxy endpoints.
-    // bapi-proxy connects directly to C1 without URL versioning,
-    // while API versioning is handled through the Clerk-API-Version header.
-    machineTokens: new MachineTokensApi(
-      buildRequest({
-        ...options,
-        apiVersion: '/',
-      }),
-    ),
     idPOAuthAccessToken: new IdPOAuthAccessTokenApi(
       buildRequest({
         ...options,
-        apiVersion: '/',
+        skipApiVersionInUrl: true,
       }),
     ),
-    apiKeys: new APIKeysAPI(
+    instance: new InstanceAPI(request),
+    invitations: new InvitationAPI(request),
+    jwks: new JwksAPI(request),
+    jwtTemplates: new JwtTemplatesApi(request),
+    machineTokens: new MachineTokensApi(
       buildRequest({
         ...options,
-        apiVersion: '/',
+        skipApiVersionInUrl: true,
+        requireSecretKey: false,
       }),
     ),
-    jwks: new JwksAPI(request),
-    jwtTemplates: new JwtTemplatesApi(request),
     oauthApplications: new OAuthApplicationsApi(request),
     organizations: new OrganizationAPI(request),
     phoneNumbers: new PhoneNumberAPI(request),
diff --git a/packages/backend/src/api/request.ts b/packages/backend/src/api/request.ts
index 7b0c1d38b5c..59eacf4fd0d 100644
--- a/packages/backend/src/api/request.ts
+++ b/packages/backend/src/api/request.ts
@@ -57,6 +57,15 @@ type BuildRequestOptions = {
    * @default true
    */
   requireSecretKey?: boolean;
+  /**
+   * If true, omits the API version from the request URL path.
+   * This is required for bapi-proxy endpoints, which do not use versioning in the URL.
+   *
+   * Note: API versioning for these endpoints is instead handled via the `Clerk-API-Version` HTTP header.
+   *
+   * @default false
+   */
+  skipApiVersionInUrl?: boolean;
 };
 
 export function buildRequest(options: BuildRequestOptions) {
@@ -67,6 +76,7 @@ export function buildRequest(options: BuildRequestOptions) {
       apiUrl = API_URL,
       apiVersion = API_VERSION,
       userAgent = USER_AGENT,
+      skipApiVersionInUrl = false,
     } = options;
     const { path, method, queryParams, headerParams, bodyParams, formData } = requestOptions;
 
@@ -74,7 +84,7 @@ export function buildRequest(options: BuildRequestOptions) {
       assertValidSecretKey(secretKey);
     }
 
-    const url = joinPaths(apiUrl, apiVersion, path);
+    const url = skipApiVersionInUrl ? joinPaths(apiUrl, path) : joinPaths(apiUrl, apiVersion, path);
 
     // Build final URL with search parameters
     const finalUrl = new URL(url);

From d0f3a1388679343aa2360426560dc3636e00d59f Mon Sep 17 00:00:00 2001
From: wobsoriano <sorianorobertc@gmail.com>
Date: Tue, 1 Jul 2025 07:42:38 -0700
Subject: [PATCH 2/3] chore: remove secret key skip for m2m

---
 packages/backend/src/api/factory.ts | 1 -
 1 file changed, 1 deletion(-)

diff --git a/packages/backend/src/api/factory.ts b/packages/backend/src/api/factory.ts
index 5283aafbc09..ce83dac4328 100644
--- a/packages/backend/src/api/factory.ts
+++ b/packages/backend/src/api/factory.ts
@@ -68,7 +68,6 @@ export function createBackendApiClient(options: CreateBackendApiOptions) {
       buildRequest({
         ...options,
         skipApiVersionInUrl: true,
-        requireSecretKey: false,
       }),
     ),
     oauthApplications: new OAuthApplicationsApi(request),

From e8c9e9360a2fea4e3985c9c632bdac2df6304e53 Mon Sep 17 00:00:00 2001
From: Robert Soriano <sorianorobertc@gmail.com>
Date: Tue, 1 Jul 2025 07:49:36 -0700
Subject: [PATCH 3/3] chore: add changeset

---
 .changeset/tender-shrimps-admire.md | 5 +++++
 1 file changed, 5 insertions(+)
 create mode 100644 .changeset/tender-shrimps-admire.md

diff --git a/.changeset/tender-shrimps-admire.md b/.changeset/tender-shrimps-admire.md
new file mode 100644
index 00000000000..e1415759a43
--- /dev/null
+++ b/.changeset/tender-shrimps-admire.md
@@ -0,0 +1,5 @@
+---
+"@clerk/backend": patch
+---
+
+Use explicit config for api version handling in backend client request builder