chore(backend): Add explicit config for api version handling in url

.changeset/tender-shrimps-admire.md

@@ -0,0 +1,5 @@
+---
+"@clerk/backend": patch
+---
+
+Use explicit config for api version handling in backend client request builder

packages/backend/src/api/factory.ts

@@ -43,36 +43,33 @@ 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,
       }),
     ),
-    jwks: new JwksAPI(request),
-    jwtTemplates: new JwtTemplatesApi(request),
     oauthApplications: new OAuthApplicationsApi(request),
     organizations: new OrganizationAPI(request),
     phoneNumbers: new PhoneNumberAPI(request),

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,14 +76,15 @@ 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;
 
     if (requireSecretKey) {
       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);