fix(express): build per-middleware ClerkClient when apiUrl/apiVersion are set

The backend's createAuthenticateRequest factory pins apiUrl/apiVersion at
client construction time and overrides any runtime values. The Express
default ClerkClient singleton is built from env only, so passing apiUrl
or apiVersion to clerkMiddleware() was silently ignored on the default
path even after option-forwarding was generalized.

When the caller hasn't supplied a custom clerkClient but did pass apiUrl
or apiVersion, build a per-middleware ClerkClient with those values
instead of using the singleton.

Author: jacekradko

.changeset/express-forward-auth-options.md

@@ -3,3 +3,5 @@
 ---
 
 Forward all `AuthenticateRequestOptions` and `VerifyTokenOptions` passed to `clerkMiddleware()` through to the backend `authenticateRequest()` call. Previously only a hand-picked subset was forwarded, so options like `organizationSyncOptions`, `skipJwksCache`, and `headerType` were accepted by the TypeScript types but silently ignored at runtime — the same class of bug that caused `clockSkewInMs` to be dropped.
+
+Additionally, when `apiUrl` or `apiVersion` are passed to `clerkMiddleware()` and no custom `clerkClient` is supplied, the middleware now builds a per-middleware `ClerkClient` configured with those values instead of using the env-only default singleton. This is required because `@clerk/backend` pins `apiUrl`/`apiVersion` at client construction time and ignores runtime overrides on `authenticateRequest()`. Passing your own `clerkClient` continues to take precedence.

packages/express/src/__tests__/clerkMiddleware.test.ts

@@ -12,7 +12,19 @@ vi.mock('@clerk/backend/proxy', async () => {
   };
 });
 
-import { authenticateRequest } from '../authenticateRequest';
+const { mockCreateClerkClient } = vi.hoisted(() => ({
+  mockCreateClerkClient: vi.fn(),
+}));
+vi.mock('@clerk/backend', async () => {
+  const actual = (await vi.importActual('@clerk/backend')) as typeof import('@clerk/backend');
+  mockCreateClerkClient.mockImplementation(actual.createClerkClient);
+  return {
+    ...actual,
+    createClerkClient: mockCreateClerkClient,
+  };
+});
+
+import { authenticateAndDecorateRequest, authenticateRequest } from '../authenticateRequest';
 import { clerkMiddleware } from '../clerkMiddleware';
 import { getAuth } from '../getAuth';
 import { assertNoDebugHeaders, assertSignedOutDebugHeaders, runMiddleware, runMiddlewareOnPath } from './helpers';
@@ -203,6 +215,52 @@ describe('clerkMiddleware', () => {
     expect(forwarded).not.toHaveProperty('frontendApiProxy');
   });
 
+  describe('apiUrl/apiVersion default-client construction', () => {
+    beforeEach(() => {
+      mockCreateClerkClient.mockClear();
+    });
+
+    it('builds a per-middleware ClerkClient with apiUrl when no custom clerkClient is supplied', () => {
+      authenticateAndDecorateRequest({
+        apiUrl: 'https://api.example.test',
+        secretKey: 'sk_test_....',
+        publishableKey: 'pk_test_Y2xlcmsuZXhhbXBsZS5jb20k',
+      });
+
+      expect(mockCreateClerkClient).toHaveBeenCalledWith(
+        expect.objectContaining({ apiUrl: 'https://api.example.test' }),
+      );
+    });
+
+    it('builds a per-middleware ClerkClient with apiVersion when no custom clerkClient is supplied', () => {
+      authenticateAndDecorateRequest({
+        apiVersion: 'v2',
+        secretKey: 'sk_test_....',
+        publishableKey: 'pk_test_Y2xlcmsuZXhhbXBsZS5jb20k',
+      });
+
+      expect(mockCreateClerkClient).toHaveBeenCalledWith(expect.objectContaining({ apiVersion: 'v2' }));
+    });
+
+    it('does not call createClerkClient at construction when apiUrl/apiVersion are not set', () => {
+      authenticateAndDecorateRequest({ secretKey: 'sk_test_....' });
+
+      expect(mockCreateClerkClient).not.toHaveBeenCalled();
+    });
+
+    it('does not build a per-middleware client when the caller supplies their own clerkClient', () => {
+      const customClient = { authenticateRequest: vi.fn() } as any;
+
+      authenticateAndDecorateRequest({
+        apiUrl: 'https://api.example.test',
+        apiVersion: 'v2',
+        clerkClient: customClient,
+      });
+
+      expect(mockCreateClerkClient).not.toHaveBeenCalled();
+    });
+  });
+
   it('throws error if clerkMiddleware is not executed before getAuth', async () => {
     const customMiddleware: RequestHandler = (request, response, next) => {
       const auth = getAuth(request);

packages/express/src/authenticateRequest.ts

@@ -1,3 +1,4 @@
+import { createClerkClient } from '@clerk/backend';
 import type { RequestState } from '@clerk/backend/internal';
 import { AuthStatus, createClerkRequest } from '@clerk/backend/internal';
 import { clerkFrontendApiProxy, DEFAULT_PROXY_PATH, stripTrailingSlashes } from '@clerk/backend/proxy';
@@ -111,8 +112,27 @@ const absoluteProxyUrl = (relativeOrAbsoluteUrl: string, baseUrl: string): strin
   return new URL(relativeOrAbsoluteUrl, baseUrl).toString();
 };
 
+// `apiUrl` and `apiVersion` are pinned at client construction time inside
+// `@clerk/backend`'s `createAuthenticateRequest` factory (build-time values
+// override runtime ones). The default singleton in `./clerkClient` is built
+// from env only, so passing these via `clerkMiddleware()` would be silently
+// ignored. When the caller hasn't supplied their own `clerkClient` but did
+// pass `apiUrl`/`apiVersion`, build a per-middleware client with those values.
+const resolveDefaultClerkClient = (options: ClerkMiddlewareOptions) => {
+  if (!options.apiUrl && !options.apiVersion) {
+    return defaultClerkClient;
+  }
+  const env = { ...loadApiEnv(), ...loadClientEnv() };
+  return createClerkClient({
+    ...env,
+    ...(options.apiUrl ? { apiUrl: options.apiUrl } : {}),
+    ...(options.apiVersion ? { apiVersion: options.apiVersion } : {}),
+    userAgent: `${PACKAGE_NAME}@${PACKAGE_VERSION}`,
+  });
+};
+
 export const authenticateAndDecorateRequest = (options: ClerkMiddlewareOptions = {}): RequestHandler => {
-  const clerkClient = options.clerkClient || defaultClerkClient;
+  const clerkClient = options.clerkClient || resolveDefaultClerkClient(options);
 
   // Extract proxy configuration
   const frontendApiProxy = options.frontendApiProxy;