Initiate user login

Login initiation begins your authentication flow. You redirect users to Scalekit’s hosted login page by creating an authorization URL with appropriate parameters.When users visit this URL, Scalekit’s authorization server validates the request, displays the login interface, and handles authentication through your configured connection methods (SSO, social providers, Magic Link or Email OTP

Authorization URL format

<SCALEKIT_ENVIRONMENT_URL>/oauth/authorize?
  response_type=code& # always `code` for authorization code flow
  client_id=<SCALEKIT_CLIENT_ID>& # Dashboard > Developers > Settings > API Credentials
  redirect_uri=<CALLBACK_URL>& # Dashboard > Authentication > Redirect URLs > Allowed Callback URLs
  scope=openid+profile+email+offline_access& # Permissions requested. Include `offline_access` for refresh tokens
  state=<RANDOM_STATE> # prevent CSRF attacks

The authorization request includes several parameters that control authentication behavior:

• Required parameters ensure Scalekit can identify your application and return the user securely
• Optional parameters enable organization routing and pre-populate fields
• Security parameters prevent unauthorized access attempts

Query parameters

Understand each parameter and how it controls the authorization flow:

Parameter	Required	Description
response_type	Yes	Set to code for authorization code flow. Indicates the expected response type.
client_id	Yes	Your application’s public identifier from the dashboard. Scalekit uses this to identify and validate your application.
redirect_uri	Yes	Your application’s callback URL where Scalekit returns the authorization code. Must be registered in your dashboard settings.
scope	Yes	Space-separated list of permissions. Always include openid profile email. Add offline_access to request refresh tokens for extended sessions.
state	Recommended	Random string generated by your application. Scalekit returns this unchanged. Use it to prevent CSRF attacks and maintain request state.
prompt	Recommended	Value to control the authentication flow. Use login to force re-authentication. Use create to trigger sign up page select_account to select an account if they have multiple accounts
organization_id	Optional	Route user to specific organization’s configured authentication method.
connection_id	Optional	Skip organization selection and direct user to specific SSO connection.
login_hint	Optional	Pre-populate the email field with a hint. Useful for domain-based routing when combined with organization_id.

Set up login flow

1. Add state parameter recommended

   Always generate a cryptographically secure random string for the state parameter and store it temporarily (session, local storage, cache, etc).

   This can be used to validate that the state value returned in the callback matches the original value you sent. This prevents CSRF (Cross-Site Request Forgery) attacks where an attacker tricks users into approving unauthorized authentication requests.

   Node.js

   Generate and store state

   // Generate secure random state
   const state = require('crypto').randomBytes(32).toString('hex');
   // Store it temporarily (session, local storage, cache, etc)
   sessionStorage.oauthState = state;

   Python

   Generate and store state

   import os
   import secrets
   
   # Generate secure random state
   state = secrets.token_hex(32)
   # Store it temporarily (session, local storage, cache, etc)
   session['oauth_state'] = state

   Go

   Generate and store state

   import (
       "crypto/rand"
       "encoding/hex"
   )
   
   // Generate secure random state
   b := make([]byte, 32)
   rand.Read(b)
   state := hex.EncodeToString(b)
   // Store it temporarily (session, local storage, cache, etc)
   // Example for Go: use a storage library
   // session.Set("oauth_state", state)

   Java

   Generate and store state

   import java.security.SecureRandom;
   import java.util.Base64;
   
   // Generate secure random state
   SecureRandom sr = new SecureRandom();
   byte[] randomBytes = new byte[32];
   sr.nextBytes(randomBytes);
   String state = Base64.getUrlEncoder().withoutPadding().encodeToString(randomBytes);
   // Store it temporarily (session, local storage, cache, etc)
   // Example for Java: use any storage library
   // session.setAttribute("oauth_state", state);

2. Redirect to the authorization URL

   Use the Scalekit SDK to generate the authorization URL. It doesn’t make any network requests; it simply returns the URL as a string. Your app can redirect the user to this URL.

   Node.js

   Express.js

   4 collapsed lines
   import { Scalekit } from '@scalekit-sdk/node';
   
   const scalekit = new Scalekit(/* your credentials */);
   
   // Basic authorization URL for general login
   const redirectUri = 'https://yourapp.com/auth/callback';
   const options = {
     scopes: ['openid', 'profile', 'email', 'offline_access'],
     state: sessionStorage.oauthState,
   };
   
   const authorizationUrl = scalekit.getAuthorizationUrl(redirectUri, options);
   
   // Redirect user to Scalekit's hosted login page
   res.redirect(authorizationUrl);

   Python

   Flask

   3 collapsed lines
   from scalekit import ScalekitClient, AuthorizationUrlOptions
   
   scalekit = ScalekitClient(/* your credentials */)
   
   # Basic authorization URL for general login
   redirect_uri = 'https://yourapp.com/auth/callback'
   options = AuthorizationUrlOptions(
       scopes=['openid', 'profile', 'email', 'offline_access'],
       state=session['oauth_state'] # Add this line
   )
   
   authorization_url = scalekit.get_authorization_url(redirect_uri, options)
   
   # Redirect user to Scalekit's hosted login page
   return redirect(authorization_url)

   Go

   Gin

   4 collapsed lines
   import "github.com/scalekit-inc/scalekit-sdk-go"
   
   scalekit := scalekit.NewScalekitClient(/* your credentials */)
   
   // Basic authorization URL for general login
   redirectUri := "https://yourapp.com/auth/callback"
   options := scalekit.AuthorizationUrlOptions{
       Scopes: []string{"openid", "profile", "email", "offline_access"},
       State: "your_generated_state", // Add this line
   }
   
   authorizationUrl, err := scalekit.GetAuthorizationUrl(redirectUri, options)
   
   // Redirect user to Scalekit's hosted login page
   c.Redirect(http.StatusFound, authorizationUrl.String())

   Java

   Spring

   4 collapsed lines
   import com.scalekit.ScalekitClient;
   import com.scalekit.internal.http.AuthorizationUrlOptions;
   
   ScalekitClient scalekit = new ScalekitClient(/* your credentials */);
   
   // Basic authorization URL for general login
   String redirectUri = "https://yourapp.com/auth/callback";
   AuthorizationUrlOptions options = new AuthorizationUrlOptions();
   options.setScopes(Arrays.asList("openid", "profile", "email", "offline_access"));
   options.setState("your_generated_state"); // Add this line
   
   URL authorizationUrl = scalekit.authentication().getAuthorizationUrl(redirectUri, options);
   
   // Redirect user to Scalekit's hosted login page
   return new RedirectView(authorizationUrl.toString());

After the user authenticates:

1. Scalekit generates an authorization code
2. Makes a callback to your registered allowed callback URL
3. Your backend exchanges the code for tokens by making a server-to-server request

This approach keeps sensitive operations server-side and protects your application’s credentials.

Let’s take a look at how to complete the login in the next step.