Initiate user signup or 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

Understand each parameter and how it controls the authorization flow:

Query parameter	Description
response_type	Set to code for authorization code flow Required Indicates the expected response type
client_id	Your application’s public identifier from the dashboard Required Scalekit uses this to identify and validate your application
redirect_uri	Your application’s callback URL where Scalekit returns the authorization code Required Must be registered in your dashboard settings
scope	Space-separated list of permissions Required Always include openid profile email. Add offline_access to request refresh tokens for extended sessions
state	Random string generated by your application Recommended Scalekit returns this unchanged. Use it to prevent CSRF attacks and maintain request state
prompt	Value to control the authentication flow Optional Use login to force re-authentication even when the user has a valid session. Send it only when you need to re-verify identity — including it on routine logins re-prompts users unnecessarily, a common cause of users appearing logged out Use create to trigger the sign-up page Use select_account to force the organization selector, even if the user has an active session with an organization. The selector appears only when the user belongs to multiple organizations Use none to check silently whether a session exists, without showing the login or sign-up page
organization_id	Skip routing the user to the hosted login page and route them to the enterprise SSO connection configured for the organization Optional
connection_id	Skip routing the user to the hosted login page and route them to a specific enterprise SSO connection Optional
login_hint	Used for Home Realm Discovery. Scalekit extracts the email domain from login_hint and routes the user to the matching organization’s SSO connection based on configured domain rules Optional
provider	Skip routing user to hosted login page and direct user to a specific social connection. Supported values: google, microsoft, github, gitlab, linkedin, and salesforce Optional

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. This method constructs the URL locally without making network requests. Redirect users to this URL to start authentication.

   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()
   options.scopes = ['openid', 'profile', 'email', 'offline_access']
   options.state = session['oauth_state']
   
   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 := scalekitClient.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());

   Scalekit will try to verify the user’s identity and redirect them to your application’s callback URL. If the user is a new user, Scalekit will automatically create a new user account.

Dedicated sign-up flow

To keep sign-up separate from login, use the prompt: 'create' parameter to send users straight to the dedicated sign-up page.

Node.js

Express.js

const redirectUri = 'http://localhost:3000/api/callback';
const options = {
  scopes: ['openid', 'profile', 'email', 'offline_access'],
  prompt: 'create', // explicitly takes you to sign up flow
};
4 collapsed lines

const authorizationUrl = scalekit.getAuthorizationUrl(redirectUri, options);

res.redirect(authorizationUrl);

Python

Flask

from scalekit import AuthorizationUrlOptions

redirect_uri = 'http://localhost:3000/api/callback'
options = AuthorizationUrlOptions()
options.scopes=['openid', 'profile', 'email', 'offline_access']
options.prompt='create'  # optional: explicitly takes you to sign up flow

4 collapsed lines
authorization_url = scalekit.get_authorization_url(redirect_uri, options)

# For web frameworks like Flask/Django:
# return redirect(authorization_url)

Go

Gin

redirectUri := "http://localhost:3000/api/callback"
options := scalekit.AuthorizationUrlOptions{
    Scopes: []string{"openid", "profile", "email", "offline_access"},
    Prompt: "create", // explicitly takes you to sign up flow
}

8 collapsed lines
authorizationUrl, err := scalekitClient.GetAuthorizationUrl(redirectUri, options)
if err != nil {
    // handle error appropriately
    panic(err)
}

// For web frameworks like Gin:
// c.Redirect(http.StatusFound, authorizationUrl.String())

Java

Spring

4 collapsed lines
import com.scalekit.internal.http.AuthorizationUrlOptions;
import java.net.URL;
import java.util.Arrays;

String redirectUri = "http://localhost:3000/api/callback";
AuthorizationUrlOptions options = new AuthorizationUrlOptions();
options.setScopes(Arrays.asList("openid", "profile", "email", "offline_access"));
options.setPrompt("create");

URL authorizationUrl = scalekit.authentication().getAuthorizationUrl(redirectUri, options);

After the user authenticates either in signup or login flows:

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.