feat(clerk-js): Send force_origin on skipCache token requests (#8106)

Author: nikosdouvlis

.changeset/session-minter-force-origin.md

@@ -0,0 +1,5 @@
+---
+'@clerk/clerk-js': patch
+---
+
+Send `force_origin=true` body param on `/tokens` requests when `skipCache` is true, so FAPI Proxy routes to origin instead of Session Minter.

integration/tests/resiliency.test.ts

@@ -558,8 +558,47 @@ testAgainstRunningApps({ withEnv: [appConfigs.envs.withEmailCodes] })('resilienc
       const lastBody = new URLSearchParams(tokenRequestBodies[tokenRequestBodies.length - 1]);
       expect(lastBody.has('token')).toBe(sessionMinterEnabled);
 
+      // skipCache: true should send force_origin=true in the POST body when sessionMinter is enabled.
+      // Session.ts sets forceOrigin: 'true' which fapiClient serializes to force_origin=true
+      expect(lastBody.has('force_origin')).toBe(sessionMinterEnabled);
+
       // User should still be signed in after refresh
       await u.po.expect.toBeSignedIn();
     });
+
+    test('token refresh without skipCache does not send force_origin', async ({ page, context }) => {
+      const u = createTestUtils({ app, page, context });
+
+      // Sign in
+      await u.po.signIn.goTo();
+      await u.po.signIn.signInWithEmailAndInstantPassword({ email: fakeUser.email, password: fakeUser.password });
+      await u.po.expect.toBeSignedIn();
+
+      // Track token request bodies
+      const tokenRequestBodies: string[] = [];
+      await context.route('**/v1/client/sessions/*/tokens*', async route => {
+        const postData = route.request().postData();
+        if (postData) {
+          tokenRequestBodies.push(postData);
+        }
+        await route.continue();
+      });
+
+      // Force a fresh token fetch without skipCache
+      const token = await page.evaluate(async () => {
+        const clerk = (window as any).Clerk;
+        await clerk.session?.clearCache();
+        return await clerk.session?.getToken();
+      });
+
+      expect(token).toBeTruthy();
+
+      // Without skipCache, force_origin should NOT be present in the POST body
+      expect(tokenRequestBodies.length).toBeGreaterThanOrEqual(1);
+      const lastBody = new URLSearchParams(tokenRequestBodies[tokenRequestBodies.length - 1]);
+      expect(lastBody.has('force_origin')).toBe(false);
+
+      await u.po.expect.toBeSignedIn();
+    });
   });
 });

packages/clerk-js/src/core/resources/Session.ts

@@ -489,6 +489,7 @@ export class Session extends BaseResource implements SessionResource {
       : {
           organizationId: organizationId ?? null,
           ...(sessionMinterEnabled && this.lastActiveToken ? { token: this.lastActiveToken.getRawString() } : {}),
+          ...(sessionMinterEnabled && skipCache ? { forceOrigin: 'true' } : {}),
         };
 
     if (sessionMinterEnabled) {

packages/clerk-js/src/core/resources/__tests__/Session.test.ts

@@ -1698,6 +1698,108 @@ describe('Session', () => {
     });
   });
 
+  describe('sends force_origin in /tokens request body when skipCache is true', () => {
+    let dispatchSpy: ReturnType<typeof vi.spyOn>;
+    let fetchSpy: ReturnType<typeof vi.spyOn>;
+
+    beforeEach(() => {
+      dispatchSpy = vi.spyOn(eventBus, 'emit');
+      fetchSpy = vi.spyOn(BaseResource, '_fetch' as any);
+      BaseResource.clerk = clerkMock({
+        __internal_environment: {
+          authConfig: { sessionMinter: true },
+        },
+      }) as any;
+    });
+
+    afterEach(() => {
+      dispatchSpy?.mockRestore();
+      fetchSpy?.mockRestore();
+      BaseResource.clerk = null as any;
+    });
+
+    it('includes forceOrigin in body when skipCache is true', async () => {
+      const session = new Session({
+        status: 'active',
+        id: 'session_1',
+        object: 'session',
+        user: createUser({}),
+        last_active_organization_id: null,
+        last_active_token: { object: 'token', jwt: mockJwt },
+        actor: null,
+        created_at: new Date().getTime(),
+        updated_at: new Date().getTime(),
+      } as SessionJSON);
+
+      SessionTokenCache.clear();
+
+      fetchSpy.mockResolvedValueOnce({ object: 'token', jwt: mockJwt });
+
+      await session.getToken({ skipCache: true });
+
+      expect(fetchSpy).toHaveBeenCalledTimes(1);
+      expect(fetchSpy.mock.calls[0][0]).toMatchObject({
+        path: '/client/sessions/session_1/tokens',
+        method: 'POST',
+        body: expect.objectContaining({ forceOrigin: 'true' }),
+        search: { debug: 'skip_cache' },
+      });
+      expect(fetchSpy.mock.calls[0][0].body).not.toHaveProperty('debug');
+    });
+
+    it('does not include forceOrigin in body when skipCache is false or undefined', async () => {
+      const session = new Session({
+        status: 'active',
+        id: 'session_1',
+        object: 'session',
+        user: createUser({}),
+        last_active_organization_id: null,
+        last_active_token: { object: 'token', jwt: mockJwt },
+        actor: null,
+        created_at: new Date().getTime(),
+        updated_at: new Date().getTime(),
+      } as SessionJSON);
+
+      SessionTokenCache.clear();
+
+      fetchSpy.mockResolvedValueOnce({ object: 'token', jwt: mockJwt });
+
+      await session.getToken();
+
+      expect(fetchSpy).toHaveBeenCalledTimes(1);
+      expect(fetchSpy.mock.calls[0][0].body).not.toHaveProperty('forceOrigin');
+    });
+
+    it('does not include forceOrigin when sessionMinter is false even with skipCache true', async () => {
+      BaseResource.clerk = clerkMock({
+        __internal_environment: {
+          authConfig: { sessionMinter: false },
+        },
+      }) as any;
+
+      const session = new Session({
+        status: 'active',
+        id: 'session_1',
+        object: 'session',
+        user: createUser({}),
+        last_active_organization_id: null,
+        last_active_token: { object: 'token', jwt: mockJwt },
+        actor: null,
+        created_at: new Date().getTime(),
+        updated_at: new Date().getTime(),
+      } as SessionJSON);
+
+      SessionTokenCache.clear();
+
+      fetchSpy.mockResolvedValueOnce({ object: 'token', jwt: mockJwt });
+
+      await session.getToken({ skipCache: true });
+
+      expect(fetchSpy).toHaveBeenCalledTimes(1);
+      expect(fetchSpy.mock.calls[0][0].body).not.toHaveProperty('forceOrigin');
+    });
+  });
+
   describe('origin outage mode fallback', () => {
     let dispatchSpy: ReturnType<typeof vi.spyOn>;
     let fetchSpy: ReturnType<typeof vi.spyOn>;

packages/clerk-js/src/core/resources/__tests__/Token.test.ts

@@ -152,6 +152,20 @@ describe('Token', () => {
       const [url] = (global.fetch as Mock).mock.calls[0];
       expect(url.toString()).not.toContain('debug=skip_cache');
     });
+
+    it('includes force_origin=true in POST body when provided', async () => {
+      mockFetch(true, 200, {
+        object: 'token',
+        jwt: mockJwt,
+      });
+      BaseResource.clerk = { getFapiClient: () => createFapiClient(baseFapiClientOptions) } as any;
+
+      await Token.create('/path/to/tokens', { forceOrigin: 'true' });
+
+      const [url, options] = (global.fetch as Mock).mock.calls[0];
+      expect(options.body).toContain('force_origin=true');
+      expect(url.toString()).not.toContain('force_origin');
+    });
   });
 
   describe('create with search parameters', () => {