> **Building with AI coding agents?** Install the authstack plugin with one command. This equips your agent with accurate Scalekit implementation patterns. > > **Recommended**: > ```bash > npx @scalekit-inc/cli setup > ``` > > Global: > ```bash > npm install -g @scalekit-inc/cli > scalekit setup > ``` > > Supports Claude Code, Cursor, GitHub Copilot, Codex + skills for 40+ agents. > Skills: integrating-agentkit, implementing-saaskit, adding-mcp-oauth, implementing-modular-sso, implementing-scim-provisioning. > [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/) --- # SaaSKit: Add auth to my app You'll implement sign-up, login, and logout flows with secure session management and user management included. The foundation you build here extends to features like workspaces, enterprise SSO, MCP authentication, and SCIM provisioning.
See Demo
See the integration in action
Review the authentication sequence Scalekit handles the complex authentication flow while you focus on your core product: ![Full-Stack Authentication Flow](@/assets/docs/fsa/overview/new-1.png) 1. **User initiates sign-in** - Your app redirects to Scalekit's hosted auth page 2. **Identity verification** - User authenticates via their preferred method 3. **Secure callback** - Scalekit returns user profile and session tokens 4. **Session creation** - Your app establishes a secure user session 5. **Protected access** - User accesses your application's features
---- 1. ## Set up Scalekit Use the following instructions to install the SDK for your technology stack. If you haven't already, add your Scalekit credentials to your environment variables file: ```sh showLineNumbers=false title=".env" SCALEKIT_ENVIRONMENT_URL= SCALEKIT_CLIENT_ID= SCALEKIT_CLIENT_SECRET= COOKIE_ENCRYPTION_SECRET= # openssl rand -base64 32 — encrypts the session cookie REDIRECT_URI=http://localhost:3000/callback ``` ### Register redirect URLs for your app You need to register redirect URLs for your application. Go to **Scalekit dashboard** → **Authentication** → **Redirect URLs** and configure: - **Allowed callback URLs**: The endpoint where users are sent after successful authentication to exchange authorization codes and retrieve profile information. [Learn more](/guides/dashboard/redirects/#allowed-callback-urls) - **Initiate login URL**: The endpoint in your app that redirects users to Scalekit’s `/authorize` endpoint. Required when authentication is not initiated from your app, for example, when a user accepts an organization invitation or starts sign-in directly from their identity provider (IdP-initiated SSO). [Learn more](/guides/dashboard/redirects/#initiate-login-url) 2. ## Redirect users to sign up (or) login An authorization URL is an endpoint that redirects users to Scalekit's sign-in page. Use the Scalekit SDK to construct this URL with your redirect URI and required scopes. ```ts title="server.ts" wrap import express from 'express'; import { ScalekitAuth } from '@scalekit-sdk/node/express'; const auth = new ScalekitAuth({ envUrl: process.env.SCALEKIT_ENVIRONMENT_URL, clientId: process.env.SCALEKIT_CLIENT_ID, clientSecret: process.env.SCALEKIT_CLIENT_SECRET, redirectUri: process.env.REDIRECT_URI, cookieEncryptionSecret: process.env.COOKIE_ENCRYPTION_SECRET, }); const app = express(); app.use(auth.router); app.get('/account', auth.requiresAuth, (req, res) => { res.json({ sub: req.scalekitUser?.sub }); }); app.listen(3000); ``` Open `http://localhost:3000/account`. A missing session goes to `/login`. After login, the visitor returns to `/account`. Register `http://localhost:3000/callback` as the dashboard Redirect URI. ```ts title="lib/auth.ts" wrap import { ScalekitClient } from '@scalekit-sdk/node'; import { ScalekitAuthNext } from '@scalekit-sdk/node/next'; const scalekit = new ScalekitClient( process.env.SCALEKIT_ENVIRONMENT_URL!, process.env.SCALEKIT_CLIENT_ID!, process.env.SCALEKIT_CLIENT_SECRET! ); export const auth = new ScalekitAuthNext({ client: scalekit, redirectUri: process.env.REDIRECT_URI!, cookieEncryptionSecret: process.env.COOKIE_ENCRYPTION_SECRET!, }); ``` ```ts title="app/login/route.ts" wrap import { auth } from '../../lib/auth'; export const GET = auth.createLoginHandler(); ``` ```ts title="app/callback/route.ts" wrap import { auth } from '../../lib/auth'; export const GET = auth.createCallbackHandler(); ``` ```ts title="app/logout/route.ts" wrap import { auth } from '../../lib/auth'; export const GET = auth.createLogoutHandler(); ``` ```ts title="app/account/route.ts" wrap import { auth } from '../../lib/auth'; export const GET = auth.withAuth(async (request, { user }) => { return Response.json({ sub: user?.sub }); }); ``` Open `http://localhost:3000/account`. A missing session goes to `/login`. ```bash showLineNumbers=false pip install "scalekit-sdk-python[flask]" ``` ```py title="app.py" wrap import os from flask import Flask from scalekit.frameworks.flask import ScalekitAuth app = Flask(__name__) auth = ScalekitAuth( app, env_url=os.environ["SCALEKIT_ENVIRONMENT_URL"], client_id=os.environ["SCALEKIT_CLIENT_ID"], client_secret=os.environ["SCALEKIT_CLIENT_SECRET"], redirect_uri=os.environ["REDIRECT_URI"], cookie_encryption_secret=os.environ["COOKIE_ENCRYPTION_SECRET"], # HTTP localhost drops a Secure cookie, so the session never sticks. # A missing Secure flag on real HTTP lets the browser send sk_session in cleartext. cookie_secure=False, ) @app.route("/account") @auth.requires_auth def account(): return {"sub": auth.current_user["sub"]} if __name__ == "__main__": app.run(port=3000) ``` Open `http://localhost:3000/account`. A missing session goes to `/login`. Register `http://localhost:3000/callback` as the dashboard Redirect URI. ```bash showLineNumbers=false pip install "scalekit-sdk-python[fastapi]" ``` ```py title="app.py" wrap import os from fastapi import Depends, FastAPI from scalekit.frameworks.fastapi import ScalekitAuth app = FastAPI() auth = ScalekitAuth( env_url=os.environ["SCALEKIT_ENVIRONMENT_URL"], client_id=os.environ["SCALEKIT_CLIENT_ID"], client_secret=os.environ["SCALEKIT_CLIENT_SECRET"], redirect_uri=os.environ["REDIRECT_URI"], cookie_encryption_secret=os.environ["COOKIE_ENCRYPTION_SECRET"], # HTTP localhost drops a Secure cookie, so the session never sticks. # A missing Secure flag on real HTTP lets the browser send sk_session in cleartext. cookie_secure=False, ) auth.install(app) @app.get("/account") async def account(user: dict = Depends(auth.requires_auth)): return {"sub": user["sub"]} ``` ```bash showLineNumbers=false uvicorn app:app --port 3000 ``` Open `http://localhost:3000/account`. Register `http://localhost:3000/callback` as the dashboard Redirect URI. ```go wrap title="internal/http/auth.go" // Must match the allowed callback URL you registered in the dashboard redirectUri := "http://localhost:3000/auth/callback" // Request user profile data (openid, profile, email) and session tracking (offline_access) // offline_access enables refresh tokens so users can stay logged in across sessions options := scalekit.AuthorizationUrlOptions{ Scopes: []string{"openid", "profile", "email", "offline_access"} } authorizationUrl, err := scalekitClient.GetAuthorizationUrl(redirectUri, options) // Generated URL will look like: // https:///oauth/authorize?response_type=code&client_id=skc_1234&scope=openid%20profile%20email%20offline_access&redirect_uri=https%3A%2F%2Fyourapp.com%2Fcallback if err != nil { // Handle error based on your application's error handling strategy panic(err) } c.Redirect(http.StatusFound, authorizationUrl.String()) ``` ```java wrap title="AuthController.java" import com.scalekit.internal.http.AuthorizationUrlOptions; import java.net.URL; import java.util.Arrays; // Must match the allowed callback URL you registered in the dashboard String redirectUri = "http://localhost:3000/auth/callback"; // Request user profile data (openid, profile, email) and session tracking (offline_access) // offline_access enables refresh tokens so users can stay logged in across sessions AuthorizationUrlOptions options = new AuthorizationUrlOptions(); options.setScopes(Arrays.asList("openid", "profile", "email", "offline_access")); URL authorizationUrl = scalekit.authentication().getAuthorizationUrl(redirectUri, options); // Generated URL will look like: // https:///oauth/authorize?response_type=code&client_id=skc_1234&scope=openid%20profile%20email%20offline_access&redirect_uri=https%3A%2F%2Fyourapp.com%2Fcallback ``` This redirects users to Scalekit's managed sign-in page where they can authenticate. The page includes default authentication methods for users to toggle between sign in and sign up. **Match your redirect URLs exactly:** Ensure the redirect URL in your code matches what you configured in the Scalekit dashboard, including protocol (`https://`), domain, port, and path. 3. ## Get user details from the callback After successful authentication, Scalekit creates a user record and sends the user information to your callback endpoint. In authentication flow, Scalekit redirects to your callback URL with an authorization code. Your application exchanges this code for the user's profile information and session tokens. ```ts app.use(auth.router); // GET /callback writes sk_session ``` ```ts title="app/callback/route.ts" import { auth } from '../../lib/auth'; export const GET = auth.createCallbackHandler(); ``` ```py auth = ScalekitAuth(app, ...) # registers GET /callback ``` ```py auth.install(app) # registers GET /callback ``` ```go collapse={1-17, 24-32, 38-46} { 34-37 } "AuthenticateWithCode" title="internal/http/auth_callback.go" package main import ( "log" "net/http" "os" "github.com/gin-gonic/gin" "github.com/scalekit-inc/scalekit-sdk-go" ) // Create Scalekit client instance var scalekitClient = scalekit.NewScalekitClient( os.Getenv("SCALEKIT_ENVIRONMENT_URL"), os.Getenv("SCALEKIT_CLIENT_ID"), os.Getenv("SCALEKIT_CLIENT_SECRET"), ) const redirectUri = "http://localhost:3000/auth/callback" func callbackHandler(c *gin.Context) { code := c.Query("code") errorParam := c.Query("error") errorDescription := c.Query("error_description") if errorParam != "" { c.JSON(http.StatusUnauthorized, gin.H{ "error": errorParam, "error_description": errorDescription, }) return } // Exchange the authorization code for user profile and session tokens // Returns: User (profile info), IdToken (JWT with user claims), AccessToken (JWT with roles/permissions), RefreshToken options := scalekit.AuthenticationOptions{} authResult, err := scalekitClient.AuthenticateWithCode( c.Request.Context(), code, redirectUri, options, ) if err != nil { log.Printf("Error exchanging code: %v", err) c.JSON(http.StatusInternalServerError, gin.H{ "error": "Failed to authenticate user", }) return } user := authResult.User // IdToken: Decode to access full user profile (sub, oid, email, name) // AccessToken: Contains roles and permissions for authorization decisions // RefreshToken: Use to obtain new access tokens when they expire // "user" object contains the user's profile information // Next step: Create a session and log in the user c.Redirect(http.StatusFound, "/dashboard/profile") } ``` ```java collapse={1-10, 40-47, 22-25} wrap "authenticateWithCode" {14,33, 29-31} title="CallbackController.java" import com.scalekit.ScalekitClient; import com.scalekit.internal.http.AuthenticationOptions; import com.scalekit.internal.http.AuthenticationResponse; import org.springframework.web.bind.annotation.*; import org.springframework.web.servlet.view.RedirectView; import org.springframework.http.ResponseEntity; import org.springframework.http.HttpStatus; import java.util.HashMap; import java.util.Map; @RestController public class CallbackController { private final String redirectUri = "http://localhost:3000/auth/callback"; @GetMapping("/auth/callback") public Object callback( @RequestParam(required = false) String code, @RequestParam(required = false) String error, @RequestParam(name = "error_description", required = false) String errorDescription ) { if (error != null) { // handle error } try { // Exchange the authorization code for user profile and session tokens // Returns: user (profile info), idToken (JWT with user claims), accessToken (JWT with roles/permissions), refreshToken AuthenticationOptions options = new AuthenticationOptions(); AuthenticationResponse authResult = scalekit .authentication() .authenticateWithCode(code,redirectUri,options); var user = authResult.getIdTokenClaims(); // idToken: Decode to access full user profile (sub, oid, email, name) // accessToken: Contains roles and permissions for authorization decisions // refreshToken: Use to obtain new access tokens when they expire // "user" object contains the user's profile information // Next step: Create a session and log in the user return new RedirectView("/dashboard/profile"); } catch (Exception err) { // Handle exception (e.g., log error, return error response) } } } ``` The `authResult` object contains: - `user` - Common user details with email, name, and verification status - `idToken` - JWT containing verified full user identity claims (includes: `sub` user ID, `oid` organization ID, `email`, `name`, `exp` expiration) - `accessToken` - Short-lived token that determines current access context (includes: `sub` user ID, `oid` organization ID, `roles`, `permissions`, `exp` expiration) - `refreshToken` - Long-lived token to obtain new access tokens The user details are packaged in the form of JWT tokens. Decode the `idToken` to access full user profile information (email, name, organization ID) and the `accessToken` to check user roles and permissions for authorization decisions. See [Complete login with code exchange](/authenticate/fsa/complete-login/) for detailed token claim references and verification instructions. 4. ## Create and manage user sessions The access token is a JWT that contains the user's permissions and roles. It expires in 5 minutes (default) but [can be configured](/authenticate/fsa/manage-session/#configure-session-security-and-duration). When it expires, use the refresh token to obtain a new access token. The refresh token is long-lived and designed for this purpose. The Scalekit SDK provides methods to refresh access tokens automatically. However, you must log the user out when the refresh token itself expires or becomes invalid. ```ts app.get('/account', auth.requiresAuth, (req, res) => { res.json({ sub: req.scalekitUser?.sub }); }); ``` ```ts title="app/account/route.ts" import { auth } from '../../lib/auth'; export const GET = auth.withAuth(async (request, { user }) => { return Response.json({ sub: user?.sub }); }); ``` ```py @app.route("/account") @auth.requires_auth def account(): return {"sub": auth.current_user["sub"]} ``` ```py @app.get("/account") async def account(user: dict = Depends(auth.requires_auth)): return {"sub": user["sub"]} ``` ```go collapse={1-8} import ( "net/http" "os" ) // Set SameSite mode for CSRF protection c.SetSameSite(http.SameSiteStrictMode) // Store access token in HttpOnly cookie with Path scoping to API routes c.SetCookie( "accessToken", authResult.AccessToken, authResult.ExpiresIn-60, // seconds in Gin "/api", "", os.Getenv("GIN_MODE") == "release", true, ) // Store refresh token in separate HttpOnly cookie with Path scoped to refresh endpoint c.SetCookie( "refreshToken", authResult.RefreshToken, 0, // No expiry for refresh token cookie "/auth/refresh", "", os.Getenv("GIN_MODE") == "release", true, ) ``` ```java collapse={1-6} import javax.servlet.http.Cookie; import javax.servlet.http.HttpServletResponse; // Store access token in HttpOnly cookie with Path scoping to API routes Cookie accessTokenCookie = new Cookie("accessToken", authResult.getAccessToken()); accessTokenCookie.setMaxAge(authResult.getExpiresIn() - 60); // seconds in Spring accessTokenCookie.setHttpOnly(true); accessTokenCookie.setSecure(true); accessTokenCookie.setPath("/api"); response.addCookie(accessTokenCookie); // Store refresh token in separate HttpOnly cookie with Path scoped to refresh endpoint Cookie refreshTokenCookie = new Cookie("refreshToken", authResult.getRefreshToken()); refreshTokenCookie.setHttpOnly(true); refreshTokenCookie.setSecure(true); refreshTokenCookie.setPath("/auth/refresh"); response.addCookie(refreshTokenCookie); response.setHeader("Set-Cookie", response.getHeader("Set-Cookie") + "; SameSite=Strict"); ``` This sets browser cookies with the session tokens. Every request to your backend needs to verify the `accessToken` to ensure the user is authenticated. If expired, use the `refreshToken` to get a new access token. ```ts app.get('/dashboard', auth.requiresAuth, (req, res) => { res.json({ user: req.scalekitUser }); }); ``` ```ts title="middleware.ts" import { auth } from './lib/auth'; export default auth.createMiddleware({ publicRoutes: ['/'], }); export const config = { runtime: 'nodejs', matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'], }; ``` ```py @app.route("/dashboard") @auth.requires_auth def dashboard(): return {"user": auth.current_user} ``` ```py @app.get("/dashboard") async def dashboard(user: dict = Depends(auth.requires_auth)): return {"user": user} ``` ```go wrap collapse={1-5,11-14, 21-25, 34-38, 42-46, 50-54, 58-62, 65-95} import ( "context" "net/http" ) // verifyToken is a middleware that ensures a valid access token or refreshes it if expired. func verifyToken(next http.HandlerFunc) http.HandlerFunc { return func(w http.ResponseWriter, r *http.Request) { // Retrieve the access token from the user's cookie cookie, err := r.Cookie("accessToken") if err != nil { // No access token cookie found; reject the request http.Error(w, `{"message": "No access token provided"}`, http.StatusUnauthorized) return } accessToken := cookie.Value // Decrypt the access token before validation decryptedAccessToken, err := decrypt(accessToken) if err != nil { // Could not decrypt access token; treat as invalid http.Error(w, `{"message": "Token decryption failed"}`, http.StatusUnauthorized) return } // Validate the access token using the Scalekit SDK isValid, err := scalekitClient.ValidateAccessToken(r.Context(), decryptedAccessToken) if err != nil || !isValid { // Access token is invalid or expired // Attempt to retrieve the stored refresh token refreshToken, err := getStoredRefreshToken(r) if err != nil { // No refresh token is available; cannot continue http.Error(w, `{"message": "No refresh token available"}`, http.StatusUnauthorized) return } // Use the refresh token to obtain a new access token from Scalekit tokenResponse, err := scalekitClient.RefreshAccessToken(r.Context(), refreshToken) if err != nil { // Refresh attempt failed; likely an expired or invalid refresh token http.Error(w, `{"message": "Token refresh failed"}`, http.StatusUnauthorized) return } // Save the new refresh token so it can be reused for future requests err = storeRefreshToken(tokenResponse.RefreshToken) if err != nil { // Could not store the new refresh token http.Error(w, `{"message": "Failed to store refresh token"}`, http.StatusInternalServerError) return } // Encrypt the new access token before setting it in the cookie encryptedNewAccessToken, err := encrypt(tokenResponse.AccessToken) if err != nil { // Could not encrypt new access token http.Error(w, `{"message": "Token encryption failed"}`, http.StatusInternalServerError) return } // Issue a new accessToken cookie with updated credentials newCookie := &http.Cookie{ Name: "accessToken", Value: encryptedNewAccessToken, HttpOnly: true, Secure: true, Path: "/", SameSite: http.SameSiteStrictMode, } http.SetCookie(w, newCookie) // Mark the token as valid in the request context and proceed r = r.WithContext(context.WithValue(r.Context(), "tokenValid", true)) } else { // The access token is valid; continue with marked context r = r.WithContext(context.WithValue(r.Context(), "tokenValid", true)) } // Pass the request along to the next handler in the chain next(w, r) } } // dashboardHandler demonstrates a protected route that requires authentication. func dashboardHandler(w http.ResponseWriter, r *http.Request) { w.Header().Set("Content-Type", "application/json") w.Write([]byte(`{ "message": "This is a protected route", "tokenValid": true }`)) } // Usage example: // Attach middleware to the /dashboard route: // http.HandleFunc("/dashboard", verifyToken(dashboardHandler)) ``` ```java wrap collapse={1-6, 53-65} import javax.servlet.http.HttpServletRequest; import javax.servlet.http.HttpServletResponse; import javax.servlet.http.Cookie; import org.springframework.web.servlet.HandlerInterceptor; @Component public class TokenVerificationInterceptor implements HandlerInterceptor { @Override public boolean preHandle( HttpServletRequest request, HttpServletResponse response, Object handler ) throws Exception { try { // Get access token from cookie String accessToken = getCookieValue(request, "accessToken"); String refreshToken = getCookieValue(request, "refreshToken"); // Decrypt the tokens String decryptedAccessToken = decrypt(accessToken); String decryptedRefreshToken = decrypt(refreshToken); // Use Scalekit SDK to validate the token boolean isValid = scalekit.authentication().validateAccessToken(decryptedAccessToken); // Use refreshToken to get a new access token AuthenticationResponse tokenResponse = scalekit .authentication() .refreshToken(decryptedRefreshToken); // Update the cookie with the new access token and refresh token String encryptedNewAccessToken = encrypt(tokenResponse.getAccessToken()); String encryptedNewRefreshToken = encrypt(tokenResponse.getRefreshToken()); Cookie accessTokenCookie = new Cookie("accessToken", encryptedNewAccessToken); accessTokenCookie.setHttpOnly(true); accessTokenCookie.setSecure(true); accessTokenCookie.setPath("/"); response.addCookie(accessTokenCookie); Cookie refreshTokenCookie = new Cookie("refreshToken", encryptedNewRefreshToken); refreshTokenCookie.setHttpOnly(true); refreshTokenCookie.setSecure(true); refreshTokenCookie.setPath("/"); response.addCookie(refreshTokenCookie); return true; } catch (Exception e) { // handle exception } } private String getCookieValue(HttpServletRequest request, String cookieName) { Cookie[] cookies = request.getCookies(); if (cookies != null) { for (Cookie cookie : cookies) { if (cookieName.equals(cookie.getName())) { return cookie.getValue(); } } } return null; } } ``` Authenticated users can access your dashboard. The app enforces session policies using session tokens. To change session policies, go to Dashboard > Authentication > Session Policy in the Scalekit dashboard. 5. ## Log out the user Session persistence depends on the session policy configured in the Scalekit dashboard. To log out a user, clear local session data and invalidate the user's session in Scalekit. ```html Log out ``` ```ts title="app/logout/route.ts" import { auth } from '../../lib/auth'; export const GET = auth.createLogoutHandler(); ``` ```html Log out ``` ```html Log out ``` ```html Log out ``` ```go collapse={1-8} package main import ( "net/http" "github.com/gin-gonic/gin" "github.com/scalekit-inc/scalekit-sdk-go" ) func logoutHandler(c *gin.Context) { // Clear all session data including cookies and local storage clearSessionData() // Generate Scalekit logout URL options := scalekit.LogoutUrlOptions{ IdTokenHint: idToken, PostLogoutRedirectUri: postLogoutRedirectUri, } logoutUrl, err := scalekitClient.GetLogoutUrl(options) if err != nil { c.JSON(http.StatusInternalServerError, gin.H{ "error": "Failed to generate logout URL", }) return } // Redirect to Scalekit's logout endpoint // Note: This is a one-time use URL that becomes invalid after use c.Redirect(http.StatusFound, logoutUrl.String()) } ``` ```java collapse={1-5} {"Clear all session data including cookies and local storage": 11} {"Generate Scalekit logout URL": 14} {"Redirect to Scalekit's logout endpoint": 22} import com.scalekit.internal.http.LogoutUrlOptions; import org.springframework.web.bind.annotation.*; import org.springframework.web.servlet.view.RedirectView; import java.net.URL; @RestController public class LogoutController { @GetMapping("/logout") public RedirectView logout() { clearSessionData(); LogoutUrlOptions options = new LogoutUrlOptions(); options.setIdTokenHint(idToken); options.setPostLogoutRedirectUri(postLogoutRedirectUri); URL logoutUrl = scalekit.authentication() .getLogoutUrl(options); // Note: This is a one-time use URL that becomes invalid after use return new RedirectView(logoutUrl.toString()); } } ``` The logout process completes when Scalekit invalidates the user's session and redirects them to your [registered post-logout URL](/guides/dashboard/redirects/#post-logout-url). This single integration unlocks multiple authentication methods, including Magic Link & OTP, social sign-ins, enterprise single sign-on (SSO), and robust user management features. As you continue working with Scalekit, you'll discover even more features that enhance your authentication workflows. --- ## More Scalekit documentation | Resource | What it contains | When to use it | |----------|-----------------|----------------| | [/llms.txt](/llms.txt) | Structured index with routing hints per product area | Start here — find which documentation set covers your topic before loading full content | | [/llms-full.txt](/llms-full.txt) | Complete documentation for all Scalekit products in one file | Use when you need exhaustive context across multiple products or when the topic spans several areas | | [sitemap-0.xml](https://docs.scalekit.com/sitemap-0.xml) | Full URL list of every documentation page | Use to discover specific page URLs you can fetch for targeted, page-level answers |