Web application

Implement Multi-App Authentication for web apps using Authorization Code flow with client_id and client_secret

A web application typically has both a frontend and a backend. In this model, the backend initiates authentication, handles the callback, exchanges the authorization code for tokens, and manages user sessions securely.

This guide covers the authorization code flow for web applications that use a client_id and client_secret.

Prerequisites

Before you begin, ensure you have:

A Scalekit account with an environment configured
Your environment URL (ENV_URL), e.g., https://yourenv.scalekit.com
A web application registered in Scalekit with client_id and client_secret (Create one →)
At least one redirect URL configured in Dashboard > Developers > Applications > [Your App] > Redirects

High-level flow

Step-by-step implementation

Initiate login or signup
Section titled “Initiate login or signup”

Login begins when your backend redirects the user to Scalekit’s hosted login page using the authorization endpoint.
Terminal window
```
1
<ENV_URL>/oauth/authorize?
2
  response_type=code&
3
  client_id=<CLIENT_ID>&
4
  redirect_uri=<CALLBACK_URL>&
5
  scope=openid+profile+email+offline_access&
6
  state=<RANDOM_STATE>
```
For detailed definition of the parameters, refer here
Handle the callback and complete login
Section titled “Handle the callback and complete login”

After authentication, Scalekit redirects the user back to your callback endpoint with code and state.

Your backend must:
- Validate the returned state
- Handle any error parameters
- Exchange the authorization code for tokens
Terminal window
```
1
POST <ENV_URL>/oauth/token
2
Content-Type: application/x-www-form-urlencoded
3

4
grant_type=authorization_code&
5
client_id=<CLIENT_ID>&
6
client_secret=<CLIENT_SECRET>&
7
code=<CODE>&
8
redirect_uri=<CALLBACK_URL>
```
```
1
{
2
  "access_token": "...",
3
  "refresh_token": "...",
4
  "id_token": "...",
5
  "expires_in": 299
6
}
```
Note: Authorization codes are single-use and short-lived.
Manage sessions and token refresh
Section titled “Manage sessions and token refresh”

Once tokens are issued, your web app is responsible for session management.

Token roles
- Access token: short-lived, used for authenticated requests
- Refresh token: used to obtain new tokens
- ID token: user identity claims and required for logout
Typical web apps store tokens in secure cookies and validate the access token on every protected request.

When an access token expires, request new tokens using the refresh token:
Terminal window
```
1
POST <ENV_URL>/oauth/token
2
Content-Type: application/x-www-form-urlencoded
3

4
grant_type=refresh_token&
5
client_id=<CLIENT_ID>&
6
client_secret=<CLIENT_SECRET>&
7
refresh_token=<REFRESH_TOKEN>
```
Validate access tokens by checking:
- Verify the token signature using Scalekit’s public keys (JWKS).
- iss matches your Scalekit environment
- aud matches your client_id
- exp and iat are valid
Public keys for verification are available at:
Terminal window
```
1
<ENV_URL>/keys
```
Implement logout
Section titled “Implement logout”

Logging out requires clearing your application session and invalidating the Scalekit session.

Your logout endpoint should:
- Extract the ID token
- Clear application session cookies
- Redirect the browser to Scalekit’s logout endpoint
Terminal window
```
1
<ENV_URL>/oidc/logout?
2
  id_token_hint=<ID_TOKEN>&
3
  post_logout_redirect_uri=<POST_LOGOUT_REDIRECT_URI>
```
Logout must be performed via a browser redirect so that Scalekit can identify and terminate the session. Additionally, configure backchannel logout URIs to get notified when a logout is performed from another application sharing the same user session.

Handle errors

When authentication fails, Scalekit redirects to your callback URL with error parameters instead of an authorization code:

1
/callback?error=access_denied&error_description=User+denied+access&state=<STATE>

Your callback handler should check for errors before processing the authorization code:

Check if the error parameter exists
Log the error and error_description for debugging
Display a user-friendly message
Provide an option to retry login

Common error codes:

Error	Description
`access_denied`	User denied the authorization request
`invalid_request`	Missing or invalid parameters
`server_error`	Scalekit encountered an unexpected error

(Optional) Use Scalekit Management APIs

In addition to handling user authentication, web applications can also call Scalekit’s Management APIs from the backend. These APIs allow your application to interact with Scalekit-managed resources such as users, organizations, memberships, and roles.

Typical use cases include:

Fetching the currently authenticated user
Listing organizations the user belongs to
Managing organization membership or roles

Management APIs are Scalekit-owned APIs and are intended to be called server-side only. To use Management APIs, the application must explicitly allow it:

Go to app.scalekit.com
Navigate to Developers → Applications
Select your Web Application
Enable Allow Scalekit Management API Access

This option is available only for web applications, since they can securely store credentials. When enabled, your backend can authenticate to Scalekit’s Management APIs using the application’s credentials and SDKs provided by Scalekit. These calls are independent of end-user access tokens and are designed for trusted, server-side workflows.

What’s next

Configure backchannel logout to receive notifications when a user logs out from another app
Set up a custom domain for your authentication pages
Add enterprise SSO to support SAML and OIDC with your customers’ identity providers

Web application

Prerequisites

High-level flow

Step-by-step implementation

Initiate login or signup

Handle the callback and complete login

Manage sessions and token refresh

Implement logout

Handle errors

(Optional) Use Scalekit Management APIs

What’s next