Share sessions across apps

Shared session sync lets multiple Android applications on the same device share Clerk authentication state. When a user signs in or out of one participating app, Clerk updates the other participating apps when they receive the change, return to the foreground, or launch again.

This feature applies only to apps on the same device that use the same Clerk Publishable Key⁠ and signing certificate. It doesn't share sessions across devices or Clerk instances.

How shared session sync works

Each app stores its own Clerk snapshot and exposes it through a read-only content provider. Clerk discovers providers from sibling apps, verifies that they have the same signing certificate, and ignores snapshots from a different Publishable Key⁠.

Clerk reconciles shared state:

• When the app initializes.
• When a participating app publishes a change.
• When the app returns to the foreground.

What Clerk synchronizes

Clerk synchronizes only the state required to keep authentication consistent:

• The Clerk client and its sessions.
• The Clerk environment.
• The Clerk device token.

Shared session sync doesn't share arbitrary application data.

Enable shared session sync

Before you start

Ensure that every participating app:

• Uses the same Clerk Publishable Key⁠.
• Uses Clerk Android SDK 1.0.36 or later.
• Is signed with the same signing certificate.
• Is an app that you trust to access the shared Clerk state.

package com.example.myclerkapp

import android.app.Application
import com.clerk.api.Clerk
import com.clerk.api.ClerkConfigurationOptions
import com.clerk.api.SharedSessionSyncConfig

class MyClerkApp : Application() {
  override fun onCreate() {
    super.onCreate()

    Clerk.initialize(
      context = this,
      publishableKey = "YOUR_PUBLISHABLE_KEY",
      options = ClerkConfigurationOptions(
        sharedSessionSync = SharedSessionSyncConfig.enabled,
      ),
    )
  }
}

Reload shared state manually

Shared state normally updates automatically. To force reconciliation at another point in your app lifecycle, call Clerk.reloadFromSharedStorage() from a coroutine. It returns true when the in-memory client, environment, or device-token generation changes.

val stateChanged = Clerk.reloadFromSharedStorage()

Sign-out behavior

Shared session sync publishes the client state that results from a sign-out. It doesn't change whether signOut() removes all sessions or a specific session. If your app supports multiple sessions, pass a session ID when you want to remove only that session. For a complete example, see the custom sign-out flow guide.

Security and limitations

• Only apps on the same device can participate.
• Every app must opt in and use the same Clerk Publishable Key⁠.
• Only callers with the same signing certificate can read a shared snapshot.
• The provider is read-only and exposes only Clerk's shared-session snapshot.
• Every app signed with the trusted certificate is inside the shared-session trust boundary.

Troubleshoot shared session sync

If Clerk state doesn't synchronize between apps, verify that: