Skip to main content

Share sessions across apps

iOS apps and extensions on the same device share one Clerk session when they use the same Keychain service and access group. When a user signs in or out of one app, the other apps use the same session.

Sharing applies only to apps on the same device that belong to the same Apple Developer Team, use the same Clerk , and use the same Keychain service and access group. It doesn't share sessions across devices, developer teams, or Clerk instances.

Warning

The Keychain access group is the trust boundary. Every app in the access group can read and replace the shared session, so add only apps you trust.

Share a session

Before you start

Ensure that every app that should share the session:

  • Uses the same Clerk .
  • Belongs to the same Apple Developer Team.
  • Has the Keychain Sharing capability.
  • Is an app that you trust to access the shared session.

Add the Keychain Sharing capability

In Xcode, select the target that builds each app or extension. Navigate to the Signing & Capabilities tab and select the + Capability option, then add Keychain Sharing.

Add the same Keychain access group

Add the same Keychain group to every target, such as:

Keychain group
$(AppIdentifierPrefix)com.example.shared-auth

After you build each target, inspect its signed entitlements and copy the fully expanded value from the keychain-access-groups array, such as ABCDE12345.com.example.shared-auth. Use that exact value when you configure Clerk. Don't construct the prefix from your Team ID because an app's signed App ID Prefix can differ from its Team ID.

Configure every app

In each app, configure Clerk with the same , Keychain service, and full access group:

import ClerkKit

Clerk.configure(
  publishableKey: "YOUR_PUBLISHABLE_KEY",
  options: .init(
    keychainConfig: .init(
      service: "com.example.shared-auth",
      accessGroup: "ABCDE12345.com.example.shared-auth"
    )
  )
)

Replace the example accessGroup with the exact value from each built app's signed keychain-access-groups entitlement. Every app must use the same fully expanded value.

Warning

The service defaults to the app's bundle identifier. Because sibling apps have different bundle identifiers, you must set the same explicit service in every app.

Test the shared session

Install at least two apps on the same device. Sign in to one app, then open the other app and verify that it uses the same session. Repeat the test after signing out.

Sign-out behavior

Signing out in one app signs out every app that shares the session. signOut() still decides whether all sessions or a specific session is removed. 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.

Tip

Calling Clerk.clearAllKeychainItems() in one app also signs out every app that shares the session.

Security and limitations

  • Only apps on the same device can share a session.
  • Every app must use the same Clerk .
  • Every app must belong to the same Apple Developer Team and Keychain access group.
  • Any app in the Keychain access group can read and replace the shared session.
  • Apps connected to different Clerk instances must not use the same Keychain service and access group, because they would overwrite each other's session. Use a dedicated service and access group for each Clerk instance.

Troubleshoot session sharing

If apps don't share the session, verify that:

Checklist

If an app sets an accessGroup that its entitlements don't include, Clerk logs an error and keeps that app's session private to the app. Add the access group to the app's Keychain Sharing entitlement, then relaunch the app.

Feedback

What did you think of this content?

Last updated on

GitHubEdit on GitHub