fix(backend,clerk-js): treat undefined satelliteAutoSync as false

.changeset/fix-satellite-auto-sync-default.md

@@ -0,0 +1,6 @@
+---
+"@clerk/backend": patch
+"@clerk/clerk-js": patch
+---
+
+Fix `satelliteAutoSync` to default to `false` as documented. Previously, not passing the prop resulted in `undefined`, which was treated as `true` due to a strict equality check (`=== false`). This preserved Core 2 auto-sync behavior instead of the intended Core 3 default. The check is now `!== true`, so both `undefined` and `false` skip automatic satellite sync.

integration/tests/handshake.test.ts

@@ -529,7 +529,7 @@ test.describe('Client handshake @generic', () => {
  expect(res.status).toBe(200);
  });
 
- test('signed out satellite with sec-fetch-dest=document - prod', async () => {
+ test('signed out satellite with sec-fetch-dest=document skips handshake by default (satelliteAutoSync unset) - prod', async () => {
  const config = generateConfig({
  mode: 'live',
  });
@@ -543,13 +543,8 @@ test.describe('Client handshake @generic', () => {
  }),
  redirect: 'manual',
  });
- expect(res.status).toBe(307);
- const locationUrl = new URL(res.headers.get('location'));
- expect(locationUrl.origin + locationUrl.pathname).toBe('https://clerk.example.com/v1/client/handshake');
- expect(locationUrl.searchParams.get('redirect_url')).toBe(`${app.serverUrl}/`);
- expect(locationUrl.searchParams.get('__clerk_hs_reason')).toBe('satellite-needs-syncing');
- expect(locationUrl.searchParams.has('__clerk_api_version')).toBe(true);
- expect(locationUrl.searchParams.get('suffixed_cookies')).toBe('false');
+ // In Core 3, satelliteAutoSync defaults to false, so no handshake redirect
+ expect(res.status).toBe(200);
  });
 
  test('signed out satellite - dev', async () => {
@@ -628,7 +623,28 @@ test.describe('Client handshake @generic', () => {
  expect(res.status).toBe(200);
  });
 
- test('signed out satellite with satelliteAutoSync=true (default) triggers handshake - prod', async () => {
+ test('signed out satellite with satelliteAutoSync unset triggers handshake when __clerk_synced=false - prod', async () => {
+ const config = generateConfig({
+ mode: 'live',
+ });
+ const res = await fetch(app.serverUrl + '/?__clerk_synced=false', {
+ headers: new Headers({
+ 'X-Publishable-Key': config.pk,
+ 'X-Secret-Key': config.sk,
+ 'X-Satellite': 'true',
+ 'X-Domain': 'example.com',
+ 'Sec-Fetch-Dest': 'document',
+ }),
+ redirect: 'manual',
+ });
+ // Even without satelliteAutoSync, __clerk_synced=false (post sign-in) should trigger handshake
+ expect(res.status).toBe(307);
+ const locationUrl = new URL(res.headers.get('location'));
+ expect(locationUrl.origin + locationUrl.pathname).toBe('https://clerk.example.com/v1/client/handshake');
+ expect(locationUrl.searchParams.get('__clerk_hs_reason')).toBe('satellite-needs-syncing');
+ });
+
+ test('signed out satellite with satelliteAutoSync=true (explicit opt-in) triggers handshake - prod', async () => {
  const config = generateConfig({
  mode: 'live',
  });
@@ -643,7 +659,7 @@ test.describe('Client handshake @generic', () => {
  }),
  redirect: 'manual',
  });
- // Should redirect to handshake with default/true satelliteAutoSync
+ // Should redirect to handshake when satelliteAutoSync is explicitly true
  expect(res.status).toBe(307);
  const locationUrl = new URL(res.headers.get('location'));
  expect(locationUrl.origin + locationUrl.pathname).toBe('https://clerk.example.com/v1/client/handshake');

packages/backend/src/tokens/__tests__/request.test.ts

@@ -651,7 +651,7 @@ describe('tokens.authenticateRequest(options)', () => {
  expect(requestState).toBeSignedOutToAuth();
  });
 
- test('cookieToken: returns handshake when clientUat is missing or equals to 0 and is satellite and not is synced [11y]', async () => {
+ test('cookieToken: returns handshake when clientUat is missing or equals to 0 and is satellite with satelliteAutoSync=true and not is synced [11y]', async () => {
  server.use(
  http.get('https://api.clerk.test/v1/jwks', () => {
  return HttpResponse.json(mockJwks);
@@ -671,6 +671,7 @@ describe('tokens.authenticateRequest(options)', () => {
  isSatellite: true,
  signInUrl: 'https://primary.dev/sign-in',
  domain: 'satellite.dev',
+ satelliteAutoSync: true,
  }),
  );
 
@@ -684,7 +685,7 @@ describe('tokens.authenticateRequest(options)', () => {
  expect(requestState.toAuth()).toBeNull();
  });
 
- test('cookieToken: redirects to signInUrl when is satellite dev and not synced', async () => {
+ test('cookieToken: redirects to signInUrl when is satellite dev with satelliteAutoSync=true and not synced', async () => {
  server.use(
  http.get('https://api.clerk.test/v1/jwks', () => {
  return HttpResponse.json(mockJwks);
@@ -705,6 +706,7 @@ describe('tokens.authenticateRequest(options)', () => {
  isSatellite: true,
  signInUrl: 'https://primary.dev/sign-in',
  domain: 'satellite.dev',
+ satelliteAutoSync: true,
  }),
  );
 
@@ -873,6 +875,114 @@ describe('tokens.authenticateRequest(options)', () => {
  expect(requestState.toAuth()).toBeSignedOutToAuth();
  });
 
+ test('cookieToken: returns signed out without handshake when satelliteAutoSync is not set (defaults to false) and no cookies - prod', async () => {
+ const requestState = await authenticateRequest(
+ mockRequestWithCookies(
+ { ...defaultHeaders, 'sec-fetch-dest': 'document' },
+ { __client_uat: '0' },
+ `http://satellite.example/path`,
+ ),
+ mockOptions({
+ secretKey: 'deadbeef',
+ publishableKey: PK_LIVE,
+ signInUrl: 'https://primary.example/sign-in',
+ isSatellite: true,
+ domain: 'satellite.example',
+ }),
+ );
+
+ expect(requestState).toBeSignedOut({
+ reason: AuthErrorReason.SessionTokenAndUATMissing,
+ isSatellite: true,
+ domain: 'satellite.example',
+ signInUrl: 'https://primary.example/sign-in',
+ });
+ expect(requestState.toAuth()).toBeSignedOutToAuth();
+ expect(requestState.headers.get('location')).toBeNull();
+ });
+
+ test('cookieToken: returns signed out without handshake when satelliteAutoSync is not set (defaults to false) and no cookies - dev', async () => {
+ const requestState = await authenticateRequest(
+ mockRequestWithCookies(
+ { ...defaultHeaders, 'sec-fetch-dest': 'document' },
+ {
+ __client_uat: '0',
+ __clerk_db_jwt: mockJwt,
+ },
+ ),
+ mockOptions({
+ secretKey: 'sk_test_deadbeef',
+ publishableKey: PK_TEST,
+ isSatellite: true,
+ signInUrl: 'https://primary.dev/sign-in',
+ domain: 'satellite.dev',
+ }),
+ );
+
+ expect(requestState).toBeSignedOut({
+ reason: AuthErrorReason.SessionTokenAndUATMissing,
+ isSatellite: true,
+ domain: 'satellite.dev',
+ signInUrl: 'https://primary.dev/sign-in',
+ });
+ expect(requestState.toAuth()).toBeSignedOutToAuth();
+ expect(requestState.headers.get('location')).toBeNull();
+ });
+
+ test('cookieToken: triggers handshake when satelliteAutoSync is not set but __clerk_synced=false is present - prod', async () => {
+ const requestState = await authenticateRequest(
+ mockRequestWithCookies(
+ { ...defaultHeaders, 'sec-fetch-dest': 'document' },
+ { __client_uat: '0' },
+ `http://satellite.example/path?__clerk_synced=false`,
+ ),
+ mockOptions({
+ secretKey: 'deadbeef',
+ publishableKey: PK_LIVE,
+ signInUrl: 'https://primary.example/sign-in',
+ isSatellite: true,
+ domain: 'satellite.example',
+ }),
+ );
+
+ expect(requestState).toMatchHandshake({
+ reason: AuthErrorReason.SatelliteCookieNeedsSyncing,
+ isSatellite: true,
+ domain: 'satellite.example',
+ signInUrl: 'https://primary.example/sign-in',
+ });
+ });
+
+ test('cookieToken: triggers handshake when satelliteAutoSync is not set but __clerk_synced=false is present - dev', async () => {
+ const requestState = await authenticateRequest(
+ mockRequestWithCookies(
+ { ...defaultHeaders, 'sec-fetch-dest': 'document' },
+ {
+ __client_uat: '0',
+ __clerk_db_jwt: mockJwt,
+ },
+ `http://satellite.dev/path?__clerk_synced=false`,
+ ),
+ mockOptions({
+ secretKey: 'sk_test_deadbeef',
+ publishableKey: PK_TEST,
+ signInUrl: 'https://primary.dev/sign-in',
+ isSatellite: true,
+ domain: 'satellite.dev',
+ }),
+ );
+
+ expect(requestState).toMatchHandshake({
+ reason: AuthErrorReason.SatelliteCookieNeedsSyncing,
+ isSatellite: true,
+ domain: 'satellite.dev',
+ signInUrl: 'https://primary.dev/sign-in',
+ });
+ expect(requestState.headers.get('location')).toEqual(
+ `https://primary.dev/sign-in?__clerk_redirect_url=http%3A%2F%2Fexample.com%2Fpath%3F__clerk_synced%3Dfalse`,
+ );
+ });
+
  test('cookieToken: returns handshake when app is not satellite and responds to syncing on dev instances[12y]', async () => {
  const sp = new URLSearchParams();
  sp.set('__clerk_redirect_url', 'http://localhost:3000');

packages/backend/src/tokens/request.ts

@@ -484,7 +484,7 @@ export const authenticateRequest: AuthenticateRequest = (async (
  * - 'false' (NeedsSync): Trigger sync - satellite returning from primary sign-in
  * - 'true' (Completed): Sync done - prevents re-sync loop
  *
- * With satelliteAutoSync=false:
+ * With satelliteAutoSync=false or unset (Core 3 default):
  * - Skip handshake on first visit if no cookies exist (return signedOut immediately)
  * - Trigger handshake when __clerk_synced=false is present (post sign-in redirect)
  * - Allow normal token verification flow when cookies exist (enables refresh)
@@ -499,8 +499,8 @@ export const authenticateRequest: AuthenticateRequest = (async (
  const hasCookies = hasSessionToken || hasActiveClient;
 
  // Determine if we should skip handshake for satellites with no cookies
- // satelliteAutoSync defaults to true, so we only skip when explicitly set to false
- const shouldSkipSatelliteHandshake = authenticateContext.satelliteAutoSync === false && !hasCookies && !needsSync;
+ // satelliteAutoSync defaults to false (Core 3), so we skip unless explicitly set to true
+ const shouldSkipSatelliteHandshake = authenticateContext.satelliteAutoSync !== true && !hasCookies && !needsSync;
 
  if (authenticateContext.instanceType === 'production' && isRequestEligibleForMultiDomainSync && !syncCompleted) {
  // With satelliteAutoSync=false: skip handshake if no cookies and no sync trigger

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

@@ -2386,6 +2386,7 @@ describe('Clerk singleton', () => {
  describe('Clerk().isSatellite and Clerk().domain getters', () => {
  beforeEach(() => {
  mockClientFetch.mockReset();
+ mockClientFetch.mockReturnValue(Promise.resolve({ signedInSessions: [] }));
  mockEnvironmentFetch.mockReturnValue(
  Promise.resolve({
  authConfig: {},

packages/clerk-js/src/core/auth/AuthCookieService.ts

@@ -111,7 +111,7 @@ export class AuthCookieService {
  if (!this.clerk.loaded) {
  return this.clientUat.get() <= 0;
  }
- return !!this.clerk.user;
+ return !this.clerk.user;
  }
 
  public async handleUnauthenticatedDevBrowser() {

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

@@ -2845,10 +2845,9 @@ export class Clerk implements ClerkInterface {
  return true;
  }
 
- // Check if satelliteAutoSync is disabled - if so, skip automatic sync
- // unless explicitly triggered via __clerk_synced=false
- if (this.#options.satelliteAutoSync === false) {
- // Skip automatic sync when satelliteAutoSync is false
+ // Check if satelliteAutoSync is enabled - only auto-sync when explicitly opted in
+ // In Core 3, satelliteAutoSync defaults to false (undefined is treated as false)
+ if (this.#options.satelliteAutoSync !== true) {
  return false;
  }
 

.changeset/fix-satellite-auto-sync-default.md

@@ -0,0 +1,6 @@
+---
+"@clerk/backend": patch
+"@clerk/clerk-js": patch
+---
+
+Fix `satelliteAutoSync` to default to `false` as documented. Previously, not passing the prop resulted in `undefined`, which was treated as `true` due to a strict equality check (`=== false`). This preserved Core 2 auto-sync behavior instead of the intended Core 3 default. The check is now `!== true`, so both `undefined` and `false` skip automatic satellite sync.

integration/tests/handshake.test.ts

@@ -529,7 +529,7 @@ test.describe('Client handshake @generic', () => {
  expect(res.status).toBe(200);
  });
 
- test('signed out satellite with sec-fetch-dest=document - prod', async () => {
+ test('signed out satellite with sec-fetch-dest=document skips handshake by default (satelliteAutoSync unset) - prod', async () => {
  const config = generateConfig({
  mode: 'live',
  });
@@ -543,13 +543,8 @@ test.describe('Client handshake @generic', () => {
  }),
  redirect: 'manual',
  });
- expect(res.status).toBe(307);
- const locationUrl = new URL(res.headers.get('location'));
- expect(locationUrl.origin + locationUrl.pathname).toBe('https://clerk.example.com/v1/client/handshake');
- expect(locationUrl.searchParams.get('redirect_url')).toBe(`${app.serverUrl}/`);
- expect(locationUrl.searchParams.get('__clerk_hs_reason')).toBe('satellite-needs-syncing');
- expect(locationUrl.searchParams.has('__clerk_api_version')).toBe(true);
- expect(locationUrl.searchParams.get('suffixed_cookies')).toBe('false');
+ // In Core 3, satelliteAutoSync defaults to false, so no handshake redirect
+ expect(res.status).toBe(200);
  });
 
  test('signed out satellite - dev', async () => {
@@ -628,7 +623,28 @@ test.describe('Client handshake @generic', () => {
  expect(res.status).toBe(200);
  });
 
- test('signed out satellite with satelliteAutoSync=true (default) triggers handshake - prod', async () => {
+ test('signed out satellite with satelliteAutoSync unset triggers handshake when __clerk_synced=false - prod', async () => {
+ const config = generateConfig({
+ mode: 'live',
+ });
+ const res = await fetch(app.serverUrl + '/?__clerk_synced=false', {
+ headers: new Headers({
+ 'X-Publishable-Key': config.pk,
+ 'X-Secret-Key': config.sk,
+ 'X-Satellite': 'true',
+ 'X-Domain': 'example.com',
+ 'Sec-Fetch-Dest': 'document',
+ }),
+ redirect: 'manual',
+ });
+ // Even without satelliteAutoSync, __clerk_synced=false (post sign-in) should trigger handshake
+ expect(res.status).toBe(307);
+ const locationUrl = new URL(res.headers.get('location'));
+ expect(locationUrl.origin + locationUrl.pathname).toBe('https://clerk.example.com/v1/client/handshake');
+ expect(locationUrl.searchParams.get('__clerk_hs_reason')).toBe('satellite-needs-syncing');
+ });
+
+ test('signed out satellite with satelliteAutoSync=true (explicit opt-in) triggers handshake - prod', async () => {
  const config = generateConfig({
  mode: 'live',
  });
@@ -643,7 +659,7 @@ test.describe('Client handshake @generic', () => {
  }),
  redirect: 'manual',
  });
- // Should redirect to handshake with default/true satelliteAutoSync
+ // Should redirect to handshake when satelliteAutoSync is explicitly true
  expect(res.status).toBe(307);
  const locationUrl = new URL(res.headers.get('location'));
  expect(locationUrl.origin + locationUrl.pathname).toBe('https://clerk.example.com/v1/client/handshake');

packages/backend/src/tokens/__tests__/request.test.ts

@@ -651,7 +651,7 @@ describe('tokens.authenticateRequest(options)', () => {
  expect(requestState).toBeSignedOutToAuth();
  });
 
- test('cookieToken: returns handshake when clientUat is missing or equals to 0 and is satellite and not is synced [11y]', async () => {
+ test('cookieToken: returns handshake when clientUat is missing or equals to 0 and is satellite with satelliteAutoSync=true and not is synced [11y]', async () => {
  server.use(
  http.get('https://api.clerk.test/v1/jwks', () => {
  return HttpResponse.json(mockJwks);
@@ -671,6 +671,7 @@ describe('tokens.authenticateRequest(options)', () => {
  isSatellite: true,
  signInUrl: 'https://primary.dev/sign-in',
  domain: 'satellite.dev',
+ satelliteAutoSync: true,
  }),
  );
 
@@ -684,7 +685,7 @@ describe('tokens.authenticateRequest(options)', () => {
  expect(requestState.toAuth()).toBeNull();
  });
 
- test('cookieToken: redirects to signInUrl when is satellite dev and not synced', async () => {
+ test('cookieToken: redirects to signInUrl when is satellite dev with satelliteAutoSync=true and not synced', async () => {
  server.use(
  http.get('https://api.clerk.test/v1/jwks', () => {
  return HttpResponse.json(mockJwks);
@@ -705,6 +706,7 @@ describe('tokens.authenticateRequest(options)', () => {
  isSatellite: true,
  signInUrl: 'https://primary.dev/sign-in',
  domain: 'satellite.dev',
+ satelliteAutoSync: true,
  }),
  );
 
@@ -873,6 +875,114 @@ describe('tokens.authenticateRequest(options)', () => {
  expect(requestState.toAuth()).toBeSignedOutToAuth();
  });
 
+ test('cookieToken: returns signed out without handshake when satelliteAutoSync is not set (defaults to false) and no cookies - prod', async () => {
+ const requestState = await authenticateRequest(
+ mockRequestWithCookies(
+ { ...defaultHeaders, 'sec-fetch-dest': 'document' },
+ { __client_uat: '0' },
+ `http://satellite.example/path`,
+ ),
+ mockOptions({
+ secretKey: 'deadbeef',
+ publishableKey: PK_LIVE,
+ signInUrl: 'https://primary.example/sign-in',
+ isSatellite: true,
+ domain: 'satellite.example',
+ }),
+ );
+
+ expect(requestState).toBeSignedOut({
+ reason: AuthErrorReason.SessionTokenAndUATMissing,
+ isSatellite: true,
+ domain: 'satellite.example',
+ signInUrl: 'https://primary.example/sign-in',
+ });
+ expect(requestState.toAuth()).toBeSignedOutToAuth();
+ expect(requestState.headers.get('location')).toBeNull();
+ });
+
+ test('cookieToken: returns signed out without handshake when satelliteAutoSync is not set (defaults to false) and no cookies - dev', async () => {
+ const requestState = await authenticateRequest(
+ mockRequestWithCookies(
+ { ...defaultHeaders, 'sec-fetch-dest': 'document' },
+ {
+ __client_uat: '0',
+ __clerk_db_jwt: mockJwt,
+ },
+ ),
+ mockOptions({
+ secretKey: 'sk_test_deadbeef',
+ publishableKey: PK_TEST,
+ isSatellite: true,
+ signInUrl: 'https://primary.dev/sign-in',
+ domain: 'satellite.dev',
+ }),
+ );
+
+ expect(requestState).toBeSignedOut({
+ reason: AuthErrorReason.SessionTokenAndUATMissing,
+ isSatellite: true,
+ domain: 'satellite.dev',
+ signInUrl: 'https://primary.dev/sign-in',
+ });
+ expect(requestState.toAuth()).toBeSignedOutToAuth();
+ expect(requestState.headers.get('location')).toBeNull();
+ });
+
+ test('cookieToken: triggers handshake when satelliteAutoSync is not set but __clerk_synced=false is present - prod', async () => {
+ const requestState = await authenticateRequest(
+ mockRequestWithCookies(
+ { ...defaultHeaders, 'sec-fetch-dest': 'document' },
+ { __client_uat: '0' },
+ `http://satellite.example/path?__clerk_synced=false`,
+ ),
+ mockOptions({
+ secretKey: 'deadbeef',
+ publishableKey: PK_LIVE,
+ signInUrl: 'https://primary.example/sign-in',
+ isSatellite: true,
+ domain: 'satellite.example',
+ }),
+ );
+
+ expect(requestState).toMatchHandshake({
+ reason: AuthErrorReason.SatelliteCookieNeedsSyncing,
+ isSatellite: true,
+ domain: 'satellite.example',
+ signInUrl: 'https://primary.example/sign-in',
+ });
+ });
+
+ test('cookieToken: triggers handshake when satelliteAutoSync is not set but __clerk_synced=false is present - dev', async () => {
+ const requestState = await authenticateRequest(
+ mockRequestWithCookies(
+ { ...defaultHeaders, 'sec-fetch-dest': 'document' },
+ {
+ __client_uat: '0',
+ __clerk_db_jwt: mockJwt,
+ },
+ `http://satellite.dev/path?__clerk_synced=false`,
+ ),
+ mockOptions({
+ secretKey: 'sk_test_deadbeef',
+ publishableKey: PK_TEST,
+ signInUrl: 'https://primary.dev/sign-in',
+ isSatellite: true,
+ domain: 'satellite.dev',
+ }),
+ );
+
+ expect(requestState).toMatchHandshake({
+ reason: AuthErrorReason.SatelliteCookieNeedsSyncing,
+ isSatellite: true,
+ domain: 'satellite.dev',
+ signInUrl: 'https://primary.dev/sign-in',
+ });
+ expect(requestState.headers.get('location')).toEqual(
+ `https://primary.dev/sign-in?__clerk_redirect_url=http%3A%2F%2Fexample.com%2Fpath%3F__clerk_synced%3Dfalse`,
+ );
+ });
+
  test('cookieToken: returns handshake when app is not satellite and responds to syncing on dev instances[12y]', async () => {
  const sp = new URLSearchParams();
  sp.set('__clerk_redirect_url', 'http://localhost:3000');

packages/backend/src/tokens/request.ts

@@ -484,7 +484,7 @@ export const authenticateRequest: AuthenticateRequest = (async (
  * - 'false' (NeedsSync): Trigger sync - satellite returning from primary sign-in
  * - 'true' (Completed): Sync done - prevents re-sync loop
  *
- * With satelliteAutoSync=false:
+ * With satelliteAutoSync=false or unset (Core 3 default):
  * - Skip handshake on first visit if no cookies exist (return signedOut immediately)
  * - Trigger handshake when __clerk_synced=false is present (post sign-in redirect)
  * - Allow normal token verification flow when cookies exist (enables refresh)
@@ -499,8 +499,8 @@ export const authenticateRequest: AuthenticateRequest = (async (
  const hasCookies = hasSessionToken || hasActiveClient;
 
  // Determine if we should skip handshake for satellites with no cookies
- // satelliteAutoSync defaults to true, so we only skip when explicitly set to false
- const shouldSkipSatelliteHandshake = authenticateContext.satelliteAutoSync === false && !hasCookies && !needsSync;
+ // satelliteAutoSync defaults to false (Core 3), so we skip unless explicitly set to true
+ const shouldSkipSatelliteHandshake = authenticateContext.satelliteAutoSync !== true && !hasCookies && !needsSync;
 
  if (authenticateContext.instanceType === 'production' && isRequestEligibleForMultiDomainSync && !syncCompleted) {
  // With satelliteAutoSync=false: skip handshake if no cookies and no sync trigger

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

@@ -2386,6 +2386,7 @@ describe('Clerk singleton', () => {
  describe('Clerk().isSatellite and Clerk().domain getters', () => {
  beforeEach(() => {
  mockClientFetch.mockReset();
+ mockClientFetch.mockReturnValue(Promise.resolve({ signedInSessions: [] }));
  mockEnvironmentFetch.mockReturnValue(
  Promise.resolve({
  authConfig: {},

packages/clerk-js/src/core/auth/AuthCookieService.ts

@@ -111,7 +111,7 @@ export class AuthCookieService {
  if (!this.clerk.loaded) {
  return this.clientUat.get() <= 0;
  }
- return !!this.clerk.user;
+ return !this.clerk.user;
  }
 
  public async handleUnauthenticatedDevBrowser() {

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

@@ -2845,10 +2845,9 @@ export class Clerk implements ClerkInterface {
  return true;
  }
 
- // Check if satelliteAutoSync is disabled - if so, skip automatic sync
- // unless explicitly triggered via __clerk_synced=false
- if (this.#options.satelliteAutoSync === false) {
- // Skip automatic sync when satelliteAutoSync is false
+ // Check if satelliteAutoSync is enabled - only auto-sync when explicitly opted in
+ // In Core 3, satelliteAutoSync defaults to false (undefined is treated as false)
+ if (this.#options.satelliteAutoSync !== true) {
  return false;
  }
 

.changeset/fix-satellite-auto-sync-default.md

@@ -0,0 +1,6 @@
+---
+"@clerk/backend": patch
+"@clerk/clerk-js": patch
+---
+
+Fix `satelliteAutoSync` to default to `false` as documented. Previously, not passing the prop resulted in `undefined`, which was treated as `true` due to a strict equality check (`=== false`). This preserved Core 2 auto-sync behavior instead of the intended Core 3 default. The check is now `!== true`, so both `undefined` and `false` skip automatic satellite sync.

integration/tests/handshake.test.ts

@@ -529,7 +529,7 @@ test.describe('Client handshake @generic', () => {
  expect(res.status).toBe(200);
  });
 
- test('signed out satellite with sec-fetch-dest=document - prod', async () => {
+ test('signed out satellite with sec-fetch-dest=document skips handshake by default (satelliteAutoSync unset) - prod', async () => {
  const config = generateConfig({
  mode: 'live',
  });
@@ -543,13 +543,8 @@ test.describe('Client handshake @generic', () => {
  }),
  redirect: 'manual',
  });
- expect(res.status).toBe(307);
- const locationUrl = new URL(res.headers.get('location'));
- expect(locationUrl.origin + locationUrl.pathname).toBe('https://clerk.example.com/v1/client/handshake');
- expect(locationUrl.searchParams.get('redirect_url')).toBe(`${app.serverUrl}/`);
- expect(locationUrl.searchParams.get('__clerk_hs_reason')).toBe('satellite-needs-syncing');
- expect(locationUrl.searchParams.has('__clerk_api_version')).toBe(true);
- expect(locationUrl.searchParams.get('suffixed_cookies')).toBe('false');
+ // In Core 3, satelliteAutoSync defaults to false, so no handshake redirect
+ expect(res.status).toBe(200);
  });
 
  test('signed out satellite - dev', async () => {
@@ -628,7 +623,28 @@ test.describe('Client handshake @generic', () => {
  expect(res.status).toBe(200);
  });
 
- test('signed out satellite with satelliteAutoSync=true (default) triggers handshake - prod', async () => {
+ test('signed out satellite with satelliteAutoSync unset triggers handshake when __clerk_synced=false - prod', async () => {
+ const config = generateConfig({
+ mode: 'live',
+ });
+ const res = await fetch(app.serverUrl + '/?__clerk_synced=false', {
+ headers: new Headers({
+ 'X-Publishable-Key': config.pk,
+ 'X-Secret-Key': config.sk,
+ 'X-Satellite': 'true',
+ 'X-Domain': 'example.com',
+ 'Sec-Fetch-Dest': 'document',
+ }),
+ redirect: 'manual',
+ });
+ // Even without satelliteAutoSync, __clerk_synced=false (post sign-in) should trigger handshake
+ expect(res.status).toBe(307);
+ const locationUrl = new URL(res.headers.get('location'));
+ expect(locationUrl.origin + locationUrl.pathname).toBe('https://clerk.example.com/v1/client/handshake');
+ expect(locationUrl.searchParams.get('__clerk_hs_reason')).toBe('satellite-needs-syncing');
+ });
+
+ test('signed out satellite with satelliteAutoSync=true (explicit opt-in) triggers handshake - prod', async () => {
  const config = generateConfig({
  mode: 'live',
  });
@@ -643,7 +659,7 @@ test.describe('Client handshake @generic', () => {
  }),
  redirect: 'manual',
  });
- // Should redirect to handshake with default/true satelliteAutoSync
+ // Should redirect to handshake when satelliteAutoSync is explicitly true
  expect(res.status).toBe(307);
  const locationUrl = new URL(res.headers.get('location'));
  expect(locationUrl.origin + locationUrl.pathname).toBe('https://clerk.example.com/v1/client/handshake');

packages/backend/src/tokens/__tests__/request.test.ts

@@ -651,7 +651,7 @@ describe('tokens.authenticateRequest(options)', () => {
  expect(requestState).toBeSignedOutToAuth();
  });
 
- test('cookieToken: returns handshake when clientUat is missing or equals to 0 and is satellite and not is synced [11y]', async () => {
+ test('cookieToken: returns handshake when clientUat is missing or equals to 0 and is satellite with satelliteAutoSync=true and not is synced [11y]', async () => {
  server.use(
  http.get('https://api.clerk.test/v1/jwks', () => {
  return HttpResponse.json(mockJwks);
@@ -671,6 +671,7 @@ describe('tokens.authenticateRequest(options)', () => {
  isSatellite: true,
  signInUrl: 'https://primary.dev/sign-in',
  domain: 'satellite.dev',
+ satelliteAutoSync: true,
  }),
  );
 
@@ -684,7 +685,7 @@ describe('tokens.authenticateRequest(options)', () => {
  expect(requestState.toAuth()).toBeNull();
  });
 
- test('cookieToken: redirects to signInUrl when is satellite dev and not synced', async () => {
+ test('cookieToken: redirects to signInUrl when is satellite dev with satelliteAutoSync=true and not synced', async () => {
  server.use(
  http.get('https://api.clerk.test/v1/jwks', () => {
  return HttpResponse.json(mockJwks);
@@ -705,6 +706,7 @@ describe('tokens.authenticateRequest(options)', () => {
  isSatellite: true,
  signInUrl: 'https://primary.dev/sign-in',
  domain: 'satellite.dev',
+ satelliteAutoSync: true,
  }),
  );
 
@@ -873,6 +875,114 @@ describe('tokens.authenticateRequest(options)', () => {
  expect(requestState.toAuth()).toBeSignedOutToAuth();
  });
 
+ test('cookieToken: returns signed out without handshake when satelliteAutoSync is not set (defaults to false) and no cookies - prod', async () => {
+ const requestState = await authenticateRequest(
+ mockRequestWithCookies(
+ { ...defaultHeaders, 'sec-fetch-dest': 'document' },
+ { __client_uat: '0' },
+ `http://satellite.example/path`,
+ ),
+ mockOptions({
+ secretKey: 'deadbeef',
+ publishableKey: PK_LIVE,
+ signInUrl: 'https://primary.example/sign-in',
+ isSatellite: true,
+ domain: 'satellite.example',
+ }),
+ );
+
+ expect(requestState).toBeSignedOut({
+ reason: AuthErrorReason.SessionTokenAndUATMissing,
+ isSatellite: true,
+ domain: 'satellite.example',
+ signInUrl: 'https://primary.example/sign-in',
+ });
+ expect(requestState.toAuth()).toBeSignedOutToAuth();
+ expect(requestState.headers.get('location')).toBeNull();
+ });
+
+ test('cookieToken: returns signed out without handshake when satelliteAutoSync is not set (defaults to false) and no cookies - dev', async () => {
+ const requestState = await authenticateRequest(
+ mockRequestWithCookies(
+ { ...defaultHeaders, 'sec-fetch-dest': 'document' },
+ {
+ __client_uat: '0',
+ __clerk_db_jwt: mockJwt,
+ },
+ ),
+ mockOptions({
+ secretKey: 'sk_test_deadbeef',
+ publishableKey: PK_TEST,
+ isSatellite: true,
+ signInUrl: 'https://primary.dev/sign-in',
+ domain: 'satellite.dev',
+ }),
+ );
+
+ expect(requestState).toBeSignedOut({
+ reason: AuthErrorReason.SessionTokenAndUATMissing,
+ isSatellite: true,
+ domain: 'satellite.dev',
+ signInUrl: 'https://primary.dev/sign-in',
+ });
+ expect(requestState.toAuth()).toBeSignedOutToAuth();
+ expect(requestState.headers.get('location')).toBeNull();
+ });
+
+ test('cookieToken: triggers handshake when satelliteAutoSync is not set but __clerk_synced=false is present - prod', async () => {
+ const requestState = await authenticateRequest(
+ mockRequestWithCookies(
+ { ...defaultHeaders, 'sec-fetch-dest': 'document' },
+ { __client_uat: '0' },
+ `http://satellite.example/path?__clerk_synced=false`,
+ ),
+ mockOptions({
+ secretKey: 'deadbeef',
+ publishableKey: PK_LIVE,
+ signInUrl: 'https://primary.example/sign-in',
+ isSatellite: true,
+ domain: 'satellite.example',
+ }),
+ );
+
+ expect(requestState).toMatchHandshake({
+ reason: AuthErrorReason.SatelliteCookieNeedsSyncing,
+ isSatellite: true,
+ domain: 'satellite.example',
+ signInUrl: 'https://primary.example/sign-in',
+ });
+ });
+
+ test('cookieToken: triggers handshake when satelliteAutoSync is not set but __clerk_synced=false is present - dev', async () => {
+ const requestState = await authenticateRequest(
+ mockRequestWithCookies(
+ { ...defaultHeaders, 'sec-fetch-dest': 'document' },
+ {
+ __client_uat: '0',
+ __clerk_db_jwt: mockJwt,
+ },
+ `http://satellite.dev/path?__clerk_synced=false`,
+ ),
+ mockOptions({
+ secretKey: 'sk_test_deadbeef',
+ publishableKey: PK_TEST,
+ signInUrl: 'https://primary.dev/sign-in',
+ isSatellite: true,
+ domain: 'satellite.dev',
+ }),
+ );
+
+ expect(requestState).toMatchHandshake({
+ reason: AuthErrorReason.SatelliteCookieNeedsSyncing,
+ isSatellite: true,
+ domain: 'satellite.dev',
+ signInUrl: 'https://primary.dev/sign-in',
+ });
+ expect(requestState.headers.get('location')).toEqual(
+ `https://primary.dev/sign-in?__clerk_redirect_url=http%3A%2F%2Fexample.com%2Fpath%3F__clerk_synced%3Dfalse`,
+ );
+ });
+
  test('cookieToken: returns handshake when app is not satellite and responds to syncing on dev instances[12y]', async () => {
  const sp = new URLSearchParams();
  sp.set('__clerk_redirect_url', 'http://localhost:3000');

packages/backend/src/tokens/request.ts

@@ -484,7 +484,7 @@ export const authenticateRequest: AuthenticateRequest = (async (
  * - 'false' (NeedsSync): Trigger sync - satellite returning from primary sign-in
  * - 'true' (Completed): Sync done - prevents re-sync loop
  *
- * With satelliteAutoSync=false:
+ * With satelliteAutoSync=false or unset (Core 3 default):
  * - Skip handshake on first visit if no cookies exist (return signedOut immediately)
  * - Trigger handshake when __clerk_synced=false is present (post sign-in redirect)
  * - Allow normal token verification flow when cookies exist (enables refresh)
@@ -499,8 +499,8 @@ export const authenticateRequest: AuthenticateRequest = (async (
  const hasCookies = hasSessionToken || hasActiveClient;
 
  // Determine if we should skip handshake for satellites with no cookies
- // satelliteAutoSync defaults to true, so we only skip when explicitly set to false
- const shouldSkipSatelliteHandshake = authenticateContext.satelliteAutoSync === false && !hasCookies && !needsSync;
+ // satelliteAutoSync defaults to false (Core 3), so we skip unless explicitly set to true
+ const shouldSkipSatelliteHandshake = authenticateContext.satelliteAutoSync !== true && !hasCookies && !needsSync;
 
  if (authenticateContext.instanceType === 'production' && isRequestEligibleForMultiDomainSync && !syncCompleted) {
  // With satelliteAutoSync=false: skip handshake if no cookies and no sync trigger

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

@@ -2386,6 +2386,7 @@ describe('Clerk singleton', () => {
  describe('Clerk().isSatellite and Clerk().domain getters', () => {
  beforeEach(() => {
  mockClientFetch.mockReset();
+ mockClientFetch.mockReturnValue(Promise.resolve({ signedInSessions: [] }));
  mockEnvironmentFetch.mockReturnValue(
  Promise.resolve({
  authConfig: {},

packages/clerk-js/src/core/auth/AuthCookieService.ts

@@ -111,7 +111,7 @@ export class AuthCookieService {
  if (!this.clerk.loaded) {
  return this.clientUat.get() <= 0;
  }
- return !!this.clerk.user;
+ return !this.clerk.user;
  }
 
  public async handleUnauthenticatedDevBrowser() {

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

@@ -2845,10 +2845,9 @@ export class Clerk implements ClerkInterface {
  return true;
  }
 
- // Check if satelliteAutoSync is disabled - if so, skip automatic sync
- // unless explicitly triggered via __clerk_synced=false
- if (this.#options.satelliteAutoSync === false) {
- // Skip automatic sync when satelliteAutoSync is false
+ // Check if satelliteAutoSync is enabled - only auto-sync when explicitly opted in
+ // In Core 3, satelliteAutoSync defaults to false (undefined is treated as false)
+ if (this.#options.satelliteAutoSync !== true) {
  return false;
  }
 

.changeset/fix-satellite-auto-sync-default.md

@@ -0,0 +1,6 @@
+---
+"@clerk/backend": patch
+"@clerk/clerk-js": patch
+---
+
+Fix `satelliteAutoSync` to default to `false` as documented. Previously, not passing the prop resulted in `undefined`, which was treated as `true` due to a strict equality check (`=== false`). This preserved Core 2 auto-sync behavior instead of the intended Core 3 default. The check is now `!== true`, so both `undefined` and `false` skip automatic satellite sync.

integration/tests/handshake.test.ts

@@ -529,7 +529,7 @@ test.describe('Client handshake @generic', () => {
  expect(res.status).toBe(200);
  });
 
- test('signed out satellite with sec-fetch-dest=document - prod', async () => {
+ test('signed out satellite with sec-fetch-dest=document skips handshake by default (satelliteAutoSync unset) - prod', async () => {
  const config = generateConfig({
  mode: 'live',
  });
@@ -543,13 +543,8 @@ test.describe('Client handshake @generic', () => {
  }),
  redirect: 'manual',
  });
- expect(res.status).toBe(307);
- const locationUrl = new URL(res.headers.get('location'));
- expect(locationUrl.origin + locationUrl.pathname).toBe('https://clerk.example.com/v1/client/handshake');
- expect(locationUrl.searchParams.get('redirect_url')).toBe(`${app.serverUrl}/`);
- expect(locationUrl.searchParams.get('__clerk_hs_reason')).toBe('satellite-needs-syncing');
- expect(locationUrl.searchParams.has('__clerk_api_version')).toBe(true);
- expect(locationUrl.searchParams.get('suffixed_cookies')).toBe('false');
+ // In Core 3, satelliteAutoSync defaults to false, so no handshake redirect
+ expect(res.status).toBe(200);
  });
 
  test('signed out satellite - dev', async () => {
@@ -628,7 +623,28 @@ test.describe('Client handshake @generic', () => {
  expect(res.status).toBe(200);
  });
 
- test('signed out satellite with satelliteAutoSync=true (default) triggers handshake - prod', async () => {
+ test('signed out satellite with satelliteAutoSync unset triggers handshake when __clerk_synced=false - prod', async () => {
+ const config = generateConfig({
+ mode: 'live',
+ });
+ const res = await fetch(app.serverUrl + '/?__clerk_synced=false', {
+ headers: new Headers({
+ 'X-Publishable-Key': config.pk,
+ 'X-Secret-Key': config.sk,
+ 'X-Satellite': 'true',
+ 'X-Domain': 'example.com',
+ 'Sec-Fetch-Dest': 'document',
+ }),
+ redirect: 'manual',
+ });
+ // Even without satelliteAutoSync, __clerk_synced=false (post sign-in) should trigger handshake
+ expect(res.status).toBe(307);
+ const locationUrl = new URL(res.headers.get('location'));
+ expect(locationUrl.origin + locationUrl.pathname).toBe('https://clerk.example.com/v1/client/handshake');
+ expect(locationUrl.searchParams.get('__clerk_hs_reason')).toBe('satellite-needs-syncing');
+ });
+
+ test('signed out satellite with satelliteAutoSync=true (explicit opt-in) triggers handshake - prod', async () => {
  const config = generateConfig({
  mode: 'live',
  });
@@ -643,7 +659,7 @@ test.describe('Client handshake @generic', () => {
  }),
  redirect: 'manual',
  });
- // Should redirect to handshake with default/true satelliteAutoSync
+ // Should redirect to handshake when satelliteAutoSync is explicitly true
  expect(res.status).toBe(307);
  const locationUrl = new URL(res.headers.get('location'));
  expect(locationUrl.origin + locationUrl.pathname).toBe('https://clerk.example.com/v1/client/handshake');

packages/backend/src/tokens/__tests__/request.test.ts

@@ -651,7 +651,7 @@ describe('tokens.authenticateRequest(options)', () => {
  expect(requestState).toBeSignedOutToAuth();
  });
 
- test('cookieToken: returns handshake when clientUat is missing or equals to 0 and is satellite and not is synced [11y]', async () => {
+ test('cookieToken: returns handshake when clientUat is missing or equals to 0 and is satellite with satelliteAutoSync=true and not is synced [11y]', async () => {
  server.use(
  http.get('https://api.clerk.test/v1/jwks', () => {
  return HttpResponse.json(mockJwks);
@@ -671,6 +671,7 @@ describe('tokens.authenticateRequest(options)', () => {
  isSatellite: true,
  signInUrl: 'https://primary.dev/sign-in',
  domain: 'satellite.dev',
+ satelliteAutoSync: true,
  }),
  );
 
@@ -684,7 +685,7 @@ describe('tokens.authenticateRequest(options)', () => {
  expect(requestState.toAuth()).toBeNull();
  });
 
- test('cookieToken: redirects to signInUrl when is satellite dev and not synced', async () => {
+ test('cookieToken: redirects to signInUrl when is satellite dev with satelliteAutoSync=true and not synced', async () => {
  server.use(
  http.get('https://api.clerk.test/v1/jwks', () => {
  return HttpResponse.json(mockJwks);
@@ -705,6 +706,7 @@ describe('tokens.authenticateRequest(options)', () => {
  isSatellite: true,
  signInUrl: 'https://primary.dev/sign-in',
  domain: 'satellite.dev',
+ satelliteAutoSync: true,
  }),
  );
 
@@ -873,6 +875,114 @@ describe('tokens.authenticateRequest(options)', () => {
  expect(requestState.toAuth()).toBeSignedOutToAuth();
  });
 
+ test('cookieToken: returns signed out without handshake when satelliteAutoSync is not set (defaults to false) and no cookies - prod', async () => {
+ const requestState = await authenticateRequest(
+ mockRequestWithCookies(
+ { ...defaultHeaders, 'sec-fetch-dest': 'document' },
+ { __client_uat: '0' },
+ `http://satellite.example/path`,
+ ),
+ mockOptions({
+ secretKey: 'deadbeef',
+ publishableKey: PK_LIVE,
+ signInUrl: 'https://primary.example/sign-in',
+ isSatellite: true,
+ domain: 'satellite.example',
+ }),
+ );
+
+ expect(requestState).toBeSignedOut({
+ reason: AuthErrorReason.SessionTokenAndUATMissing,
+ isSatellite: true,
+ domain: 'satellite.example',
+ signInUrl: 'https://primary.example/sign-in',
+ });
+ expect(requestState.toAuth()).toBeSignedOutToAuth();
+ expect(requestState.headers.get('location')).toBeNull();
+ });
+
+ test('cookieToken: returns signed out without handshake when satelliteAutoSync is not set (defaults to false) and no cookies - dev', async () => {
+ const requestState = await authenticateRequest(
+ mockRequestWithCookies(
+ { ...defaultHeaders, 'sec-fetch-dest': 'document' },
+ {
+ __client_uat: '0',
+ __clerk_db_jwt: mockJwt,
+ },
+ ),
+ mockOptions({
+ secretKey: 'sk_test_deadbeef',
+ publishableKey: PK_TEST,
+ isSatellite: true,
+ signInUrl: 'https://primary.dev/sign-in',
+ domain: 'satellite.dev',
+ }),
+ );
+
+ expect(requestState).toBeSignedOut({
+ reason: AuthErrorReason.SessionTokenAndUATMissing,
+ isSatellite: true,
+ domain: 'satellite.dev',
+ signInUrl: 'https://primary.dev/sign-in',
+ });
+ expect(requestState.toAuth()).toBeSignedOutToAuth();
+ expect(requestState.headers.get('location')).toBeNull();
+ });
+
+ test('cookieToken: triggers handshake when satelliteAutoSync is not set but __clerk_synced=false is present - prod', async () => {
+ const requestState = await authenticateRequest(
+ mockRequestWithCookies(
+ { ...defaultHeaders, 'sec-fetch-dest': 'document' },
+ { __client_uat: '0' },
+ `http://satellite.example/path?__clerk_synced=false`,
+ ),
+ mockOptions({
+ secretKey: 'deadbeef',
+ publishableKey: PK_LIVE,
+ signInUrl: 'https://primary.example/sign-in',
+ isSatellite: true,
+ domain: 'satellite.example',
+ }),
+ );
+
+ expect(requestState).toMatchHandshake({
+ reason: AuthErrorReason.SatelliteCookieNeedsSyncing,
+ isSatellite: true,
+ domain: 'satellite.example',
+ signInUrl: 'https://primary.example/sign-in',
+ });
+ });
+
+ test('cookieToken: triggers handshake when satelliteAutoSync is not set but __clerk_synced=false is present - dev', async () => {
+ const requestState = await authenticateRequest(
+ mockRequestWithCookies(
+ { ...defaultHeaders, 'sec-fetch-dest': 'document' },
+ {
+ __client_uat: '0',
+ __clerk_db_jwt: mockJwt,
+ },
+ `http://satellite.dev/path?__clerk_synced=false`,
+ ),
+ mockOptions({
+ secretKey: 'sk_test_deadbeef',
+ publishableKey: PK_TEST,
+ signInUrl: 'https://primary.dev/sign-in',
+ isSatellite: true,
+ domain: 'satellite.dev',
+ }),
+ );
+
+ expect(requestState).toMatchHandshake({
+ reason: AuthErrorReason.SatelliteCookieNeedsSyncing,
+ isSatellite: true,
+ domain: 'satellite.dev',
+ signInUrl: 'https://primary.dev/sign-in',
+ });
+ expect(requestState.headers.get('location')).toEqual(
+ `https://primary.dev/sign-in?__clerk_redirect_url=http%3A%2F%2Fexample.com%2Fpath%3F__clerk_synced%3Dfalse`,
+ );
+ });
+
  test('cookieToken: returns handshake when app is not satellite and responds to syncing on dev instances[12y]', async () => {
  const sp = new URLSearchParams();
  sp.set('__clerk_redirect_url', 'http://localhost:3000');

packages/backend/src/tokens/request.ts

@@ -484,7 +484,7 @@ export const authenticateRequest: AuthenticateRequest = (async (
  * - 'false' (NeedsSync): Trigger sync - satellite returning from primary sign-in
  * - 'true' (Completed): Sync done - prevents re-sync loop
  *
- * With satelliteAutoSync=false:
+ * With satelliteAutoSync=false or unset (Core 3 default):
  * - Skip handshake on first visit if no cookies exist (return signedOut immediately)
  * - Trigger handshake when __clerk_synced=false is present (post sign-in redirect)
  * - Allow normal token verification flow when cookies exist (enables refresh)
@@ -499,8 +499,8 @@ export const authenticateRequest: AuthenticateRequest = (async (
  const hasCookies = hasSessionToken || hasActiveClient;
 
  // Determine if we should skip handshake for satellites with no cookies
- // satelliteAutoSync defaults to true, so we only skip when explicitly set to false
- const shouldSkipSatelliteHandshake = authenticateContext.satelliteAutoSync === false && !hasCookies && !needsSync;
+ // satelliteAutoSync defaults to false (Core 3), so we skip unless explicitly set to true
+ const shouldSkipSatelliteHandshake = authenticateContext.satelliteAutoSync !== true && !hasCookies && !needsSync;
 
  if (authenticateContext.instanceType === 'production' && isRequestEligibleForMultiDomainSync && !syncCompleted) {
  // With satelliteAutoSync=false: skip handshake if no cookies and no sync trigger

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

@@ -2386,6 +2386,7 @@ describe('Clerk singleton', () => {
  describe('Clerk().isSatellite and Clerk().domain getters', () => {
  beforeEach(() => {
  mockClientFetch.mockReset();
+ mockClientFetch.mockReturnValue(Promise.resolve({ signedInSessions: [] }));
  mockEnvironmentFetch.mockReturnValue(
  Promise.resolve({
  authConfig: {},

packages/clerk-js/src/core/auth/AuthCookieService.ts

@@ -111,7 +111,7 @@ export class AuthCookieService {
  if (!this.clerk.loaded) {
  return this.clientUat.get() <= 0;
  }
- return !!this.clerk.user;
+ return !this.clerk.user;
  }
 
  public async handleUnauthenticatedDevBrowser() {

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

@@ -2845,10 +2845,9 @@ export class Clerk implements ClerkInterface {
  return true;
  }
 
- // Check if satelliteAutoSync is disabled - if so, skip automatic sync
- // unless explicitly triggered via __clerk_synced=false
- if (this.#options.satelliteAutoSync === false) {
- // Skip automatic sync when satelliteAutoSync is false
+ // Check if satelliteAutoSync is enabled - only auto-sync when explicitly opted in
+ // In Core 3, satelliteAutoSync defaults to false (undefined is treated as false)
+ if (this.#options.satelliteAutoSync !== true) {
  return false;
  }
 

.changeset/fix-satellite-auto-sync-default.md

@@ -0,0 +1,6 @@
+---
+"@clerk/backend": patch
+"@clerk/clerk-js": patch
+---
+
+Fix `satelliteAutoSync` to default to `false` as documented. Previously, not passing the prop resulted in `undefined`, which was treated as `true` due to a strict equality check (`=== false`). This preserved Core 2 auto-sync behavior instead of the intended Core 3 default. The check is now `!== true`, so both `undefined` and `false` skip automatic satellite sync.

integration/tests/handshake.test.ts

@@ -529,7 +529,7 @@ test.describe('Client handshake @generic', () => {
  expect(res.status).toBe(200);
  });
 
- test('signed out satellite with sec-fetch-dest=document - prod', async () => {
+ test('signed out satellite with sec-fetch-dest=document skips handshake by default (satelliteAutoSync unset) - prod', async () => {
  const config = generateConfig({
  mode: 'live',
  });
@@ -543,13 +543,8 @@ test.describe('Client handshake @generic', () => {
  }),
  redirect: 'manual',
  });
- expect(res.status).toBe(307);
- const locationUrl = new URL(res.headers.get('location'));
- expect(locationUrl.origin + locationUrl.pathname).toBe('https://clerk.example.com/v1/client/handshake');
- expect(locationUrl.searchParams.get('redirect_url')).toBe(`${app.serverUrl}/`);
- expect(locationUrl.searchParams.get('__clerk_hs_reason')).toBe('satellite-needs-syncing');
- expect(locationUrl.searchParams.has('__clerk_api_version')).toBe(true);
- expect(locationUrl.searchParams.get('suffixed_cookies')).toBe('false');
+ // In Core 3, satelliteAutoSync defaults to false, so no handshake redirect
+ expect(res.status).toBe(200);
  });
 
  test('signed out satellite - dev', async () => {
@@ -628,7 +623,28 @@ test.describe('Client handshake @generic', () => {
  expect(res.status).toBe(200);
  });
 
- test('signed out satellite with satelliteAutoSync=true (default) triggers handshake - prod', async () => {
+ test('signed out satellite with satelliteAutoSync unset triggers handshake when __clerk_synced=false - prod', async () => {
+ const config = generateConfig({
+ mode: 'live',
+ });
+ const res = await fetch(app.serverUrl + '/?__clerk_synced=false', {
+ headers: new Headers({
+ 'X-Publishable-Key': config.pk,
+ 'X-Secret-Key': config.sk,
+ 'X-Satellite': 'true',
+ 'X-Domain': 'example.com',
+ 'Sec-Fetch-Dest': 'document',
+ }),
+ redirect: 'manual',
+ });
+ // Even without satelliteAutoSync, __clerk_synced=false (post sign-in) should trigger handshake
+ expect(res.status).toBe(307);
+ const locationUrl = new URL(res.headers.get('location'));
+ expect(locationUrl.origin + locationUrl.pathname).toBe('https://clerk.example.com/v1/client/handshake');
+ expect(locationUrl.searchParams.get('__clerk_hs_reason')).toBe('satellite-needs-syncing');
+ });
+
+ test('signed out satellite with satelliteAutoSync=true (explicit opt-in) triggers handshake - prod', async () => {
  const config = generateConfig({
  mode: 'live',
  });
@@ -643,7 +659,7 @@ test.describe('Client handshake @generic', () => {
  }),
  redirect: 'manual',
  });
- // Should redirect to handshake with default/true satelliteAutoSync
+ // Should redirect to handshake when satelliteAutoSync is explicitly true
  expect(res.status).toBe(307);
  const locationUrl = new URL(res.headers.get('location'));
  expect(locationUrl.origin + locationUrl.pathname).toBe('https://clerk.example.com/v1/client/handshake');

packages/backend/src/tokens/__tests__/request.test.ts

@@ -651,7 +651,7 @@ describe('tokens.authenticateRequest(options)', () => {
  expect(requestState).toBeSignedOutToAuth();
  });
 
- test('cookieToken: returns handshake when clientUat is missing or equals to 0 and is satellite and not is synced [11y]', async () => {
+ test('cookieToken: returns handshake when clientUat is missing or equals to 0 and is satellite with satelliteAutoSync=true and not is synced [11y]', async () => {
  server.use(
  http.get('https://api.clerk.test/v1/jwks', () => {
  return HttpResponse.json(mockJwks);
@@ -671,6 +671,7 @@ describe('tokens.authenticateRequest(options)', () => {
  isSatellite: true,
  signInUrl: 'https://primary.dev/sign-in',
  domain: 'satellite.dev',
+ satelliteAutoSync: true,
  }),
  );
 
@@ -684,7 +685,7 @@ describe('tokens.authenticateRequest(options)', () => {
  expect(requestState.toAuth()).toBeNull();
  });
 
- test('cookieToken: redirects to signInUrl when is satellite dev and not synced', async () => {
+ test('cookieToken: redirects to signInUrl when is satellite dev with satelliteAutoSync=true and not synced', async () => {
  server.use(
  http.get('https://api.clerk.test/v1/jwks', () => {
  return HttpResponse.json(mockJwks);
@@ -705,6 +706,7 @@ describe('tokens.authenticateRequest(options)', () => {
  isSatellite: true,
  signInUrl: 'https://primary.dev/sign-in',
  domain: 'satellite.dev',
+ satelliteAutoSync: true,
  }),
  );
 
@@ -873,6 +875,114 @@ describe('tokens.authenticateRequest(options)', () => {
  expect(requestState.toAuth()).toBeSignedOutToAuth();
  });
 
+ test('cookieToken: returns signed out without handshake when satelliteAutoSync is not set (defaults to false) and no cookies - prod', async () => {
+ const requestState = await authenticateRequest(
+ mockRequestWithCookies(
+ { ...defaultHeaders, 'sec-fetch-dest': 'document' },
+ { __client_uat: '0' },
+ `http://satellite.example/path`,
+ ),
+ mockOptions({
+ secretKey: 'deadbeef',
+ publishableKey: PK_LIVE,
+ signInUrl: 'https://primary.example/sign-in',
+ isSatellite: true,
+ domain: 'satellite.example',
+ }),
+ );
+
+ expect(requestState).toBeSignedOut({
+ reason: AuthErrorReason.SessionTokenAndUATMissing,
+ isSatellite: true,
+ domain: 'satellite.example',
+ signInUrl: 'https://primary.example/sign-in',
+ });
+ expect(requestState.toAuth()).toBeSignedOutToAuth();
+ expect(requestState.headers.get('location')).toBeNull();
+ });
+
+ test('cookieToken: returns signed out without handshake when satelliteAutoSync is not set (defaults to false) and no cookies - dev', async () => {
+ const requestState = await authenticateRequest(
+ mockRequestWithCookies(
+ { ...defaultHeaders, 'sec-fetch-dest': 'document' },
+ {
+ __client_uat: '0',
+ __clerk_db_jwt: mockJwt,
+ },
+ ),
+ mockOptions({
+ secretKey: 'sk_test_deadbeef',
+ publishableKey: PK_TEST,
+ isSatellite: true,
+ signInUrl: 'https://primary.dev/sign-in',
+ domain: 'satellite.dev',
+ }),
+ );
+
+ expect(requestState).toBeSignedOut({
+ reason: AuthErrorReason.SessionTokenAndUATMissing,
+ isSatellite: true,
+ domain: 'satellite.dev',
+ signInUrl: 'https://primary.dev/sign-in',
+ });
+ expect(requestState.toAuth()).toBeSignedOutToAuth();
+ expect(requestState.headers.get('location')).toBeNull();
+ });
+
+ test('cookieToken: triggers handshake when satelliteAutoSync is not set but __clerk_synced=false is present - prod', async () => {
+ const requestState = await authenticateRequest(
+ mockRequestWithCookies(
+ { ...defaultHeaders, 'sec-fetch-dest': 'document' },
+ { __client_uat: '0' },
+ `http://satellite.example/path?__clerk_synced=false`,
+ ),
+ mockOptions({
+ secretKey: 'deadbeef',
+ publishableKey: PK_LIVE,
+ signInUrl: 'https://primary.example/sign-in',
+ isSatellite: true,
+ domain: 'satellite.example',
+ }),
+ );
+
+ expect(requestState).toMatchHandshake({
+ reason: AuthErrorReason.SatelliteCookieNeedsSyncing,
+ isSatellite: true,
+ domain: 'satellite.example',
+ signInUrl: 'https://primary.example/sign-in',
+ });
+ });
+
+ test('cookieToken: triggers handshake when satelliteAutoSync is not set but __clerk_synced=false is present - dev', async () => {
+ const requestState = await authenticateRequest(
+ mockRequestWithCookies(
+ { ...defaultHeaders, 'sec-fetch-dest': 'document' },
+ {
+ __client_uat: '0',
+ __clerk_db_jwt: mockJwt,
+ },
+ `http://satellite.dev/path?__clerk_synced=false`,
+ ),
+ mockOptions({
+ secretKey: 'sk_test_deadbeef',
+ publishableKey: PK_TEST,
+ signInUrl: 'https://primary.dev/sign-in',
+ isSatellite: true,
+ domain: 'satellite.dev',
+ }),
+ );
+
+ expect(requestState).toMatchHandshake({
+ reason: AuthErrorReason.SatelliteCookieNeedsSyncing,
+ isSatellite: true,
+ domain: 'satellite.dev',
+ signInUrl: 'https://primary.dev/sign-in',
+ });
+ expect(requestState.headers.get('location')).toEqual(
+ `https://primary.dev/sign-in?__clerk_redirect_url=http%3A%2F%2Fexample.com%2Fpath%3F__clerk_synced%3Dfalse`,
+ );
+ });
+
  test('cookieToken: returns handshake when app is not satellite and responds to syncing on dev instances[12y]', async () => {
  const sp = new URLSearchParams();
  sp.set('__clerk_redirect_url', 'http://localhost:3000');

packages/backend/src/tokens/request.ts

@@ -484,7 +484,7 @@ export const authenticateRequest: AuthenticateRequest = (async (
  * - 'false' (NeedsSync): Trigger sync - satellite returning from primary sign-in
  * - 'true' (Completed): Sync done - prevents re-sync loop
  *
- * With satelliteAutoSync=false:
+ * With satelliteAutoSync=false or unset (Core 3 default):
  * - Skip handshake on first visit if no cookies exist (return signedOut immediately)
  * - Trigger handshake when __clerk_synced=false is present (post sign-in redirect)
  * - Allow normal token verification flow when cookies exist (enables refresh)
@@ -499,8 +499,8 @@ export const authenticateRequest: AuthenticateRequest = (async (
  const hasCookies = hasSessionToken || hasActiveClient;
 
  // Determine if we should skip handshake for satellites with no cookies
- // satelliteAutoSync defaults to true, so we only skip when explicitly set to false
- const shouldSkipSatelliteHandshake = authenticateContext.satelliteAutoSync === false && !hasCookies && !needsSync;
+ // satelliteAutoSync defaults to false (Core 3), so we skip unless explicitly set to true
+ const shouldSkipSatelliteHandshake = authenticateContext.satelliteAutoSync !== true && !hasCookies && !needsSync;
 
  if (authenticateContext.instanceType === 'production' && isRequestEligibleForMultiDomainSync && !syncCompleted) {
  // With satelliteAutoSync=false: skip handshake if no cookies and no sync trigger

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

@@ -2386,6 +2386,7 @@ describe('Clerk singleton', () => {
  describe('Clerk().isSatellite and Clerk().domain getters', () => {
  beforeEach(() => {
  mockClientFetch.mockReset();
+ mockClientFetch.mockReturnValue(Promise.resolve({ signedInSessions: [] }));
  mockEnvironmentFetch.mockReturnValue(
  Promise.resolve({
  authConfig: {},

packages/clerk-js/src/core/auth/AuthCookieService.ts

@@ -111,7 +111,7 @@ export class AuthCookieService {
  if (!this.clerk.loaded) {
  return this.clientUat.get() <= 0;
  }
- return !!this.clerk.user;
+ return !this.clerk.user;
  }
 
  public async handleUnauthenticatedDevBrowser() {

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

@@ -2845,10 +2845,9 @@ export class Clerk implements ClerkInterface {
  return true;
  }
 
- // Check if satelliteAutoSync is disabled - if so, skip automatic sync
- // unless explicitly triggered via __clerk_synced=false
- if (this.#options.satelliteAutoSync === false) {
- // Skip automatic sync when satelliteAutoSync is false
+ // Check if satelliteAutoSync is enabled - only auto-sync when explicitly opted in
+ // In Core 3, satelliteAutoSync defaults to false (undefined is treated as false)
+ if (this.#options.satelliteAutoSync !== true) {
  return false;
  }
 

.changeset/fix-satellite-auto-sync-default.md

@@ -0,0 +1,6 @@
+---
+"@clerk/backend": patch
+"@clerk/clerk-js": patch
+---
+
+Fix `satelliteAutoSync` to default to `false` as documented. Previously, not passing the prop resulted in `undefined`, which was treated as `true` due to a strict equality check (`=== false`). This preserved Core 2 auto-sync behavior instead of the intended Core 3 default. The check is now `!== true`, so both `undefined` and `false` skip automatic satellite sync.

integration/tests/handshake.test.ts

@@ -529,7 +529,7 @@ test.describe('Client handshake @generic', () => {
  expect(res.status).toBe(200);
  });
 
- test('signed out satellite with sec-fetch-dest=document - prod', async () => {
+ test('signed out satellite with sec-fetch-dest=document skips handshake by default (satelliteAutoSync unset) - prod', async () => {
  const config = generateConfig({
  mode: 'live',
  });
@@ -543,13 +543,8 @@ test.describe('Client handshake @generic', () => {
  }),
  redirect: 'manual',
  });
- expect(res.status).toBe(307);
- const locationUrl = new URL(res.headers.get('location'));
- expect(locationUrl.origin + locationUrl.pathname).toBe('https://clerk.example.com/v1/client/handshake');
- expect(locationUrl.searchParams.get('redirect_url')).toBe(`${app.serverUrl}/`);
- expect(locationUrl.searchParams.get('__clerk_hs_reason')).toBe('satellite-needs-syncing');
- expect(locationUrl.searchParams.has('__clerk_api_version')).toBe(true);
- expect(locationUrl.searchParams.get('suffixed_cookies')).toBe('false');
+ // In Core 3, satelliteAutoSync defaults to false, so no handshake redirect
+ expect(res.status).toBe(200);
  });
 
  test('signed out satellite - dev', async () => {
@@ -628,7 +623,28 @@ test.describe('Client handshake @generic', () => {
  expect(res.status).toBe(200);
  });
 
- test('signed out satellite with satelliteAutoSync=true (default) triggers handshake - prod', async () => {
+ test('signed out satellite with satelliteAutoSync unset triggers handshake when __clerk_synced=false - prod', async () => {
+ const config = generateConfig({
+ mode: 'live',
+ });
+ const res = await fetch(app.serverUrl + '/?__clerk_synced=false', {
+ headers: new Headers({
+ 'X-Publishable-Key': config.pk,
+ 'X-Secret-Key': config.sk,
+ 'X-Satellite': 'true',
+ 'X-Domain': 'example.com',
+ 'Sec-Fetch-Dest': 'document',
+ }),
+ redirect: 'manual',
+ });
+ // Even without satelliteAutoSync, __clerk_synced=false (post sign-in) should trigger handshake
+ expect(res.status).toBe(307);
+ const locationUrl = new URL(res.headers.get('location'));
+ expect(locationUrl.origin + locationUrl.pathname).toBe('https://clerk.example.com/v1/client/handshake');
+ expect(locationUrl.searchParams.get('__clerk_hs_reason')).toBe('satellite-needs-syncing');
+ });
+
+ test('signed out satellite with satelliteAutoSync=true (explicit opt-in) triggers handshake - prod', async () => {
  const config = generateConfig({
  mode: 'live',
  });
@@ -643,7 +659,7 @@ test.describe('Client handshake @generic', () => {
  }),
  redirect: 'manual',
  });
- // Should redirect to handshake with default/true satelliteAutoSync
+ // Should redirect to handshake when satelliteAutoSync is explicitly true
  expect(res.status).toBe(307);
  const locationUrl = new URL(res.headers.get('location'));
  expect(locationUrl.origin + locationUrl.pathname).toBe('https://clerk.example.com/v1/client/handshake');

packages/backend/src/tokens/__tests__/request.test.ts

@@ -651,7 +651,7 @@ describe('tokens.authenticateRequest(options)', () => {
  expect(requestState).toBeSignedOutToAuth();
  });
 
- test('cookieToken: returns handshake when clientUat is missing or equals to 0 and is satellite and not is synced [11y]', async () => {
+ test('cookieToken: returns handshake when clientUat is missing or equals to 0 and is satellite with satelliteAutoSync=true and not is synced [11y]', async () => {
  server.use(
  http.get('https://api.clerk.test/v1/jwks', () => {
  return HttpResponse.json(mockJwks);
@@ -671,6 +671,7 @@ describe('tokens.authenticateRequest(options)', () => {
  isSatellite: true,
  signInUrl: 'https://primary.dev/sign-in',
  domain: 'satellite.dev',
+ satelliteAutoSync: true,
  }),
  );
 
@@ -684,7 +685,7 @@ describe('tokens.authenticateRequest(options)', () => {
  expect(requestState.toAuth()).toBeNull();
  });
 
- test('cookieToken: redirects to signInUrl when is satellite dev and not synced', async () => {
+ test('cookieToken: redirects to signInUrl when is satellite dev with satelliteAutoSync=true and not synced', async () => {
  server.use(
  http.get('https://api.clerk.test/v1/jwks', () => {
  return HttpResponse.json(mockJwks);
@@ -705,6 +706,7 @@ describe('tokens.authenticateRequest(options)', () => {
  isSatellite: true,
  signInUrl: 'https://primary.dev/sign-in',
  domain: 'satellite.dev',
+ satelliteAutoSync: true,
  }),
  );
 
@@ -873,6 +875,114 @@ describe('tokens.authenticateRequest(options)', () => {
  expect(requestState.toAuth()).toBeSignedOutToAuth();
  });
 
+ test('cookieToken: returns signed out without handshake when satelliteAutoSync is not set (defaults to false) and no cookies - prod', async () => {
+ const requestState = await authenticateRequest(
+ mockRequestWithCookies(
+ { ...defaultHeaders, 'sec-fetch-dest': 'document' },
+ { __client_uat: '0' },
+ `http://satellite.example/path`,
+ ),
+ mockOptions({
+ secretKey: 'deadbeef',
+ publishableKey: PK_LIVE,
+ signInUrl: 'https://primary.example/sign-in',
+ isSatellite: true,
+ domain: 'satellite.example',
+ }),
+ );
+
+ expect(requestState).toBeSignedOut({
+ reason: AuthErrorReason.SessionTokenAndUATMissing,
+ isSatellite: true,
+ domain: 'satellite.example',
+ signInUrl: 'https://primary.example/sign-in',
+ });
+ expect(requestState.toAuth()).toBeSignedOutToAuth();
+ expect(requestState.headers.get('location')).toBeNull();
+ });
+
+ test('cookieToken: returns signed out without handshake when satelliteAutoSync is not set (defaults to false) and no cookies - dev', async () => {
+ const requestState = await authenticateRequest(
+ mockRequestWithCookies(
+ { ...defaultHeaders, 'sec-fetch-dest': 'document' },
+ {
+ __client_uat: '0',
+ __clerk_db_jwt: mockJwt,
+ },
+ ),
+ mockOptions({
+ secretKey: 'sk_test_deadbeef',
+ publishableKey: PK_TEST,
+ isSatellite: true,
+ signInUrl: 'https://primary.dev/sign-in',
+ domain: 'satellite.dev',
+ }),
+ );
+
+ expect(requestState).toBeSignedOut({
+ reason: AuthErrorReason.SessionTokenAndUATMissing,
+ isSatellite: true,
+ domain: 'satellite.dev',
+ signInUrl: 'https://primary.dev/sign-in',
+ });
+ expect(requestState.toAuth()).toBeSignedOutToAuth();
+ expect(requestState.headers.get('location')).toBeNull();
+ });
+
+ test('cookieToken: triggers handshake when satelliteAutoSync is not set but __clerk_synced=false is present - prod', async () => {
+ const requestState = await authenticateRequest(
+ mockRequestWithCookies(
+ { ...defaultHeaders, 'sec-fetch-dest': 'document' },
+ { __client_uat: '0' },
+ `http://satellite.example/path?__clerk_synced=false`,
+ ),
+ mockOptions({
+ secretKey: 'deadbeef',
+ publishableKey: PK_LIVE,
+ signInUrl: 'https://primary.example/sign-in',
+ isSatellite: true,
+ domain: 'satellite.example',
+ }),
+ );
+
+ expect(requestState).toMatchHandshake({
+ reason: AuthErrorReason.SatelliteCookieNeedsSyncing,
+ isSatellite: true,
+ domain: 'satellite.example',
+ signInUrl: 'https://primary.example/sign-in',
+ });
+ });
+
+ test('cookieToken: triggers handshake when satelliteAutoSync is not set but __clerk_synced=false is present - dev', async () => {
+ const requestState = await authenticateRequest(
+ mockRequestWithCookies(
+ { ...defaultHeaders, 'sec-fetch-dest': 'document' },
+ {
+ __client_uat: '0',
+ __clerk_db_jwt: mockJwt,
+ },
+ `http://satellite.dev/path?__clerk_synced=false`,
+ ),
+ mockOptions({
+ secretKey: 'sk_test_deadbeef',
+ publishableKey: PK_TEST,
+ signInUrl: 'https://primary.dev/sign-in',
+ isSatellite: true,
+ domain: 'satellite.dev',
+ }),
+ );
+
+ expect(requestState).toMatchHandshake({
+ reason: AuthErrorReason.SatelliteCookieNeedsSyncing,
+ isSatellite: true,
+ domain: 'satellite.dev',
+ signInUrl: 'https://primary.dev/sign-in',
+ });
+ expect(requestState.headers.get('location')).toEqual(
+ `https://primary.dev/sign-in?__clerk_redirect_url=http%3A%2F%2Fexample.com%2Fpath%3F__clerk_synced%3Dfalse`,
+ );
+ });
+
  test('cookieToken: returns handshake when app is not satellite and responds to syncing on dev instances[12y]', async () => {
  const sp = new URLSearchParams();
  sp.set('__clerk_redirect_url', 'http://localhost:3000');

packages/backend/src/tokens/request.ts

@@ -484,7 +484,7 @@ export const authenticateRequest: AuthenticateRequest = (async (
  * - 'false' (NeedsSync): Trigger sync - satellite returning from primary sign-in
  * - 'true' (Completed): Sync done - prevents re-sync loop
  *
- * With satelliteAutoSync=false:
+ * With satelliteAutoSync=false or unset (Core 3 default):
  * - Skip handshake on first visit if no cookies exist (return signedOut immediately)
  * - Trigger handshake when __clerk_synced=false is present (post sign-in redirect)
  * - Allow normal token verification flow when cookies exist (enables refresh)
@@ -499,8 +499,8 @@ export const authenticateRequest: AuthenticateRequest = (async (
  const hasCookies = hasSessionToken || hasActiveClient;
 
  // Determine if we should skip handshake for satellites with no cookies
- // satelliteAutoSync defaults to true, so we only skip when explicitly set to false
- const shouldSkipSatelliteHandshake = authenticateContext.satelliteAutoSync === false && !hasCookies && !needsSync;
+ // satelliteAutoSync defaults to false (Core 3), so we skip unless explicitly set to true
+ const shouldSkipSatelliteHandshake = authenticateContext.satelliteAutoSync !== true && !hasCookies && !needsSync;
 
  if (authenticateContext.instanceType === 'production' && isRequestEligibleForMultiDomainSync && !syncCompleted) {
  // With satelliteAutoSync=false: skip handshake if no cookies and no sync trigger

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

@@ -2386,6 +2386,7 @@ describe('Clerk singleton', () => {
  describe('Clerk().isSatellite and Clerk().domain getters', () => {
  beforeEach(() => {
  mockClientFetch.mockReset();
+ mockClientFetch.mockReturnValue(Promise.resolve({ signedInSessions: [] }));
  mockEnvironmentFetch.mockReturnValue(
  Promise.resolve({
  authConfig: {},

packages/clerk-js/src/core/auth/AuthCookieService.ts

@@ -111,7 +111,7 @@ export class AuthCookieService {
  if (!this.clerk.loaded) {
  return this.clientUat.get() <= 0;
  }
- return !!this.clerk.user;
+ return !this.clerk.user;
  }
 
  public async handleUnauthenticatedDevBrowser() {

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

@@ -2845,10 +2845,9 @@ export class Clerk implements ClerkInterface {
  return true;
  }
 
- // Check if satelliteAutoSync is disabled - if so, skip automatic sync
- // unless explicitly triggered via __clerk_synced=false
- if (this.#options.satelliteAutoSync === false) {
- // Skip automatic sync when satelliteAutoSync is false
+ // Check if satelliteAutoSync is enabled - only auto-sync when explicitly opted in
+ // In Core 3, satelliteAutoSync defaults to false (undefined is treated as false)
+ if (this.#options.satelliteAutoSync !== true) {
  return false;
  }
 

.changeset/fix-satellite-auto-sync-default.md

@@ -0,0 +1,6 @@
+---
+"@clerk/backend": patch
+"@clerk/clerk-js": patch
+---
+
+Fix `satelliteAutoSync` to default to `false` as documented. Previously, not passing the prop resulted in `undefined`, which was treated as `true` due to a strict equality check (`=== false`). This preserved Core 2 auto-sync behavior instead of the intended Core 3 default. The check is now `!== true`, so both `undefined` and `false` skip automatic satellite sync.

integration/tests/handshake.test.ts

@@ -529,7 +529,7 @@ test.describe('Client handshake @generic', () => {
  expect(res.status).toBe(200);
  });
 
- test('signed out satellite with sec-fetch-dest=document - prod', async () => {
+ test('signed out satellite with sec-fetch-dest=document skips handshake by default (satelliteAutoSync unset) - prod', async () => {
  const config = generateConfig({
  mode: 'live',
  });
@@ -543,13 +543,8 @@ test.describe('Client handshake @generic', () => {
  }),
  redirect: 'manual',
  });
- expect(res.status).toBe(307);
- const locationUrl = new URL(res.headers.get('location'));
- expect(locationUrl.origin + locationUrl.pathname).toBe('https://clerk.example.com/v1/client/handshake');
- expect(locationUrl.searchParams.get('redirect_url')).toBe(`${app.serverUrl}/`);
- expect(locationUrl.searchParams.get('__clerk_hs_reason')).toBe('satellite-needs-syncing');
- expect(locationUrl.searchParams.has('__clerk_api_version')).toBe(true);
- expect(locationUrl.searchParams.get('suffixed_cookies')).toBe('false');
+ // In Core 3, satelliteAutoSync defaults to false, so no handshake redirect
+ expect(res.status).toBe(200);
  });
 
  test('signed out satellite - dev', async () => {
@@ -628,7 +623,28 @@ test.describe('Client handshake @generic', () => {
  expect(res.status).toBe(200);
  });
 
- test('signed out satellite with satelliteAutoSync=true (default) triggers handshake - prod', async () => {
+ test('signed out satellite with satelliteAutoSync unset triggers handshake when __clerk_synced=false - prod', async () => {
+ const config = generateConfig({
+ mode: 'live',
+ });
+ const res = await fetch(app.serverUrl + '/?__clerk_synced=false', {
+ headers: new Headers({
+ 'X-Publishable-Key': config.pk,
+ 'X-Secret-Key': config.sk,
+ 'X-Satellite': 'true',
+ 'X-Domain': 'example.com',
+ 'Sec-Fetch-Dest': 'document',
+ }),
+ redirect: 'manual',
+ });
+ // Even without satelliteAutoSync, __clerk_synced=false (post sign-in) should trigger handshake
+ expect(res.status).toBe(307);
+ const locationUrl = new URL(res.headers.get('location'));
+ expect(locationUrl.origin + locationUrl.pathname).toBe('https://clerk.example.com/v1/client/handshake');
+ expect(locationUrl.searchParams.get('__clerk_hs_reason')).toBe('satellite-needs-syncing');
+ });
+
+ test('signed out satellite with satelliteAutoSync=true (explicit opt-in) triggers handshake - prod', async () => {
  const config = generateConfig({
  mode: 'live',
  });
@@ -643,7 +659,7 @@ test.describe('Client handshake @generic', () => {
  }),
  redirect: 'manual',
  });
- // Should redirect to handshake with default/true satelliteAutoSync
+ // Should redirect to handshake when satelliteAutoSync is explicitly true
  expect(res.status).toBe(307);
  const locationUrl = new URL(res.headers.get('location'));
  expect(locationUrl.origin + locationUrl.pathname).toBe('https://clerk.example.com/v1/client/handshake');

packages/backend/src/tokens/__tests__/request.test.ts

@@ -651,7 +651,7 @@ describe('tokens.authenticateRequest(options)', () => {
  expect(requestState).toBeSignedOutToAuth();
  });
 
- test('cookieToken: returns handshake when clientUat is missing or equals to 0 and is satellite and not is synced [11y]', async () => {
+ test('cookieToken: returns handshake when clientUat is missing or equals to 0 and is satellite with satelliteAutoSync=true and not is synced [11y]', async () => {
  server.use(
  http.get('https://api.clerk.test/v1/jwks', () => {
  return HttpResponse.json(mockJwks);
@@ -671,6 +671,7 @@ describe('tokens.authenticateRequest(options)', () => {
  isSatellite: true,
  signInUrl: 'https://primary.dev/sign-in',
  domain: 'satellite.dev',
+ satelliteAutoSync: true,
  }),
  );
 
@@ -684,7 +685,7 @@ describe('tokens.authenticateRequest(options)', () => {
  expect(requestState.toAuth()).toBeNull();
  });
 
- test('cookieToken: redirects to signInUrl when is satellite dev and not synced', async () => {
+ test('cookieToken: redirects to signInUrl when is satellite dev with satelliteAutoSync=true and not synced', async () => {
  server.use(
  http.get('https://api.clerk.test/v1/jwks', () => {
  return HttpResponse.json(mockJwks);
@@ -705,6 +706,7 @@ describe('tokens.authenticateRequest(options)', () => {
  isSatellite: true,
  signInUrl: 'https://primary.dev/sign-in',
  domain: 'satellite.dev',
+ satelliteAutoSync: true,
  }),
  );
 
@@ -873,6 +875,114 @@ describe('tokens.authenticateRequest(options)', () => {
  expect(requestState.toAuth()).toBeSignedOutToAuth();
  });
 
+ test('cookieToken: returns signed out without handshake when satelliteAutoSync is not set (defaults to false) and no cookies - prod', async () => {
+ const requestState = await authenticateRequest(
+ mockRequestWithCookies(
+ { ...defaultHeaders, 'sec-fetch-dest': 'document' },
+ { __client_uat: '0' },
+ `http://satellite.example/path`,
+ ),
+ mockOptions({
+ secretKey: 'deadbeef',
+ publishableKey: PK_LIVE,
+ signInUrl: 'https://primary.example/sign-in',
+ isSatellite: true,
+ domain: 'satellite.example',
+ }),
+ );
+
+ expect(requestState).toBeSignedOut({
+ reason: AuthErrorReason.SessionTokenAndUATMissing,
+ isSatellite: true,
+ domain: 'satellite.example',
+ signInUrl: 'https://primary.example/sign-in',
+ });
+ expect(requestState.toAuth()).toBeSignedOutToAuth();
+ expect(requestState.headers.get('location')).toBeNull();
+ });
+
+ test('cookieToken: returns signed out without handshake when satelliteAutoSync is not set (defaults to false) and no cookies - dev', async () => {
+ const requestState = await authenticateRequest(
+ mockRequestWithCookies(
+ { ...defaultHeaders, 'sec-fetch-dest': 'document' },
+ {
+ __client_uat: '0',
+ __clerk_db_jwt: mockJwt,
+ },
+ ),
+ mockOptions({
+ secretKey: 'sk_test_deadbeef',
+ publishableKey: PK_TEST,
+ isSatellite: true,
+ signInUrl: 'https://primary.dev/sign-in',
+ domain: 'satellite.dev',
+ }),
+ );
+
+ expect(requestState).toBeSignedOut({
+ reason: AuthErrorReason.SessionTokenAndUATMissing,
+ isSatellite: true,
+ domain: 'satellite.dev',
+ signInUrl: 'https://primary.dev/sign-in',
+ });
+ expect(requestState.toAuth()).toBeSignedOutToAuth();
+ expect(requestState.headers.get('location')).toBeNull();
+ });
+
+ test('cookieToken: triggers handshake when satelliteAutoSync is not set but __clerk_synced=false is present - prod', async () => {
+ const requestState = await authenticateRequest(
+ mockRequestWithCookies(
+ { ...defaultHeaders, 'sec-fetch-dest': 'document' },
+ { __client_uat: '0' },
+ `http://satellite.example/path?__clerk_synced=false`,
+ ),
+ mockOptions({
+ secretKey: 'deadbeef',
+ publishableKey: PK_LIVE,
+ signInUrl: 'https://primary.example/sign-in',
+ isSatellite: true,
+ domain: 'satellite.example',
+ }),
+ );
+
+ expect(requestState).toMatchHandshake({
+ reason: AuthErrorReason.SatelliteCookieNeedsSyncing,
+ isSatellite: true,
+ domain: 'satellite.example',
+ signInUrl: 'https://primary.example/sign-in',
+ });
+ });
+
+ test('cookieToken: triggers handshake when satelliteAutoSync is not set but __clerk_synced=false is present - dev', async () => {
+ const requestState = await authenticateRequest(
+ mockRequestWithCookies(
+ { ...defaultHeaders, 'sec-fetch-dest': 'document' },
+ {
+ __client_uat: '0',
+ __clerk_db_jwt: mockJwt,
+ },
+ `http://satellite.dev/path?__clerk_synced=false`,
+ ),
+ mockOptions({
+ secretKey: 'sk_test_deadbeef',
+ publishableKey: PK_TEST,
+ signInUrl: 'https://primary.dev/sign-in',
+ isSatellite: true,
+ domain: 'satellite.dev',
+ }),
+ );
+
+ expect(requestState).toMatchHandshake({
+ reason: AuthErrorReason.SatelliteCookieNeedsSyncing,
+ isSatellite: true,
+ domain: 'satellite.dev',
+ signInUrl: 'https://primary.dev/sign-in',
+ });
+ expect(requestState.headers.get('location')).toEqual(
+ `https://primary.dev/sign-in?__clerk_redirect_url=http%3A%2F%2Fexample.com%2Fpath%3F__clerk_synced%3Dfalse`,
+ );
+ });
+
  test('cookieToken: returns handshake when app is not satellite and responds to syncing on dev instances[12y]', async () => {
  const sp = new URLSearchParams();
  sp.set('__clerk_redirect_url', 'http://localhost:3000');

packages/backend/src/tokens/request.ts

@@ -484,7 +484,7 @@ export const authenticateRequest: AuthenticateRequest = (async (
  * - 'false' (NeedsSync): Trigger sync - satellite returning from primary sign-in
  * - 'true' (Completed): Sync done - prevents re-sync loop
  *
- * With satelliteAutoSync=false:
+ * With satelliteAutoSync=false or unset (Core 3 default):
  * - Skip handshake on first visit if no cookies exist (return signedOut immediately)
  * - Trigger handshake when __clerk_synced=false is present (post sign-in redirect)
  * - Allow normal token verification flow when cookies exist (enables refresh)
@@ -499,8 +499,8 @@ export const authenticateRequest: AuthenticateRequest = (async (
  const hasCookies = hasSessionToken || hasActiveClient;
 
  // Determine if we should skip handshake for satellites with no cookies
- // satelliteAutoSync defaults to true, so we only skip when explicitly set to false
- const shouldSkipSatelliteHandshake = authenticateContext.satelliteAutoSync === false && !hasCookies && !needsSync;
+ // satelliteAutoSync defaults to false (Core 3), so we skip unless explicitly set to true
+ const shouldSkipSatelliteHandshake = authenticateContext.satelliteAutoSync !== true && !hasCookies && !needsSync;
 
  if (authenticateContext.instanceType === 'production' && isRequestEligibleForMultiDomainSync && !syncCompleted) {
  // With satelliteAutoSync=false: skip handshake if no cookies and no sync trigger

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

@@ -2386,6 +2386,7 @@ describe('Clerk singleton', () => {
  describe('Clerk().isSatellite and Clerk().domain getters', () => {
  beforeEach(() => {
  mockClientFetch.mockReset();
+ mockClientFetch.mockReturnValue(Promise.resolve({ signedInSessions: [] }));
  mockEnvironmentFetch.mockReturnValue(
  Promise.resolve({
  authConfig: {},

packages/clerk-js/src/core/auth/AuthCookieService.ts

@@ -111,7 +111,7 @@ export class AuthCookieService {
  if (!this.clerk.loaded) {
  return this.clientUat.get() <= 0;
  }
- return !!this.clerk.user;
+ return !this.clerk.user;
  }
 
  public async handleUnauthenticatedDevBrowser() {

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

@@ -2845,10 +2845,9 @@ export class Clerk implements ClerkInterface {
  return true;
  }
 
- // Check if satelliteAutoSync is disabled - if so, skip automatic sync
- // unless explicitly triggered via __clerk_synced=false
- if (this.#options.satelliteAutoSync === false) {
- // Skip automatic sync when satelliteAutoSync is false
+ // Check if satelliteAutoSync is enabled - only auto-sync when explicitly opted in
+ // In Core 3, satelliteAutoSync defaults to false (undefined is treated as false)
+ if (this.#options.satelliteAutoSync !== true) {
  return false;
  }
 

.changeset/fix-satellite-auto-sync-default.md

@@ -0,0 +1,6 @@
+---
+"@clerk/backend": patch
+"@clerk/clerk-js": patch
+---
+
+Fix `satelliteAutoSync` to default to `false` as documented. Previously, not passing the prop resulted in `undefined`, which was treated as `true` due to a strict equality check (`=== false`). This preserved Core 2 auto-sync behavior instead of the intended Core 3 default. The check is now `!== true`, so both `undefined` and `false` skip automatic satellite sync.

integration/tests/handshake.test.ts

@@ -529,7 +529,7 @@ test.describe('Client handshake @generic', () => {
  expect(res.status).toBe(200);
  });
 
- test('signed out satellite with sec-fetch-dest=document - prod', async () => {
+ test('signed out satellite with sec-fetch-dest=document skips handshake by default (satelliteAutoSync unset) - prod', async () => {
  const config = generateConfig({
  mode: 'live',
  });
@@ -543,13 +543,8 @@ test.describe('Client handshake @generic', () => {
  }),
  redirect: 'manual',
  });
- expect(res.status).toBe(307);
- const locationUrl = new URL(res.headers.get('location'));
- expect(locationUrl.origin + locationUrl.pathname).toBe('https://clerk.example.com/v1/client/handshake');
- expect(locationUrl.searchParams.get('redirect_url')).toBe(`${app.serverUrl}/`);
- expect(locationUrl.searchParams.get('__clerk_hs_reason')).toBe('satellite-needs-syncing');
- expect(locationUrl.searchParams.has('__clerk_api_version')).toBe(true);
- expect(locationUrl.searchParams.get('suffixed_cookies')).toBe('false');
+ // In Core 3, satelliteAutoSync defaults to false, so no handshake redirect
+ expect(res.status).toBe(200);
  });
 
  test('signed out satellite - dev', async () => {
@@ -628,7 +623,28 @@ test.describe('Client handshake @generic', () => {
  expect(res.status).toBe(200);
  });
 
- test('signed out satellite with satelliteAutoSync=true (default) triggers handshake - prod', async () => {
+ test('signed out satellite with satelliteAutoSync unset triggers handshake when __clerk_synced=false - prod', async () => {
+ const config = generateConfig({
+ mode: 'live',
+ });
+ const res = await fetch(app.serverUrl + '/?__clerk_synced=false', {
+ headers: new Headers({
+ 'X-Publishable-Key': config.pk,
+ 'X-Secret-Key': config.sk,
+ 'X-Satellite': 'true',
+ 'X-Domain': 'example.com',
+ 'Sec-Fetch-Dest': 'document',
+ }),
+ redirect: 'manual',
+ });
+ // Even without satelliteAutoSync, __clerk_synced=false (post sign-in) should trigger handshake
+ expect(res.status).toBe(307);
+ const locationUrl = new URL(res.headers.get('location'));
+ expect(locationUrl.origin + locationUrl.pathname).toBe('https://clerk.example.com/v1/client/handshake');
+ expect(locationUrl.searchParams.get('__clerk_hs_reason')).toBe('satellite-needs-syncing');
+ });
+
+ test('signed out satellite with satelliteAutoSync=true (explicit opt-in) triggers handshake - prod', async () => {
  const config = generateConfig({
  mode: 'live',
  });
@@ -643,7 +659,7 @@ test.describe('Client handshake @generic', () => {
  }),
  redirect: 'manual',
  });
- // Should redirect to handshake with default/true satelliteAutoSync
+ // Should redirect to handshake when satelliteAutoSync is explicitly true
  expect(res.status).toBe(307);
  const locationUrl = new URL(res.headers.get('location'));
  expect(locationUrl.origin + locationUrl.pathname).toBe('https://clerk.example.com/v1/client/handshake');

packages/backend/src/tokens/__tests__/request.test.ts

@@ -651,7 +651,7 @@ describe('tokens.authenticateRequest(options)', () => {
  expect(requestState).toBeSignedOutToAuth();
  });
 
- test('cookieToken: returns handshake when clientUat is missing or equals to 0 and is satellite and not is synced [11y]', async () => {
+ test('cookieToken: returns handshake when clientUat is missing or equals to 0 and is satellite with satelliteAutoSync=true and not is synced [11y]', async () => {
  server.use(
  http.get('https://api.clerk.test/v1/jwks', () => {
  return HttpResponse.json(mockJwks);
@@ -671,6 +671,7 @@ describe('tokens.authenticateRequest(options)', () => {
  isSatellite: true,
  signInUrl: 'https://primary.dev/sign-in',
  domain: 'satellite.dev',
+ satelliteAutoSync: true,
  }),
  );
 
@@ -684,7 +685,7 @@ describe('tokens.authenticateRequest(options)', () => {
  expect(requestState.toAuth()).toBeNull();
  });
 
- test('cookieToken: redirects to signInUrl when is satellite dev and not synced', async () => {
+ test('cookieToken: redirects to signInUrl when is satellite dev with satelliteAutoSync=true and not synced', async () => {
  server.use(
  http.get('https://api.clerk.test/v1/jwks', () => {
  return HttpResponse.json(mockJwks);
@@ -705,6 +706,7 @@ describe('tokens.authenticateRequest(options)', () => {
  isSatellite: true,
  signInUrl: 'https://primary.dev/sign-in',
  domain: 'satellite.dev',
+ satelliteAutoSync: true,
  }),
  );
 
@@ -873,6 +875,114 @@ describe('tokens.authenticateRequest(options)', () => {
  expect(requestState.toAuth()).toBeSignedOutToAuth();
  });
 
+ test('cookieToken: returns signed out without handshake when satelliteAutoSync is not set (defaults to false) and no cookies - prod', async () => {
+ const requestState = await authenticateRequest(
+ mockRequestWithCookies(
+ { ...defaultHeaders, 'sec-fetch-dest': 'document' },
+ { __client_uat: '0' },
+ `http://satellite.example/path`,
+ ),
+ mockOptions({
+ secretKey: 'deadbeef',
+ publishableKey: PK_LIVE,
+ signInUrl: 'https://primary.example/sign-in',
+ isSatellite: true,
+ domain: 'satellite.example',
+ }),
+ );
+
+ expect(requestState).toBeSignedOut({
+ reason: AuthErrorReason.SessionTokenAndUATMissing,
+ isSatellite: true,
+ domain: 'satellite.example',
+ signInUrl: 'https://primary.example/sign-in',
+ });
+ expect(requestState.toAuth()).toBeSignedOutToAuth();
+ expect(requestState.headers.get('location')).toBeNull();
+ });
+
+ test('cookieToken: returns signed out without handshake when satelliteAutoSync is not set (defaults to false) and no cookies - dev', async () => {
+ const requestState = await authenticateRequest(
+ mockRequestWithCookies(
+ { ...defaultHeaders, 'sec-fetch-dest': 'document' },
+ {
+ __client_uat: '0',
+ __clerk_db_jwt: mockJwt,
+ },
+ ),
+ mockOptions({
+ secretKey: 'sk_test_deadbeef',
+ publishableKey: PK_TEST,
+ isSatellite: true,
+ signInUrl: 'https://primary.dev/sign-in',
+ domain: 'satellite.dev',
+ }),
+ );
+
+ expect(requestState).toBeSignedOut({
+ reason: AuthErrorReason.SessionTokenAndUATMissing,
+ isSatellite: true,
+ domain: 'satellite.dev',
+ signInUrl: 'https://primary.dev/sign-in',
+ });
+ expect(requestState.toAuth()).toBeSignedOutToAuth();
+ expect(requestState.headers.get('location')).toBeNull();
+ });
+
+ test('cookieToken: triggers handshake when satelliteAutoSync is not set but __clerk_synced=false is present - prod', async () => {
+ const requestState = await authenticateRequest(
+ mockRequestWithCookies(
+ { ...defaultHeaders, 'sec-fetch-dest': 'document' },
+ { __client_uat: '0' },
+ `http://satellite.example/path?__clerk_synced=false`,
+ ),
+ mockOptions({
+ secretKey: 'deadbeef',
+ publishableKey: PK_LIVE,
+ signInUrl: 'https://primary.example/sign-in',
+ isSatellite: true,
+ domain: 'satellite.example',
+ }),
+ );
+
+ expect(requestState).toMatchHandshake({
+ reason: AuthErrorReason.SatelliteCookieNeedsSyncing,
+ isSatellite: true,
+ domain: 'satellite.example',
+ signInUrl: 'https://primary.example/sign-in',
+ });
+ });
+
+ test('cookieToken: triggers handshake when satelliteAutoSync is not set but __clerk_synced=false is present - dev', async () => {
+ const requestState = await authenticateRequest(
+ mockRequestWithCookies(
+ { ...defaultHeaders, 'sec-fetch-dest': 'document' },
+ {
+ __client_uat: '0',
+ __clerk_db_jwt: mockJwt,
+ },
+ `http://satellite.dev/path?__clerk_synced=false`,
+ ),
+ mockOptions({
+ secretKey: 'sk_test_deadbeef',
+ publishableKey: PK_TEST,
+ signInUrl: 'https://primary.dev/sign-in',
+ isSatellite: true,
+ domain: 'satellite.dev',
+ }),
+ );
+
+ expect(requestState).toMatchHandshake({
+ reason: AuthErrorReason.SatelliteCookieNeedsSyncing,
+ isSatellite: true,
+ domain: 'satellite.dev',
+ signInUrl: 'https://primary.dev/sign-in',
+ });
+ expect(requestState.headers.get('location')).toEqual(
+ `https://primary.dev/sign-in?__clerk_redirect_url=http%3A%2F%2Fexample.com%2Fpath%3F__clerk_synced%3Dfalse`,
+ );
+ });
+
  test('cookieToken: returns handshake when app is not satellite and responds to syncing on dev instances[12y]', async () => {
  const sp = new URLSearchParams();
  sp.set('__clerk_redirect_url', 'http://localhost:3000');

packages/backend/src/tokens/request.ts

@@ -484,7 +484,7 @@ export const authenticateRequest: AuthenticateRequest = (async (
  * - 'false' (NeedsSync): Trigger sync - satellite returning from primary sign-in
  * - 'true' (Completed): Sync done - prevents re-sync loop
  *
- * With satelliteAutoSync=false:
+ * With satelliteAutoSync=false or unset (Core 3 default):
  * - Skip handshake on first visit if no cookies exist (return signedOut immediately)
  * - Trigger handshake when __clerk_synced=false is present (post sign-in redirect)
  * - Allow normal token verification flow when cookies exist (enables refresh)
@@ -499,8 +499,8 @@ export const authenticateRequest: AuthenticateRequest = (async (
  const hasCookies = hasSessionToken || hasActiveClient;
 
  // Determine if we should skip handshake for satellites with no cookies
- // satelliteAutoSync defaults to true, so we only skip when explicitly set to false
- const shouldSkipSatelliteHandshake = authenticateContext.satelliteAutoSync === false && !hasCookies && !needsSync;
+ // satelliteAutoSync defaults to false (Core 3), so we skip unless explicitly set to true
+ const shouldSkipSatelliteHandshake = authenticateContext.satelliteAutoSync !== true && !hasCookies && !needsSync;
 
  if (authenticateContext.instanceType === 'production' && isRequestEligibleForMultiDomainSync && !syncCompleted) {
  // With satelliteAutoSync=false: skip handshake if no cookies and no sync trigger

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

@@ -2386,6 +2386,7 @@ describe('Clerk singleton', () => {
  describe('Clerk().isSatellite and Clerk().domain getters', () => {
  beforeEach(() => {
  mockClientFetch.mockReset();
+ mockClientFetch.mockReturnValue(Promise.resolve({ signedInSessions: [] }));
  mockEnvironmentFetch.mockReturnValue(
  Promise.resolve({
  authConfig: {},

packages/clerk-js/src/core/auth/AuthCookieService.ts

@@ -111,7 +111,7 @@ export class AuthCookieService {
  if (!this.clerk.loaded) {
  return this.clientUat.get() <= 0;
  }
- return !!this.clerk.user;
+ return !this.clerk.user;
  }
 
  public async handleUnauthenticatedDevBrowser() {

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

@@ -2845,10 +2845,9 @@ export class Clerk implements ClerkInterface {
  return true;
  }
 
- // Check if satelliteAutoSync is disabled - if so, skip automatic sync
- // unless explicitly triggered via __clerk_synced=false
- if (this.#options.satelliteAutoSync === false) {
- // Skip automatic sync when satelliteAutoSync is false
+ // Check if satelliteAutoSync is enabled - only auto-sync when explicitly opted in
+ // In Core 3, satelliteAutoSync defaults to false (undefined is treated as false)
+ if (this.#options.satelliteAutoSync !== true) {
  return false;
  }