Multi-App Authentication

Register multiple applications as OAuth clients that share a single Scalekit user session. Users authenticate once and gain access everywhere across your web app, mobile app, desktop client, and documentation site. Each application gets its own OAuth client with appropriate credentials based on its type, while all apps share the same underlying session.

Check out the example apps

Use multi-app authentication when you ship multiple apps (web, mobile, desktop, or SPA), users expect to stay signed in across surfaces, or you need centralized session control and auditability. Each app gets its own OAuth client for clearer audit logs, safer scope boundaries, and easier maintenance. This eliminates friction from repeated logins and closes security gaps from inconsistent session handling.

How multi-app authentication works

1. Register each application as an OAuth client in Scalekit.
2. User logs into any app.
3. Scalekit creates a session for that user.
4. Other apps detect the session and skip the login prompt.
5. Logging out of any app terminates the shared session.

Each app must clear its own local state

Revoking the Scalekit session does not automatically clear your application’s local state. Each app must clear its own session and stored tokens. A failed refresh token exchange is a reliable signal that the shared session has been revoked. For proactive sign-out across all applications, configure back-channel logout URLs so Scalekit can notify each app when the shared session is terminated.

Application types and authentication flows

Each application is registered separately in Scalekit and receives its own OAuth client. Choose the application type based on whether it has a backend server that can securely store credentials:

App Type	Description	Has Backend?	Uses Secret?	Auth Flow
Web app (Express, Django, Rails)	Server-rendered or backend-driven apps with secure secrets.	✓	✓	Authorization Code
SPA (React, Vue, Angular)	Frontend-only apps running fully in the browser.	✗	✗	Auth Code + PKCE
Mobile (iOS, Android)	iOS or Android apps using system browser flows.	✗	✗	Auth Code + PKCE
Desktop (Electron, Tauri)	Electron or native desktop apps with deep links.	✗	✗	Auth Code + PKCE

Even though each app has a different client_id, they all rely on the same Scalekit user session. Separate clients per app give you clearer audit logs, safer scope boundaries, and easier long-term maintenance.

Implementation steps

1. Create applications in Scalekit — Create applications in Scalekit for each of your apps. During setup, select the app type based on whether it has a backend and needs client secrets.

2. Configure redirect URLs for each app — Redirects are registered endpoints in Scalekit that control where users are sent during authentication flows. Configure redirect URLs for each application.

3. Implement login flow for each app — Once your applications are registered, each app follows an OAuth-based authentication flow. Use the login implementation guide for implementing login/signup flow in your apps.

4. Manage sessions and token refresh — After users successfully authenticate in any of your apps, you receive session tokens that manage their access. Use the session management guide to manage sessions in your apps.

   Validate access tokens on each request

   Validate access tokens by checking the issuer, audience (which must include the application’s client_id), iat, and exp. Store tokens securely, and use the /oauth/token endpoint with the refresh_token grant to obtain new access, refresh, and ID tokens when needed.

5. Implement logout — Initiate logout by calling the /oidc/logout endpoint with the relevant parameters. Clear your local application session when refresh token exchange fails, or configure back-channel logout to proactively sign users out across all applications sharing the same session. Follow the logout implementation guide to implement logout in your apps.

Troubleshooting

Why am I getting a redirect URI mismatch error?

The exact URI (including trailing slashes and query parameters) must match what’s configured in Dashboard > Developers > Applications > [Your App] > Redirects. Common mismatches include:

• http vs https
• Missing or extra trailing slash
• Different port numbers in development

Why aren’t my apps sharing authentication state?

Verify all applications are registered in the same Scalekit environment. Apps in different environments maintain separate session pools and cannot share authentication state.

Why are users prompted to login on every app?

Check the following:

• All apps use the same Scalekit environment URL
• The browser allows third-party cookies (required for session detection)
• The user is using the same browser across apps

Why is the refresh token being rejected?

The Scalekit session may have been revoked from another application, or the refresh token has expired. Redirect the user to log in again to establish a new session.