SaaSKit Complete: Complete SaaSKit documentation including FSA, SSO, SCIM, user management, and authorization --- # DOCUMENT BOUNDARY --- # Role based access control (RBAC) > Control what authenticated users can access in your application based on their roles and permissions When users access features in your application, your app needs to control what actions they can perform. These permissions might be set by your app as defaults or by organization administrators. For example, in a project management application, you can allow some users to create projects while restricting others to only view existing projects. Role-based access control (RBAC) provides the framework to implement these permissions systematically. After users authenticate through Scalekit, your application receives an access token containing their roles and permissions. Use this token to make authorization decisions and control access to features and resources. Access tokens contain two key components for authorization: **Roles** group related permissions together and define what users can do in your system. Common examples include Admin, Manager, Editor, and Viewer. Roles can inherit permissions from other roles, creating hierarchical access levels. **Permissions** represent specific actions users can perform, formatted as `resource:action` patterns like `projects:create` or `tasks:read`. Use permissions for granular access control when you need precise control over individual capabilities. Access token contents ```json { "aud": ["skc_987654321098765432"], "client_id": "skc_987654321098765432", "exp": 1750850145, "iat": 1750849845, "iss": "http://example.localhost:8889", "jti": "tkn_987654321098765432", "nbf": 1750849845, "roles": ["project_manager", "member"], "oid": "org_69615647365005430", "permissions": ["projects:create", "projects:read", "tasks:assign"], "sid": "ses_987654321098765432", "sub": "usr_987654321098765432" } ``` Scalekit automatically assigns the `admin` role to the first user in each organization and the `member` role to subsequent users. Your application uses the role and permission information from Scalekit to make final authorization decisions at runtime. Start by defining the roles and permissions your application needs. --- # DOCUMENT BOUNDARY --- # Multi-App Authentication > Share authentication across web, mobile, and desktop applications with a unified session 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 ](https://github.com/scalekit-inc/multiapp-demo) 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 [Section titled “How multi-app authentication works”](#how-multi-app-authentication-works) 1. [Register](/authenticate/fsa/multiapp/manage-apps/) 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. ## Application types and authentication flows [Section titled “Application types and authentication flows”](#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)](/authenticate/fsa/multiapp/web-app) | Server-rendered or backend-driven apps with secure secrets. | ✓ | ✓ | Authorization Code | | [**SPA** (React, Vue, Angular)](/authenticate/fsa/multiapp/single-page-app) | Frontend-only apps running fully in the browser. | ✗ | ✗ | Auth Code + PKCE | | [**Mobile** (iOS, Android)](/authenticate/fsa/multiapp/native-app) | iOS or Android apps using system browser flows. | ✗ | ✗ | Auth Code + PKCE | | [**Desktop** (Electron, Tauri)](/authenticate/fsa/multiapp/native-app) | 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 [Section titled “Implementation steps”](#implementation-steps) 1. **Create applications in Scalekit** — [Create applications](/authenticate/fsa/multiapp/manage-apps) 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](/authenticate/fsa/multiapp/manage-apps/#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](/authenticate/fsa/implement-login/) 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](/authenticate/fsa/manage-session/) to manage sessions in your apps. 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](/authenticate/fsa/logout/) to implement logout in your apps. ## Troubleshooting [Section titled “Troubleshooting”](#troubleshooting) --- # DOCUMENT BOUNDARY --- # SaaSKit: Add auth to my app > SaaSKit — Hosted auth pages, managed sessions, secure logout. Purpose built. Simple where it counts 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. ### Build with a coding agent * Claude Code ```bash /plugin marketplace add scalekit-inc/claude-code-authstack ``` ```bash /plugin install full-stack-auth@scalekit-auth-stack ``` * Codex ```bash curl -fsSL https://raw.githubusercontent.com/scalekit-inc/codex-authstack/main/install.sh | bash ``` ```bash # Restart Codex # Plugin Directory -> Scalekit Auth Stack -> install full-stack-auth ``` * GitHub Copilot CLI ```bash copilot plugin marketplace add scalekit-inc/github-copilot-authstack ``` ```bash copilot plugin install full-stack-auth@scalekit-auth-stack ``` * 40+ agents ```bash npx skills add scalekit-inc/skills --skill implementing-scalekit-fsa ``` [Continue building with AI →](/dev-kit/build-with-ai/full-stack-auth/) *** 1. ## Set up Scalekit [Section titled “Set up Scalekit”](#set-up-scalekit) Use the following instructions to install the SDK for your technology stack. * Node.js ```bash npm install @scalekit-sdk/node ``` * Python ```sh pip install scalekit-sdk-python ``` * Go ```sh go get -u github.com/scalekit-inc/scalekit-sdk-go ``` * Java ```groovy /* Gradle users - add the following to your dependencies in build file */ implementation "com.scalekit:scalekit-sdk-java:2.0.11" ``` ```xml com.scalekit scalekit-sdk-java 2.0.11 ``` If you haven’t already, add your Scalekit credentials to your environment variables file: .env ```sh SCALEKIT_ENVIRONMENT_URL= SCALEKIT_CLIENT_ID= SCALEKIT_CLIENT_SECRET= ``` ### Register redirect URLs for your app [Section titled “Register redirect URLs for your app”](#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 [Section titled “Redirect users to sign up (or) login”](#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. * Node.js routes/auth.ts ```javascript 1 // Must match the allowed callback URL you registered in the dashboard 2 const redirectUri = 'http://localhost:3000/auth/callback'; 3 4 // Request user profile data (openid, profile, email) and session tracking (offline_access) 5 // offline_access enables refresh tokens so users can stay logged in across sessions 6 const options = { 7 scopes: ['openid', 'profile', 'email', 'offline_access'] 8 }; 9 10 const authorizationUrl = scalekit.getAuthorizationUrl(redirectUri, options); 11 // Generated URL will look like: 12 // https:///oauth/authorize?response_type=code&client_id=skc_1234&scope=openid%20profile%20email%20offline_access&redirect_uri=https%3A%2F%2Fyourapp.com%2Fauth%2Fcallback 13 14 res.redirect(authorizationUrl); ``` * Python app/auth/routes.py ```python 1 from scalekit import AuthorizationUrlOptions 2 3 # Must match the allowed callback URL you registered in the dashboard 4 redirect_uri = 'http://localhost:3000/auth/callback' 5 6 # Request user profile data (openid, profile, email) and session tracking (offline_access) 7 # offline_access enables refresh tokens so users can stay logged in across sessions 8 options = AuthorizationUrlOptions() 9 options.scopes = ['openid', 'profile', 'email', 'offline_access'] 10 11 12 authorization_url = scalekit.get_authorization_url(redirect_uri, options) 13 # Generated URL will look like: 14 # https:///oauth/authorize?response_type=code&client_id=skc_1234&scope=openid%20profile%20email%20offline_access&redirect_uri=https%3A%2F%2Fyourapp.com%2Fcallback 15 16 return redirect(authorization_url) ``` * Go internal/http/auth.go ```go 1 // Must match the allowed callback URL you registered in the dashboard 2 redirectUri := "http://localhost:3000/auth/callback" 3 4 // Request user profile data (openid, profile, email) and session tracking (offline_access) 5 // offline_access enables refresh tokens so users can stay logged in across sessions 6 options := scalekit.AuthorizationUrlOptions{ 7 Scopes: []string{"openid", "profile", "email", "offline_access"} 8 } 9 10 authorizationUrl, err := scalekitClient.GetAuthorizationUrl(redirectUri, options) 11 // Generated URL will look like: 12 // https:///oauth/authorize?response_type=code&client_id=skc_1234&scope=openid%20profile%20email%20offline_access&redirect_uri=https%3A%2F%2Fyourapp.com%2Fcallback 13 if err != nil { 14 // Handle error based on your application's error handling strategy 15 panic(err) 16 } 17 18 c.Redirect(http.StatusFound, authorizationUrl.String()) ``` * Java AuthController.java ```java 1 import com.scalekit.internal.http.AuthorizationUrlOptions; 2 import java.net.URL; 3 import java.util.Arrays; 4 5 // Must match the allowed callback URL you registered in the dashboard 6 String redirectUri = "http://localhost:3000/auth/callback"; 7 8 // Request user profile data (openid, profile, email) and session tracking (offline_access) 9 // offline_access enables refresh tokens so users can stay logged in across sessions 10 AuthorizationUrlOptions options = new AuthorizationUrlOptions(); 11 options.setScopes(Arrays.asList("openid", "profile", "email", "offline_access")); 12 13 URL authorizationUrl = scalekit.authentication().getAuthorizationUrl(redirectUri, options); 14 // Generated URL will look like: 15 // 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. 3. ## Get user details from the callback [Section titled “Get user details from the callback”](#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. * Node.js routes/auth-callback.ts ```javascript 1 import scalekit from '@/utils/auth.js' 2 const redirectUri = ''; 3 4 // Get the authorization code from the scalekit initiated callback 5 app.get('/auth/callback', async (req, res) => { 6 const { code, error, error_description } = req.query; 7 8 if (error) { 9 return res.status(401).json({ error, error_description }); 10 } 11 12 try { 13 // Exchange the authorization code for user profile and session tokens 14 // Returns: user (profile info), idToken (JWT with user claims), accessToken (JWT with roles/permissions), refreshToken 15 const authResult = await scalekit.authenticateWithCode( 16 code, redirectUri 17 ); 18 19 const { user, idToken, accessToken, refreshToken } = authResult; 20 // idToken: Decode to access full user profile (sub, oid, email, name) 21 // accessToken: Contains roles and permissions for authorization decisions 22 // refreshToken: Use to obtain new access tokens when they expire 23 24 // "user" object contains the user's profile information 25 // Next step: Create a session and log in the user 26 res.redirect('/dashboard/profile'); 27 } catch (err) { 28 console.error('Error exchanging code:', err); 29 res.status(500).json({ error: 'Failed to authenticate user' }); 30 } 31 }); ``` * Python app/auth/callback.py ```python 1 from flask import Flask, request, redirect, jsonify 2 from scalekit import ScalekitClient, CodeAuthenticationOptions 3 4 app = Flask(__name__) 5 # scalekit imported from your auth utils 6 7 redirect_uri = 'http://localhost:3000/auth/callback' 8 9 @app.route('/auth/callback') 10 def callback(): 11 code = request.args.get('code') 12 error = request.args.get('error') 13 error_description = request.args.get('error_description') 14 15 if error: 16 return jsonify({'error': error, 'error_description': error_description}), 401 17 18 try: 19 # Exchange the authorization code for user profile and session tokens 20 # Returns: user (profile info), id_token (JWT with user claims), access_token (JWT with roles/permissions), refresh_token 21 options = CodeAuthenticationOptions() 22 auth_result = scalekit.authenticate_with_code( 23 code, redirect_uri, options 24 ) 25 26 user = auth_result["user"] 27 # id_token: Decode to access full user profile (sub, oid, email, name) 28 # access_token: Contains roles and permissions for authorization decisions 29 # refresh_token: Use to obtain new access tokens when they expire 30 31 # "user" object contains the user's profile information 32 # Next step: Create a session and log in the user 33 return redirect('/dashboard/profile') 34 except Exception as err: 35 print(f'Error exchanging code: {err}') 36 return jsonify({'error': 'Failed to authenticate user'}), 500 ``` * Go internal/http/auth\_callback.go ```go 1 package main 2 3 import ( 4 "log" 5 "net/http" 6 "os" 7 "github.com/gin-gonic/gin" 8 "github.com/scalekit-inc/scalekit-sdk-go" 9 ) 10 11 // Create Scalekit client instance 12 var scalekitClient = scalekit.NewScalekitClient( 13 os.Getenv("SCALEKIT_ENVIRONMENT_URL"), 14 os.Getenv("SCALEKIT_CLIENT_ID"), 15 os.Getenv("SCALEKIT_CLIENT_SECRET"), 16 ) 17 18 const redirectUri = "http://localhost:3000/auth/callback" 19 20 func callbackHandler(c *gin.Context) { 21 code := c.Query("code") 22 errorParam := c.Query("error") 23 errorDescription := c.Query("error_description") 24 25 if errorParam != "" { 26 c.JSON(http.StatusUnauthorized, gin.H{ 27 "error": errorParam, 28 "error_description": errorDescription, 29 }) 30 return 31 } 32 33 // Exchange the authorization code for user profile and session tokens 34 // Returns: User (profile info), IdToken (JWT with user claims), AccessToken (JWT with roles/permissions), RefreshToken 35 options := scalekit.AuthenticationOptions{} 36 authResult, err := scalekitClient.AuthenticateWithCode( 37 c.Request.Context(), code, redirectUri, options, 38 ) 39 40 if err != nil { 41 log.Printf("Error exchanging code: %v", err) 42 c.JSON(http.StatusInternalServerError, gin.H{ 43 "error": "Failed to authenticate user", 44 }) 45 return 46 } 47 48 user := authResult.User 49 // IdToken: Decode to access full user profile (sub, oid, email, name) 50 // AccessToken: Contains roles and permissions for authorization decisions 51 // RefreshToken: Use to obtain new access tokens when they expire 52 53 // "user" object contains the user's profile information 54 // Next step: Create a session and log in the user 55 c.Redirect(http.StatusFound, "/dashboard/profile") 56 } ``` * Java CallbackController.java ```java 1 import com.scalekit.ScalekitClient; 2 import com.scalekit.internal.http.AuthenticationOptions; 3 import com.scalekit.internal.http.AuthenticationResponse; 4 import org.springframework.web.bind.annotation.*; 5 import org.springframework.web.servlet.view.RedirectView; 6 import org.springframework.http.ResponseEntity; 7 import org.springframework.http.HttpStatus; 8 import java.util.HashMap; 9 import java.util.Map; 10 11 @RestController 12 public class CallbackController { 13 14 private final String redirectUri = "http://localhost:3000/auth/callback"; 15 16 @GetMapping("/auth/callback") 17 public Object callback( 18 @RequestParam(required = false) String code, 19 @RequestParam(required = false) String error, 20 @RequestParam(name = "error_description", required = false) String errorDescription 21 ) { 22 if (error != null) { 23 // handle error 24 } 25 26 try { 27 // Exchange the authorization code for user profile and session tokens 28 // Returns: user (profile info), idToken (JWT with user claims), accessToken (JWT with roles/permissions), refreshToken 29 AuthenticationOptions options = new AuthenticationOptions(); 30 AuthenticationResponse authResult = scalekit 31 .authentication() 32 .authenticateWithCode(code,redirectUri,options); 33 34 var user = authResult.getIdTokenClaims(); 35 // idToken: Decode to access full user profile (sub, oid, email, name) 36 // accessToken: Contains roles and permissions for authorization decisions 37 // refreshToken: Use to obtain new access tokens when they expire 38 39 // "user" object contains the user's profile information 40 // Next step: Create a session and log in the user 41 return new RedirectView("/dashboard/profile"); 42 43 } catch (Exception err) { 44 // Handle exception (e.g., log error, return error response) 45 } 46 } 47 } ``` 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 - Auth result ```js 1 { 2 user: { 3 email: "john.doe@example.com", 4 emailVerified: true, 5 givenName: "John", 6 name: "John Doe", 7 id: "usr_74599896446906854" 8 }, 9 idToken: "eyJhbGciO..", // Decode for full user details 10 11 accessToken: "eyJhbGciOi..", 12 refreshToken: "rt_8f7d6e5c4b3a2d1e0f9g8h7i6j..", 13 expiresIn: 299 // in seconds 14 } ``` - Decoded ID token ID token decoded ```json 1 { 2 "at_hash": "ec_jU2ZKpFelCKLTRWiRsg", 3 "aud": [ 4 "skc_58327482062864390" 5 ], 6 "azp": "skc_58327482062864390", 7 "c_hash": "6wMreK9kWQQY6O5R0CiiYg", 8 "client_id": "skc_58327482062864390", 9 "email": "john.doe@example.com", 10 "email_verified": true, 11 "exp": 1742975822, 12 "family_name": "Doe", 13 "given_name": "John", 14 "iat": 1742974022, 15 "iss": "https://scalekit-z44iroqaaada-dev.scalekit.cloud", 16 "name": "John Doe", 17 "oid": "org_59615193906282635", 18 "sid": "ses_65274187031249433", 19 "sub": "usr_63261014140912135" 20 } ``` - Decoded access token Decoded access token ```json 1 { 2 "aud": [ 3 "prd_skc_7848964512134X699" 4 ], 5 "client_id": "prd_skc_7848964512134X699", 6 "exp": 1758265247, 7 "iat": 1758264947, 8 "iss": "https://login.devramp.ai", 9 "jti": "tkn_90928731115292X63", 10 "nbf": 1758264947, 11 "oid": "org_89678001X21929734", 12 "permissions": [ 13 "workspace_data:write", 14 "workspace_data:read" 15 ], 16 "roles": [ 17 "admin" 18 ], 19 "sid": "ses_90928729571723X24", 20 "sub": "usr_8967800122X995270", 21 // External identifiers if updated on Scalekit 22 "xoid": "ext_org_123", // Organization ID 23 "xuid": "ext_usr_456", // User ID 24 } ``` 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 [Section titled “Create and manage user sessions”](#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. * Node.js ```javascript 1 import cookieParser from 'cookie-parser'; 2 // Set cookie parser middleware 3 app.use(cookieParser()); 4 5 // Store access token in HttpOnly cookie with Path scoping to API routes 6 res.cookie('accessToken', authResult.accessToken, { 7 maxAge: (authResult.expiresIn - 60) * 1000, 8 httpOnly: true, 9 secure: true, 10 path: '/api', 11 sameSite: 'strict' 12 }); 13 14 // Store refresh token in separate HttpOnly cookie with Path scoped to refresh endpoint 15 res.cookie('refreshToken', authResult.refreshToken, { 16 httpOnly: true, 17 secure: true, 18 path: '/auth/refresh', 19 sameSite: 'strict' 20 }); ``` * Python ```python 1 from flask import Flask, make_response 2 import os 3 4 # Cookie parsing is built-in with Flask's request object 5 app = Flask(__name__) 6 7 response = make_response() 8 9 # Store access token in HttpOnly cookie with Path scoping to API routes 10 response.set_cookie( 11 'accessToken', 12 auth_result.access_token, 13 max_age=auth_result.expires_in - 60, # seconds in Flask 14 httponly=True, 15 secure=True, 16 path='/api', 17 samesite='Strict' 18 ) 19 20 # Store refresh token in separate HttpOnly cookie with Path scoped to refresh endpoint 21 response.set_cookie( 22 'refreshToken', 23 auth_result.refresh_token, 24 httponly=True, 25 secure=True, 26 path='/auth/refresh', 27 samesite='Strict' 28 ) ``` * Go ```go 1 import ( 2 "net/http" 3 "os" 4 ) 5 6 // Set SameSite mode for CSRF protection 7 c.SetSameSite(http.SameSiteStrictMode) 8 9 // Store access token in HttpOnly cookie with Path scoping to API routes 10 c.SetCookie( 11 "accessToken", 12 authResult.AccessToken, 13 authResult.ExpiresIn-60, // seconds in Gin 14 "/api", 15 "", 16 os.Getenv("GIN_MODE") == "release", 17 true, 18 ) 19 20 // Store refresh token in separate HttpOnly cookie with Path scoped to refresh endpoint 21 c.SetCookie( 22 "refreshToken", 23 authResult.RefreshToken, 24 0, // No expiry for refresh token cookie 25 "/auth/refresh", 26 "", 27 os.Getenv("GIN_MODE") == "release", 28 true, 29 ) ``` * Java ```java 1 import javax.servlet.http.Cookie; 2 import javax.servlet.http.HttpServletResponse; 3 4 // Store access token in HttpOnly cookie with Path scoping to API routes 5 Cookie accessTokenCookie = new Cookie("accessToken", authResult.getAccessToken()); 6 accessTokenCookie.setMaxAge(authResult.getExpiresIn() - 60); // seconds in Spring 7 accessTokenCookie.setHttpOnly(true); 8 accessTokenCookie.setSecure(true); 9 accessTokenCookie.setPath("/api"); 10 response.addCookie(accessTokenCookie); 11 12 // Store refresh token in separate HttpOnly cookie with Path scoped to refresh endpoint 13 Cookie refreshTokenCookie = new Cookie("refreshToken", authResult.getRefreshToken()); 14 refreshTokenCookie.setHttpOnly(true); 15 refreshTokenCookie.setSecure(true); 16 refreshTokenCookie.setPath("/auth/refresh"); 17 response.addCookie(refreshTokenCookie); 18 response.setHeader("Set-Cookie", 19 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. * Node.js ```javascript 1 // Middleware to verify and refresh tokens if needed 2 const verifyToken = async (req, res, next) => { 3 try { 4 // Get access token from cookie and decrypt it 5 const accessToken = req.cookies.accessToken; 6 const decryptedAccessToken = decrypt(accessToken); 7 8 if (!accessToken) { 9 return res.status(401).json({ message: 'No access token provided' }); 10 } 11 12 // Use Scalekit SDK to validate the token 13 const isValid = await scalekit.validateAccessToken(decryptedAccessToken); 14 15 if (!isValid) { 16 // Use stored refreshToken to get a new access token 17 const { 18 user, 19 idToken, 20 accessToken, 21 refreshToken: newRefreshToken, 22 } = await scalekit.refreshAccessToken(refreshToken); 23 24 // Store the new refresh token 25 // Update the cookie with the new access token 26 } 27 next(); 28 }; 29 30 // Example of using the middleware to protect routes 31 app.get('/dashboard', verifyToken, (req, res) => { 32 // The user object is now available in req.user 33 res.json({ 34 message: 'This is a protected route', 35 user: req.user 36 }); 37 }); ``` * Python ```python 1 from functools import wraps 2 from flask import request, jsonify, make_response 3 4 def verify_token(f): 5 """Decorator to verify and refresh tokens if needed""" 6 @wraps(f) 7 def decorated_function(*args, **kwargs): 8 try: 9 # Get access token from cookie 10 access_token = request.cookies.get('accessToken') 11 12 if not access_token: 13 return jsonify({'message': 'No access token provided'}), 401 14 15 # Decrypt the accessToken using the same encryption algorithm 16 decrypted_access_token = decrypt(access_token) 17 18 # Use Scalekit SDK to validate the token 19 is_valid = scalekit.validate_access_token(decrypted_access_token) 20 21 if not is_valid: 22 # Get stored refresh token 23 refresh_token = get_stored_refresh_token() 24 25 if not refresh_token: 26 return jsonify({'message': 'No refresh token available'}), 401 27 28 # Use stored refreshToken to get a new access token 29 token_response = scalekit.refresh_access_token(refresh_token) 30 31 # Python SDK returns dict with access_token and refresh_token 32 new_access_token = token_response.get('access_token') 33 new_refresh_token = token_response.get('refresh_token') 34 35 # Store the new refresh token 36 store_refresh_token(new_refresh_token) 37 38 # Update the cookie with the new access token 39 encrypted_new_access_token = encrypt(new_access_token) 40 response = make_response(f(*args, **kwargs)) 41 response.set_cookie( 42 'accessToken', 43 encrypted_new_access_token, 44 httponly=True, 45 secure=True, 46 path='/', 47 samesite='Strict' 48 ) 49 50 return response 51 52 # If the token was valid we just invoke the view as-is 53 return f(*args, **kwargs) 54 55 except Exception as e: 56 return jsonify({'message': f'Token verification failed: {str(e)}'}), 401 57 58 return decorated_function 59 60 # Example of using the decorator to protect routes 61 @app.route('/dashboard') 62 @verify_token 63 def dashboard(): 64 return jsonify({ 65 'message': 'This is a protected route', 66 'user': getattr(request, 'user', None) 67 }) ``` * Go ```go 1 import ( 2 "context" 3 "net/http" 4 ) 5 6 // verifyToken is a middleware that ensures a valid access token or refreshes it if expired. 7 func verifyToken(next http.HandlerFunc) http.HandlerFunc { 8 return func(w http.ResponseWriter, r *http.Request) { 9 // Retrieve the access token from the user's cookie 10 cookie, err := r.Cookie("accessToken") 11 if err != nil { 12 // No access token cookie found; reject the request 13 http.Error(w, `{"message": "No access token provided"}`, http.StatusUnauthorized) 14 return 15 } 16 17 accessToken := cookie.Value 18 19 // Decrypt the access token before validation 20 decryptedAccessToken, err := decrypt(accessToken) 21 if err != nil { 22 // Could not decrypt access token; treat as invalid 23 http.Error(w, `{"message": "Token decryption failed"}`, http.StatusUnauthorized) 24 return 25 } 26 27 // Validate the access token using the Scalekit SDK 28 isValid, err := scalekitClient.ValidateAccessToken(r.Context(), decryptedAccessToken) 29 if err != nil || !isValid { 30 // Access token is invalid or expired 31 32 // Attempt to retrieve the stored refresh token 33 refreshToken, err := getStoredRefreshToken(r) 34 if err != nil { 35 // No refresh token is available; cannot continue 36 http.Error(w, `{"message": "No refresh token available"}`, http.StatusUnauthorized) 37 return 38 } 39 40 // Use the refresh token to obtain a new access token from Scalekit 41 tokenResponse, err := scalekitClient.RefreshAccessToken(r.Context(), refreshToken) 42 if err != nil { 43 // Refresh attempt failed; likely an expired or invalid refresh token 44 http.Error(w, `{"message": "Token refresh failed"}`, http.StatusUnauthorized) 45 return 46 } 47 48 // Save the new refresh token so it can be reused for future requests 49 err = storeRefreshToken(tokenResponse.RefreshToken) 50 if err != nil { 51 // Could not store the new refresh token 52 http.Error(w, `{"message": "Failed to store refresh token"}`, http.StatusInternalServerError) 53 return 54 } 55 56 // Encrypt the new access token before setting it in the cookie 57 encryptedNewAccessToken, err := encrypt(tokenResponse.AccessToken) 58 if err != nil { 59 // Could not encrypt new access token 60 http.Error(w, `{"message": "Token encryption failed"}`, http.StatusInternalServerError) 61 return 62 } 63 64 // Issue a new accessToken cookie with updated credentials 65 newCookie := &http.Cookie{ 66 Name: "accessToken", 67 Value: encryptedNewAccessToken, 68 HttpOnly: true, 69 Secure: true, 70 Path: "/", 71 SameSite: http.SameSiteStrictMode, 72 } 73 http.SetCookie(w, newCookie) 74 75 // Mark the token as valid in the request context and proceed 76 r = r.WithContext(context.WithValue(r.Context(), "tokenValid", true)) 77 } else { 78 // The access token is valid; continue with marked context 79 r = r.WithContext(context.WithValue(r.Context(), "tokenValid", true)) 80 } 81 82 // Pass the request along to the next handler in the chain 83 next(w, r) 84 } 85 } 86 87 // dashboardHandler demonstrates a protected route that requires authentication. 88 func dashboardHandler(w http.ResponseWriter, r *http.Request) { 89 w.Header().Set("Content-Type", "application/json") 90 w.Write([]byte(`{ 91 "message": "This is a protected route", 92 "tokenValid": true 93 }`)) 94 } 95 96 // Usage example: 97 // Attach middleware to the /dashboard route: 98 // http.HandleFunc("/dashboard", verifyToken(dashboardHandler)) ``` * Java ```java 1 import javax.servlet.http.HttpServletRequest; 2 import javax.servlet.http.HttpServletResponse; 3 import javax.servlet.http.Cookie; 4 import org.springframework.web.servlet.HandlerInterceptor; 5 6 @Component 7 public class TokenVerificationInterceptor implements HandlerInterceptor { 8 @Override 9 public boolean preHandle( 10 HttpServletRequest request, 11 HttpServletResponse response, 12 Object handler 13 ) throws Exception { 14 try { 15 // Get access token from cookie 16 String accessToken = getCookieValue(request, "accessToken"); 17 String refreshToken = getCookieValue(request, "refreshToken"); 18 19 // Decrypt the tokens 20 String decryptedAccessToken = decrypt(accessToken); 21 String decryptedRefreshToken = decrypt(refreshToken); 22 23 // Use Scalekit SDK to validate the token 24 boolean isValid = scalekit.authentication().validateAccessToken(decryptedAccessToken); 25 26 27 // Use refreshToken to get a new access token 28 AuthenticationResponse tokenResponse = scalekit 29 .authentication() 30 .refreshToken(decryptedRefreshToken); 31 32 // Update the cookie with the new access token and refresh token 33 String encryptedNewAccessToken = encrypt(tokenResponse.getAccessToken()); 34 String encryptedNewRefreshToken = encrypt(tokenResponse.getRefreshToken()); 35 36 Cookie accessTokenCookie = new Cookie("accessToken", encryptedNewAccessToken); 37 accessTokenCookie.setHttpOnly(true); 38 accessTokenCookie.setSecure(true); 39 accessTokenCookie.setPath("/"); 40 response.addCookie(accessTokenCookie); 41 42 Cookie refreshTokenCookie = new Cookie("refreshToken", encryptedNewRefreshToken); 43 refreshTokenCookie.setHttpOnly(true); 44 refreshTokenCookie.setSecure(true); 45 refreshTokenCookie.setPath("/"); 46 response.addCookie(refreshTokenCookie); 47 48 return true; 49 } catch (Exception e) { 50 // handle exception 51 } 52 } 53 54 private String getCookieValue(HttpServletRequest request, String cookieName) { 55 Cookie[] cookies = request.getCookies(); 56 if (cookies != null) { 57 for (Cookie cookie : cookies) { 58 if (cookieName.equals(cookie.getName())) { 59 return cookie.getValue(); 60 } 61 } 62 } 63 return null; 64 } 65 } ``` 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 [Section titled “Log out the user”](#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. * Node.js ```javascript 1 app.get('/logout', (req, res) => { 2 // Clear all session data including cookies and local storage 3 clearSessionData(); 4 5 const logoutUrl = scalekit.getLogoutUrl( 6 idTokenHint, // ID token to invalidate 7 postLogoutRedirectUri // URL that scalekit redirects after session invalidation 8 ); 9 10 // Redirect the user to the Scalekit logout endpoint to begin invalidating the session. 11 res.redirect(logoutUrl); // This URL can only be used once and expires after logout. 12 }); ``` * Python ```python 1 from flask import Flask, redirect 2 from scalekit.common.scalekit import LogoutUrlOptions 3 4 app = Flask(__name__) 5 6 @app.route('/logout') 7 def logout(): 8 # Clear all session data including cookies and local storage 9 clear_session_data() 10 11 # Generate Scalekit logout URL 12 options = LogoutUrlOptions( 13 id_token_hint=id_token, 14 post_logout_redirect_uri=post_logout_redirect_uri 15 ) 16 logout_url = scalekit.get_logout_url(options) 17 18 # Redirect to Scalekit's logout endpoint 19 # Note: This is a one-time use URL that becomes invalid after use 20 return redirect(logout_url) ``` * Go ```go 1 package main 2 3 import ( 4 "net/http" 5 "github.com/gin-gonic/gin" 6 "github.com/scalekit-inc/scalekit-sdk-go" 7 ) 8 9 func logoutHandler(c *gin.Context) { 10 // Clear all session data including cookies and local storage 11 clearSessionData() 12 13 // Generate Scalekit logout URL 14 options := scalekit.LogoutUrlOptions{ 15 IdTokenHint: idToken, 16 PostLogoutRedirectUri: postLogoutRedirectUri, 17 } 18 logoutUrl, err := scalekitClient.GetLogoutUrl(options) 19 if err != nil { 20 c.JSON(http.StatusInternalServerError, gin.H{ 21 "error": "Failed to generate logout URL", 22 }) 23 return 24 } 25 26 // Redirect to Scalekit's logout endpoint 27 // Note: This is a one-time use URL that becomes invalid after use 28 c.Redirect(http.StatusFound, logoutUrl.String()) 29 } ``` * Java ```java 1 import com.scalekit.internal.http.LogoutUrlOptions; 2 import org.springframework.web.bind.annotation.*; 3 import org.springframework.web.servlet.view.RedirectView; 4 import java.net.URL; 5 6 @RestController 7 public class LogoutController { 8 9 @GetMapping("/logout") 10 public RedirectView logout() { 11 12 clearSessionData(); 13 14 15 LogoutUrlOptions options = new LogoutUrlOptions(); 16 options.setIdTokenHint(idToken); 17 options.setPostLogoutRedirectUri(postLogoutRedirectUri); 18 19 URL logoutUrl = scalekit.authentication() 20 .getLogoutUrl(options); 21 22 23 // Note: This is a one-time use URL that becomes invalid after use 24 return new RedirectView(logoutUrl.toString()); 25 } 26 } ``` 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. --- # DOCUMENT BOUNDARY --- # Add Modular SCIM provisioning > Automate user provisioning with SCIM. Directory API and webhooks for real-time user data sync This guide shows you how to automate user provisioning with SCIM using Scalekit’s Directory API and webhooks. You’ll learn to sync user data in real-time, create webhook endpoints for instant updates, and build automated provisioning workflows that keep your application’s user data synchronized with your customers’ directory providers. With [SCIM Provisioning](/directory/guides/user-provisioning-basics) from Scalekit, you can: * Use **webhooks** to listen for events from your customers’ directory providers (e.g., user updates, group changes) * Use **REST APIs** to list users, groups, and directories on demand Scalekit abstracts the complexities of various directory providers, giving you a single interface to automate user lifecycle management. This enables you to create accounts for new hires during onboarding, deactivate accounts when employees depart, and adjust access levels as employees change roles.  ### Build with a coding agent * Claude Code ```bash /plugin marketplace add scalekit-inc/claude-code-authstack ``` ```bash /plugin install modular-scim@scalekit-auth-stack ``` * Codex ```bash curl -fsSL https://raw.githubusercontent.com/scalekit-inc/codex-authstack/main/install.sh | bash ``` ```bash # Restart Codex # Plugin Directory -> Scalekit Auth Stack -> install modular-scim ``` * GitHub Copilot CLI ```bash copilot plugin marketplace add scalekit-inc/github-copilot-authstack ``` ```bash copilot plugin install modular-scim@scalekit-auth-stack ``` * 40+ agents ```bash npx skills add scalekit-inc/skills --skill implementing-scim-provisioning ``` [Continue building with AI →](/dev-kit/build-with-ai/scim/) ## User provisioning with Scalekit’s directory API [Section titled “User provisioning with Scalekit’s directory API”](#user-provisioning-with-scalekits-directory-api) Scalekit’s directory API allows you to fetch information about users, groups, and directories associated with an organization on-demand. This approach is ideal for scheduled synchronization tasks, bulk data imports, or when you need to ensure your application’s user data matches the latest directory provider state. Let’s explore how to use the Directory API to retrieve user and group data programmatically. 1. ### Setting up the SDK [Section titled “Setting up the SDK”](#setting-up-the-sdk) Before you begin, ensure that your organization [has a directory set up in Scalekit](/guides/user-management/scim-provisioning/). Scalekit offers language-specific SDKs for fast SSO integration. Use the installation instructions below for your technology stack: * Node.js ```bash npm install @scalekit-sdk/node ``` * Python ```sh pip install scalekit-sdk-python ``` * Go ```sh go get -u github.com/scalekit-inc/scalekit-sdk-go ``` * Java ```groovy /* Gradle users - add the following to your dependencies in build file */ implementation "com.scalekit:scalekit-sdk-java:2.0.11" ``` ```xml com.scalekit scalekit-sdk-java 2.0.11 ``` Navigate to **Dashboard > Developers > Settings > API Credentials** to obtain your credentials. Store your credentials securely in environment variables: .env ```shell 1 # Get these values from Dashboard > Developers > Settings > API Credentials 2 SCALEKIT_ENVIRONMENT_URL='https://b2b-app-dev.scalekit.com' 3 SCALEKIT_CLIENT_ID='' 4 SCALEKIT_CLIENT_SECRET='' ``` 2. ### Initialize the SDK and make your first API call [Section titled “Initialize the SDK and make your first API call”](#initialize-the-sdk-and-make-your-first-api-call) Initialize the Scalekit client with your environment variables and make your first API call to list organizations. * cURL Terminal ```bash 1 # Security: Replace with a valid access token from Scalekit 2 # This token authorizes your API requests to access organization data 3 4 # Use case: Verify API connectivity and test authentication 5 # Examples: Initial setup testing, debugging integration issues 6 7 curl -L "https://$SCALEKIT_ENVIRONMENT_URL/api/v1/organizations?page_size=5" \ 8 -H "Authorization: Bearer " ``` * Node.js Node.js ```javascript 1 import { ScalekitClient } from '@scalekit-sdk/node'; 2 3 // Initialize Scalekit client with environment variables 4 // Security: Always use environment variables for sensitive credentials 5 const scalekit = new ScalekitClient( 6 process.env.SCALEKIT_ENVIRONMENT_URL, 7 process.env.SCALEKIT_CLIENT_ID, 8 process.env.SCALEKIT_CLIENT_SECRET, 9 ); 10 11 try { 12 // Use case: Retrieve organizations for bulk user provisioning workflows 13 // Examples: Multi-tenant applications, enterprise customer onboarding 14 const { organizations } = await scalekit.organization.listOrganization({ 15 pageSize: 5, 16 }); 17 18 console.log(`Organization name: ${organizations[0].display_name}`); 19 console.log(`Organization ID: ${organizations[0].id}`); 20 } catch (error) { 21 console.error('Failed to list organizations:', error); 22 // Handle error appropriately for your application 23 } ``` * Python Python ```python 1 from scalekit import ScalekitClient 2 import os 3 4 # Initialize the SDK client with environment variables 5 # Security: Use os.getenv() to securely access credentials 6 scalekit_client = ScalekitClient( 7 env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"), 8 client_id=os.getenv("SCALEKIT_CLIENT_ID"), 9 client_secret=os.getenv("SCALEKIT_CLIENT_SECRET") 10 ) 11 12 try: 13 # Use case: Sync user data across multiple organizations 14 # Examples: Scheduled provisioning tasks, HR system integration 15 org_list = scalekit_client.organization.list_organizations(page_size=100) 16 17 if org_list: 18 print(f'Organization details: {org_list[0]}') 19 print(f'Organization ID: {org_list[0].id}') 20 except Exception as error: 21 print(f'Error listing organizations: {error}') 22 # Implement appropriate error handling for your use case ``` * Go Go ```go 1 package main 2 3 import ( 4 "context" 5 "fmt" 6 "os" 7 8 "github.com/scalekit/scalekit-go" 9 ) 10 11 // Initialize Scalekit client with environment variables 12 // Security: Always load credentials from environment, not hardcoded 13 scalekitClient := scalekit.NewScalekitClient( 14 os.Getenv("SCALEKIT_ENVIRONMENT_URL"), 15 os.Getenv("SCALEKIT_CLIENT_ID"), 16 os.Getenv("SCALEKIT_CLIENT_SECRET"), 17 ) 18 19 // Use case: Get specific organization for directory sync operations 20 // Examples: Targeted user provisioning, organization-specific workflows 21 organization, err := scalekitClient.Organization.GetOrganization( 22 ctx, 23 organizationId, 24 ) 25 if err != nil { 26 // Handle error appropriately for your application 27 return fmt.Errorf("failed to get organization: %w", err) 28 } ``` * Java Java ```java 1 import com.scalekit.ScalekitClient; 2 3 // Initialize Scalekit client with environment variables 4 // Security: Use System.getenv() to securely access credentials 5 ScalekitClient scalekitClient = new ScalekitClient( 6 System.getenv("SCALEKIT_ENVIRONMENT_URL"), 7 System.getenv("SCALEKIT_CLIENT_ID"), 8 System.getenv("SCALEKIT_CLIENT_SECRET") 9 ); 10 11 try { 12 // Use case: List organizations for automated provisioning workflows 13 // Examples: Enterprise customer setup, multi-tenant management 14 ListOrganizationsResponse organizations = scalekitClient.organizations() 15 .listOrganizations(5, ""); 16 17 if (!organizations.getOrganizations().isEmpty()) { 18 Organization firstOrg = organizations.getOrganizations().get(0); 19 System.out.println("Organization name: " + firstOrg.getDisplayName()); 20 System.out.println("Organization ID: " + firstOrg.getId()); 21 } 22 } catch (ScalekitException error) { 23 System.err.println("Failed to list organizations: " + error.getMessage()); 24 // Implement appropriate error handling 25 } ``` 3. ### Retrieve a directory [Section titled “Retrieve a directory”](#retrieve-a-directory) After successfully listing organizations, you’ll need to retrieve the specific directory to begin syncing user and group data. You can retrieve directories using either the organization and directory IDs, or fetch the primary directory for an organization. * Node.js Node.js ```javascript 1 try { 2 // Use case: Get specific directory when organization has multiple directories 3 // Examples: Department-specific provisioning, multi-division companies 4 const { directory } = await scalekit.directory.getDirectory('', ''); 5 console.log(`Directory name: ${directory.name}`); 6 7 // Use case: Get primary directory for simple provisioning workflows 8 // Examples: Small organizations, single-directory setups 9 const { directory } = await scalekit.directory.getPrimaryDirectoryByOrganizationId(''); 10 console.log(`Primary directory ID: ${directory.id}`); 11 } catch (error) { 12 console.error('Failed to retrieve directory:', error); 13 // Handle error appropriately for your application 14 } ``` * Python Python ```python 1 try: 2 # Use case: Access specific directory for targeted user sync operations 3 # Examples: Regional offices, business unit-specific provisioning 4 directory = scalekit_client.directory.get_directory( 5 organization_id='', directory_id='' 6 ) 7 print(f'Directory name: {directory.name}') 8 9 # Use case: Get primary directory for streamlined user management 10 # Examples: Standard employee provisioning, main company directory 11 primary_directory = scalekit_client.directory.get_primary_directory_by_organization_id( 12 organization_id='' 13 ) 14 print(f'Primary directory ID: {primary_directory.id}') 15 except Exception as error: 16 print(f'Error retrieving directory: {error}') 17 # Implement appropriate error handling ``` * Go Go ```go 1 // Use case: Retrieve specific directory for granular access control 2 // Examples: Multi-tenant environments, department-level provisioning 3 directory, err := scalekitClient.Directory().GetDirectory(ctx, organizationId, directoryId) 4 if err != nil { 5 return fmt.Errorf("failed to get directory: %w", err) 6 } 7 fmt.Printf("Directory name: %s\n", directory.Name) 8 9 // Use case: Get primary directory for simplified user management 10 // Examples: Automated provisioning workflows, bulk user imports 11 directory, err := scalekitClient.Directory().GetPrimaryDirectoryByOrganizationId(ctx, organizationId) 12 if err != nil { 13 return fmt.Errorf("failed to get primary directory: %w", err) 14 } 15 fmt.Printf("Primary directory ID: %s\n", directory.ID) ``` * Java Java ```java 1 try { 2 // Use case: Access specific directory for detailed user management 3 // Examples: Custom provisioning logic, directory-specific rules 4 Directory directory = scalekitClient.directories() 5 .getDirectory("", ""); 6 System.out.println("Directory name: " + directory.getName()); 7 8 // Use case: Get primary directory for standard provisioning workflows 9 // Examples: Employee onboarding, automated user sync 10 Directory primaryDirectory = scalekitClient.directories() 11 .getPrimaryDirectoryByOrganizationId(""); 12 System.out.println("Primary directory ID: " + primaryDirectory.getId()); 13 } catch (ScalekitException error) { 14 System.err.println("Failed to retrieve directory: " + error.getMessage()); 15 // Implement appropriate error handling 16 } ``` 4. ### List users in a directory [Section titled “List users in a directory”](#list-users-in-a-directory) Once you have the directory information, you can fetch users within that directory. This is commonly used for bulk user synchronization and maintaining an up-to-date user database. * Node.js Node.js ```javascript 1 try { 2 // Use case: Bulk user synchronization and provisioning 3 // Examples: New customer onboarding, scheduled user data sync 4 const { users } = await scalekit.directory.listDirectoryUsers('', ''); 5 6 // Process each user for provisioning or updates 7 users.forEach(user => { 8 console.log(`User email: ${user.email}, Name: ${user.name}`); 9 // TODO: Implement your user provisioning logic here 10 }); 11 } catch (error) { 12 console.error('Failed to list directory users:', error); 13 // Handle error appropriately for your application 14 } ``` * Python Python ```python 1 try: 2 # Use case: Automated user provisioning workflows 3 # Examples: HR system integration, bulk user imports 4 directory_users = scalekit_client.directory.list_directory_users( 5 organization_id='', directory_id='' 6 ) 7 8 # Process each user for local database updates 9 for user in directory_users: 10 print(f'User email: {user.email}, Name: {user.name}') 11 # TODO: Implement your user synchronization logic here 12 except Exception as error: 13 print(f'Error listing directory users: {error}') 14 # Implement appropriate error handling ``` * Go Go ```go 1 // Configure pagination options for large user directories 2 options := &ListDirectoryUsersOptions{ 3 PageSize: 50, // Adjust based on your needs 4 PageToken: "", 5 } 6 7 // Use case: Paginated user retrieval for large directories 8 // Examples: Enterprise customer provisioning, regular sync jobs 9 directoryUsers, err := scalekitClient.Directory().ListDirectoryUsers(ctx, organizationId, directoryId, options) 10 if err != nil { 11 return fmt.Errorf("failed to list directory users: %w", err) 12 } 13 14 // Process each user 15 for _, user := range directoryUsers.Users { 16 fmt.Printf("User email: %s, Name: %s\n", user.Email, user.Name) 17 // TODO: Implement your user provisioning logic 18 } ``` * Java Java ```java 1 // Configure options for user listing with pagination 2 var options = ListDirectoryResourceOptions.builder() 3 .pageSize(50) // Adjust based on your requirements 4 .pageToken("") 5 .includeDetail(true) // Include detailed user information 6 .build(); 7 8 try { 9 // Use case: Enterprise user management and synchronization 10 // Examples: Scheduled sync tasks, user provisioning automation 11 ListDirectoryUsersResponse usersResponse = scalekitClient.directories() 12 .listDirectoryUsers(directory.getId(), organizationId, options); 13 14 // Process each user for provisioning 15 for (User user : usersResponse.getUsers()) { 16 System.out.println("User email: " + user.getEmail() + ", Name: " + user.getName()); 17 // TODO: Implement your user provisioning logic here 18 } 19 } catch (ScalekitException error) { 20 System.err.println("Failed to list directory users: " + error.getMessage()); 21 // Implement appropriate error handling 22 } ``` 5. ### List groups in a directory [Section titled “List groups in a directory”](#list-groups-in-a-directory) Groups are essential for implementing role-based access control (RBAC) in your application. After retrieving users, you can fetch groups to manage permissions and access levels based on organizational structure. * Node.js Node.js ```javascript 1 try { 2 // Use case: Role-based access control implementation 3 // Examples: Department-level permissions, project-based access 4 const { groups } = await scalekit.directory.listDirectoryGroups( 5 '', 6 '', 7 ); 8 9 // Process each group for RBAC setup 10 groups.forEach(group => { 11 console.log(`Group name: ${group.name}, ID: ${group.id}`); 12 // TODO: Implement your group-based permission logic here 13 }); 14 } catch (error) { 15 console.error('Failed to list directory groups:', error); 16 // Handle error appropriately for your application 17 } ``` * Python Python ```python 1 try: 2 # Use case: Department-based access control 3 # Examples: Engineering vs Sales permissions, project team access 4 directory_groups = scalekit_client.directory.list_directory_groups( 5 directory_id='', organization_id='' 6 ) 7 8 # Process each group for permission mapping 9 for group in directory_groups: 10 print(f'Group name: {group.name}, ID: {group.id}') 11 # TODO: Implement your group-based permission logic here 12 except Exception as error: 13 print(f'Error listing directory groups: {error}') 14 # Implement appropriate error handling ``` * Go Go ```go 1 // Configure pagination for group listing 2 options := &ListDirectoryGroupsOptions{ 3 PageSize: 25, // Adjust based on expected group count 4 PageToken: "", 5 } 6 7 // Use case: Organizational role management 8 // Examples: Enterprise role hierarchy, department-based access 9 directoryGroups, err := scalekitClient.Directory().ListDirectoryGroups(ctx, organizationId, directoryId, options) 10 if err != nil { 11 return fmt.Errorf("failed to list directory groups: %w", err) 12 } 13 14 // Process each group for RBAC implementation 15 for _, group := range directoryGroups.Groups { 16 fmt.Printf("Group name: %s, ID: %s\n", group.Name, group.ID) 17 // TODO: Implement your group-based permission logic 18 } ``` * Java Java ```java 1 // Configure options for detailed group information 2 var options = ListDirectoryResourceOptions.builder() 3 .pageSize(25) // Adjust based on your requirements 4 .pageToken("") 5 .includeDetail(true) // Include group membership details 6 .build(); 7 8 try { 9 // Use case: Enterprise permission management 10 // Examples: Role assignments, access level configurations 11 ListDirectoryGroupsResponse groupsResponse = scalekitClient.directories() 12 .listDirectoryGroups(directory.getId(), organizationId, options); 13 14 // Process each group for permission mapping 15 for (Group group : groupsResponse.getGroups()) { 16 System.out.println("Group name: " + group.getName() + ", ID: " + group.getId()); 17 // TODO: Implement your group-based permission logic here 18 } 19 } catch (ScalekitException error) { 20 System.err.println("Failed to list directory groups: " + error.getMessage()); 21 // Implement appropriate error handling 22 } ``` Scalekit’s Directory API provides a simple way to fetch user and group information on-demand. Refer to our [API reference](https://docs.scalekit.com/apis/) to explore more capabilities. ## Realtime user provisioning with webhooks [Section titled “Realtime user provisioning with webhooks”](#realtime-user-provisioning-with-webhooks) While the Directory API is perfect for scheduled synchronization, webhooks enable immediate, real-time user provisioning. When directory providers send events to Scalekit, we forward them instantly to your application, allowing you to respond to user changes as they happen. This approach is ideal for scenarios requiring immediate action, such as new employee onboarding or emergency access revocation. 1. ### Create a secure webhook endpoint [Section titled “Create a secure webhook endpoint”](#create-a-secure-webhook-endpoint) Create a webhook endpoint to receive real-time events from directory providers. After implementing your endpoint, register it in **Dashboard > Webhooks** where you’ll receive a secret for payload verification. Critical security requirement Always verify webhook signatures before processing events. This prevents unauthorized parties from triggering your provisioning logic and protects against replay attacks. * Node.js Express.js ```javascript 1 app.post('/webhook', async (req, res) => { 2 // Security: ALWAYS verify requests are from Scalekit before processing 3 // This prevents unauthorized parties from triggering your provisioning logic 4 5 const event = req.body; 6 const headers = req.headers; 7 const secret = process.env.SCALEKIT_WEBHOOK_SECRET; 8 9 try { 10 // Verify webhook signature to prevent replay attacks and forged requests 11 await scalekit.verifyWebhookPayload(secret, headers, event); 12 } catch (error) { 13 console.error('Webhook signature verification failed:', error); 14 // Return 400 for invalid signatures - this prevents processing malicious requests 15 return res.status(400).json({ error: 'Invalid signature' }); 16 } 17 18 try { 19 // Use case: Real-time user provisioning based on directory events 20 // Examples: New hire onboarding, emergency access revocation, role changes 21 const { email, name } = event.data; 22 23 // Process the webhook event based on its type 24 switch (event.type) { 25 case 'organization.directory.user_created': 26 await createUserAccount(email, name); 27 break; 28 case 'organization.directory.user_updated': 29 await updateUserAccount(email, name); 30 break; 31 case 'organization.directory.user_deleted': 32 await deactivateUserAccount(email); 33 break; 34 default: 35 console.log(`Unhandled event type: ${event.type}`); 36 } 37 38 res.status(201).json({ message: 'Webhook processed successfully' }); 39 } catch (processingError) { 40 console.error('Failed to process webhook event:', processingError); 41 res.status(500).json({ error: 'Processing failed' }); 42 } 43 }); ``` * Python FastAPI ```python 1 from fastapi import FastAPI, Request, HTTPException 2 import os 3 import json 4 5 app = FastAPI() 6 7 @app.post("/webhook") 8 async def api_webhook(request: Request): 9 # Security: ALWAYS verify webhook signatures before processing events 10 # This prevents unauthorized webhook calls and replay attacks 11 12 headers = request.headers 13 body = await request.json() 14 15 try: 16 # Verify webhook payload using the secret from Scalekit dashboard 17 # Get this from Dashboard > Webhooks after registering your endpoint 18 is_valid = scalekit_client.verify_webhook_payload( 19 secret=os.getenv("SCALEKIT_WEBHOOK_SECRET"), 20 headers=headers, 21 payload=json.dumps(body).encode('utf-8') 22 ) 23 24 if not is_valid: 25 raise HTTPException(status_code=400, detail="Invalid webhook signature") 26 27 except Exception as verification_error: 28 print(f"Webhook verification failed: {verification_error}") 29 raise HTTPException(status_code=400, detail="Webhook verification failed") 30 31 # Use case: Instant user provisioning based on directory events 32 # Examples: Automated onboarding, immediate access revocation, role updates 33 try: 34 event_type = body.get("type") 35 event_data = body.get("data", {}) 36 email = event_data.get("email") 37 name = event_data.get("name") 38 39 if event_type == "organization.directory.user_created": 40 await create_user_account(email, name) 41 elif event_type == "organization.directory.user_updated": 42 await update_user_account(email, name) 43 elif event_type == "organization.directory.user_deleted": 44 await deactivate_user_account(email) 45 46 return JSONResponse(status_code=201, content={"status": "processed"}) 47 48 except Exception as processing_error: 49 print(f"Failed to process webhook: {processing_error}") 50 raise HTTPException(status_code=500, detail="Event processing failed") ``` * Java Spring Boot ```java 1 @PostMapping("/webhook") 2 public ResponseEntity webhook( 3 @RequestBody String body, 4 @RequestHeader Map headers) { 5 6 // Security: ALWAYS verify webhook signatures before processing 7 // This prevents malicious webhook calls and protects against replay attacks 8 9 String secret = System.getenv("SCALEKIT_WEBHOOK_SECRET"); 10 11 try { 12 // Verify webhook signature using Scalekit SDK 13 boolean isValid = scalekitClient.webhook() 14 .verifyWebhookPayload(secret, headers, body.getBytes()); 15 16 if (!isValid) { 17 return ResponseEntity.badRequest().body("Invalid webhook signature"); 18 } 19 20 } catch (Exception verificationError) { 21 System.err.println("Webhook verification failed: " + verificationError.getMessage()); 22 return ResponseEntity.badRequest().body("Webhook verification failed"); 23 } 24 25 try { 26 // Use case: Real-time user lifecycle management 27 // Examples: Employee onboarding, access termination, role modifications 28 ObjectMapper mapper = new ObjectMapper(); 29 JsonNode rootNode = mapper.readTree(body); 30 31 String eventType = rootNode.get("type").asText(); 32 JsonNode data = rootNode.get("data"); 33 34 switch (eventType) { 35 case "organization.directory.user_created": 36 String email = data.get("email").asText(); 37 String name = data.get("name").asText(); 38 createUserAccount(email, name); 39 break; 40 case "organization.directory.user_updated": 41 updateUserAccount(data); 42 break; 43 case "organization.directory.user_deleted": 44 deactivateUserAccount(data.get("email").asText()); 45 break; 46 default: 47 System.out.println("Unhandled event type: " + eventType); 48 } 49 50 return ResponseEntity.status(HttpStatus.CREATED).body("Webhook processed"); 51 52 } catch (Exception processingError) { 53 System.err.println("Failed to process webhook event: " + processingError.getMessage()); 54 return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR) 55 .body("Event processing failed"); 56 } 57 } ``` * Go Go ```go 1 // Security: Store webhook secret securely in environment variables 2 // Get this from Dashboard > Webhooks after registering your endpoint 3 webhookSecret := os.Getenv("SCALEKIT_WEBHOOK_SECRET") 4 5 http.HandleFunc("/webhook", func(w http.ResponseWriter, r *http.Request) { 6 // Security: ALWAYS verify webhook signatures before processing events 7 // This prevents unauthorized webhook calls and replay attacks 8 9 if r.Method != http.MethodPost { 10 http.Error(w, "Method not allowed", http.StatusMethodNotAllowed) 11 return 12 } 13 14 body, err := io.ReadAll(r.Body) 15 if err != nil { 16 http.Error(w, err.Error(), http.StatusBadRequest) 17 return 18 } 19 defer r.Body.Close() 20 21 // Extract webhook headers for verification 22 headers := map[string]string{ 23 "webhook-id": r.Header.Get("webhook-id"), 24 "webhook-signature": r.Header.Get("webhook-signature"), 25 "webhook-timestamp": r.Header.Get("webhook-timestamp"), 26 } 27 28 // Verify webhook signature to prevent malicious requests 29 _, err = scalekitClient.VerifyWebhookPayload(webhookSecret, headers, body) 30 if err != nil { 31 http.Error(w, "Invalid webhook signature", http.StatusBadRequest) 32 return 33 } 34 35 // Use case: Instant user provisioning and lifecycle management 36 // Examples: Real-time onboarding, emergency access revocation, role synchronization 37 var webhookEvent WebhookEvent 38 if err := json.Unmarshal(body, &webhookEvent); err != nil { 39 http.Error(w, "Invalid webhook payload", http.StatusBadRequest) 40 return 41 } 42 43 switch webhookEvent.Type { 44 case "organization.directory.user_created": 45 err = createUserAccount(webhookEvent.Data.Email, webhookEvent.Data.Name) 46 case "organization.directory.user_updated": 47 err = updateUserAccount(webhookEvent.Data) 48 case "organization.directory.user_deleted": 49 err = deactivateUserAccount(webhookEvent.Data.Email) 50 default: 51 fmt.Printf("Unhandled event type: %s\n", webhookEvent.Type) 52 } 53 54 if err != nil { 55 http.Error(w, "Failed to process webhook", http.StatusInternalServerError) 56 return 57 } 58 59 w.WriteHeader(http.StatusCreated) 60 w.Write([]byte(`{"status": "processed"}`)) 61 }) ``` 2. ### Register your webhook endpoint [Section titled “Register your webhook endpoint”](#register-your-webhook-endpoint) After implementing your secure webhook endpoint, register it in the Scalekit dashboard to start receiving events: 1. Navigate to **Dashboard > Webhooks** 2. Click **+Add Endpoint** 3. Enter your webhook endpoint URL (e.g., `https://your-app.com/api/webhooks/scalekit`) 4. Add a meaningful description for your reference 5. Select the event types you want to receive. Common choices include: * `organization.directory.user_created` - New user provisioning * `organization.directory.user_updated` - User profile changes * `organization.directory.user_deleted` - User deactivation * `organization.directory.group_created` - New group creation * `organization.directory.group_updated` - Group modifications Once registered, your webhook endpoint will start receiving event payloads from directory providers in real-time. 3. ### Process webhook events [Section titled “Process webhook events”](#process-webhook-events) Scalekit standardizes event payloads across different directory providers, ensuring consistent data structure regardless of whether your customers use Azure AD, Okta, Google Workspace, or other providers. When directory changes occur, Scalekit sends events with the following structure: Webhook event payload ```json 1 { 2 "id": "evt_1234567890", 3 "type": "organization.directory.user_created", 4 "data": { 5 "email": "john.doe@company.com", 6 "name": "John Doe", 7 "organization_id": "org_12345", 8 "directory_id": "dir_67890" 9 }, 10 "timestamp": "2024-01-15T10:30:00Z" 11 } ``` You have now successfully implemented and registered a webhook endpoint, enabling your application to receive real-time events for automated user provisioning. Your system can now respond instantly to directory changes, providing seamless user lifecycle management. Refer to our [webhook implementation guide](/authenticate/implement-workflows/implement-webhooks/) for the complete list of available event types and payload structures. --- # DOCUMENT BOUNDARY --- # Overview of modelling users and organizations > Put together a data model for your app's users and organizations Authenticated users now have access to your app. Now is the time to consider how you’ll structure your data model for users and organizations. This foundational model will serve you well as you implement features such as workspaces, user invitations, role-based access control, and more—ultimately enabling your application to fully support B2B use cases. Organizations and Users are the two first-class entities in Scalekit * An **Organization** serves as a dedicated tenant within the application, representing a distinct entity like a company or project. A **User** is an individual account granted access to interact with the application. Typically belong to organization(s). This is a simplified view of the relationship between these two entities  This model makes it easy to implement essential B2B capabilities in your application. ## Flexible user sign-in options for organizations [Section titled “Flexible user sign-in options for organizations”](#flexible-user-sign-in-options-for-organizations) Configure your application to support multiple authentication methods, allowing users to choose their preferred sign-in options. Also, this is crucial for enabling organization administrators to set and enforce specific authentication policies for their users. A primary use case is implementing enterprise Single Sign-On (SSO). This allows your customers to authenticate their users through their organization’s existing Identity Provider (IdP), such as Okta, Google, or Microsoft Entra ID where IdP verifies the user’s identity, granting them secure access to your application. With Scalekit as your authentication platform, administrators can easily enforce authentication policies for their organization’s users. Scalekit handles this enforcement automatically, either applying organization-specific policies or defaulting to your application’s preferred authentication methods on the login page. Configuring these settings is straightforward—simply toggle the desired options in your Scalekit environment through the dashboard or API. #### User records deduplication [Section titled “User records deduplication”](#user-records-deduplication) Regardless of which authentication methods your users choose, Scalekit automatically recognizes users with identical email addresses as the same individual. This eliminates the need for your application to manage multiple user records for the same person and ensures consistent identity recognition across different authentication flows. * Two different Users cannot have the same email address within the same Scalekit environment. * Scalekit automatically consolidates accounts. If a user logs in with an email and password and later uses Google OAuth with the same email, both authentication methods will be linked to the same User record. ## On how users join and leave organizations [Section titled “On how users join and leave organizations”](#on-how-users-join-and-leave-organizations) Control how users join and are provisioned into organizations. Scalekit provides a flexible user provisioning engine to manage the entire user lifecycle. This includes: * Sending and managing user invitations. * Allowing users to discover and join organizations based on their email domain. * Enabling membership in multiple organizations. * Securely de-provisioning users when they leave an organization. These capabilities are built-in, allowing you to deliver a secure and seamless user management experience from day one. ## Enforce user roles and permissions [Section titled “Enforce user roles and permissions”](#enforce-user-roles-and-permissions) While your product may offer a wide range of features, not all users should have identical access or capabilities. For example, in a project management tool, you might allow some users to create projects, while others may have permission only to view them. Managing user permissions can be complex. Scalekit simplifies this by providing the necessary roles and permissions your application needs to make authorization decisions at runtime. When a user [completes the login flow](/authenticate/fsa/complete-login/#decoding-token-claims), the access token issued by Scalekit contains their assigned roles. Your application can inspect this token to control access to different features. By default, Scalekit assigns an `admin` role to the organization creator and a `member` role to all other users, providing a solid foundation for your authorization logic. ## Modify user memberships [Section titled “Modify user memberships”](#modify-user-memberships) Scalekit tracks how users belong to organizations through a `memberships` property on each User object. This property contains an array of membership objects that define the user’s relationship to each organization they belong to. Each membership object includes these key properties: * `organization_id`: Identifies which organization the user belongs to * `roles`: Specifies the user’s roles (assigned by your application) within that organization * `status`: Indicates whether the membership is active, pending invite or invite expired The memberships property enables users to belong to multiple organizations while maintaining clear role and status information for each relationship. ```json 1 { 2 "memberships": [ 3 { 4 "join_time": "2025-06-27T10:57:43.720Z", 5 "membership_status": "ACTIVE", 6 "metadata": { 7 "department": "engineering", 8 "location": "nyc-office" 9 }, 10 "name": "string", 11 "organization_id": "org_1234abcd5678efgh", 12 "primary_identity_provider": "OKTA", 13 "roles": [ 14 { 15 "id": "role_admin", 16 "name": "Admin" 17 } 18 ] 19 }, 20 { 21 "join_time": "2025-07-15T14:30:22.451Z", 22 "membership_status": "ACTIVE", 23 "metadata": { 24 "department": "product", 25 "location": "sf-office" 26 }, 27 "name": "Jane Smith", 28 "organization_id": "org_9876zyxw5432vuts", 29 "primary_identity_provider": "GOOGLE", 30 "roles": [ 31 { 32 "id": "role_prod_manager", 33 "name": "Product Manager" 34 } 35 ] 36 } 37 ], 38 } ``` #### Migrating from a 1-to-1 model [Section titled “Migrating from a 1-to-1 model”](#migrating-from-a-1-to-1-model) In a 1-to-1 data model, each user is associated with a single organization. The user’s identity is tied to that specific organization, and they cannot belong to multiple organizations with the same identity. This model is common in applications that were not originally built with multi-tenancy in mind, or where each customer’s data and user base are kept entirely separate. For example, many traditional enterprise software applications like **Slack**, **QuickBooks**, or **Adobe Creative Suite** use this model - each customer purchases their own license and has their own separate user accounts that cannot be shared across different customer organizations. #### Migrating from a 1-to-many model [Section titled “Migrating from a 1-to-many model”](#migrating-from-a-1-to-many-model) If your application allows a single user to be part of multiple organizations, their profile in Scalekit will also be shared across those organizations. While the user’s core profile is consistent, each organization membership stores distinct information like roles, status, and metadata. If you already have a membership table that links users and organizations, you can add the Scalekit `user_id` to that table. When you update a user’s profile, the changes will apply across all their organization memberships. | Aspect | 1-to-1 | 1-to-many | | ------------------- | ------------------------------- | ------------------------------- | | **User belongs to** | One organization | Multiple organizations | | **Email address** | Tied to one org | Unique across environment | | **Authentication** | Per-organization | Across all orgs | | **Example apps** | Adobe Creative, QuickBooks | Slack, GitHub, Figma | | **Scalekit use** | Simpler setup, less flexibility | Full multi-tenancy capabilities | --- # DOCUMENT BOUNDARY --- # Complete login with code exchange > Process authentication callbacks and handle redirect flows after users authenticate with Scalekit Once users have successfully verified their identity using their chosen login method, Scalekit will have gathered the necessary user information for your app to complete the login process. However, your app must provide a callback endpoint where Scalekit can exchange an authorization code to return your app the user details. 1. ## Validate the `state` parameter recommended [Section titled “Validate the state parameter ”](#validate-the-state-parameter-) Before exchanging the authorization code, your application must validate the `state` parameter returned by Scalekit. Compare it with the value you stored in the user’s session before redirecting them. This critical step prevents Cross-Site Request Forgery (CSRF) attacks, ensuring the authentication response corresponds to a request initiated by the same user. * Node.js Validate state in Express.js ```javascript 1 const { state } = req.query; 2 3 // Assumes you are using a session middleware like express-session 4 const storedState = req.session.oauthState; 5 delete req.session.oauthState; // State should be used only once 6 7 if (!state || state !== storedState) { 8 console.error('Invalid state parameter'); 9 return res.redirect('/login?error=invalid_state'); 10 } ``` * Python Validate state in Flask ```python 1 from flask import session, request, redirect 2 3 state = request.args.get('state') 4 5 # Retrieve and remove stored state from session 6 stored_state = session.pop('oauth_state', None) 7 8 if not state or state != stored_state: 9 print('Invalid state parameter') 10 return redirect('/login?error=invalid_state') ``` * Go Validate state in Gin ```go 1 stateParam := c.Query("state") 2 3 // Assumes you are using a session library like gin-contrib/sessions 4 session := sessions.Default(c) 5 storedState := session.Get("oauth_state") 6 session.Delete("oauth_state") // State should be used only once 7 session.Save() 8 9 if stateParam == "" || stateParam != storedState { 10 log.Println("Invalid state parameter") 11 c.Redirect(http.StatusFound, "/login?error=invalid_state") 12 return 13 } ``` * Java Validate state in Spring ```java 1 // Assumes HttpSession is injected into your controller method 2 String storedState = (String) session.getAttribute("oauth_state"); 3 session.removeAttribute("oauth_state"); // State should be used only once 4 5 if (state == null || !state.equals(storedState)) { 6 System.err.println("Invalid state parameter"); 7 return new RedirectView("/login?error=invalid_state"); 8 } ``` 2. ## Exchange authorization code for tokens [Section titled “Exchange authorization code for tokens”](#exchange-authorization-code-for-tokens) Once the `state` is validated, your app can safely exchange the authorization code for tokens. The Scalekit SDK simplifies this process with the `authenticateWithCode` method, which handles the secure server-to-server request. * Node.js Express.js callback handler ```javascript 1 app.get('/auth/callback', async (req, res) => { 2 const { code, error, error_description, state } = req.query; 3 4 // Add state validation here (see previous step) 5 6 // Handle errors first 7 if (error) { 8 console.error('Authentication error:', error); 9 return res.redirect('/login?error=auth_failed'); 10 } 11 12 if (!code) { 13 return res.redirect('/login?error=missing_code'); 14 } 15 16 try { 17 // Exchange code for user data 18 const authResult = await scalekit.authenticateWithCode( 19 code, 20 'https://yourapp.com/auth/callback' 21 ); 22 23 const { user, accessToken, refreshToken } = authResult; 24 25 // TODO: Store user session (next guide covers this) 26 // req.session.user = user; 27 28 res.redirect('/dashboard'); 29 30 } catch (error) { 31 console.error('Token exchange failed:', error); 32 res.redirect('/login?error=exchange_failed'); 33 } 34 }); ``` * Python Flask callback handler ```python 1 @app.route('/auth/callback') 2 def auth_callback(): 3 code = request.args.get('code') 4 error = request.args.get('error') 5 state = request.args.get('state') 6 7 # TODO: Add state validation here (see previous step) 8 9 # Handle errors first 10 if error: 11 print(f'Authentication error: {error}') 12 return redirect('/login?error=auth_failed') 13 14 if not code: 15 return redirect('/login?error=missing_code') 16 17 try: 18 # Exchange code for user data 19 options = CodeAuthenticationOptions() 20 auth_result = scalekit.authenticate_with_code( 21 code, 22 'https://yourapp.com/auth/callback', 23 options 24 ) 25 26 user = auth_result.user 27 # access_token = auth_result.access_token 28 # refresh_token = auth_result.refresh_token 29 30 # TODO: Store user session (next guide covers this) 31 # session['user'] = user 32 33 return redirect('/dashboard') 34 35 except Exception as e: 36 print(f'Token exchange failed: {e}') 37 return redirect('/login?error=exchange_failed') ``` * Go Gin callback handler ```go 1 func authCallbackHandler(c *gin.Context) { 2 code := c.Query("code") 3 errorParam := c.Query("error") 4 stateParam := c.Query("state") 5 6 // TODO: Add state validation here (see previous step) 7 8 // Handle errors first 9 if errorParam != "" { 10 log.Printf("Authentication error: %s", errorParam) 11 c.Redirect(http.StatusFound, "/login?error=auth_failed") 12 return 13 } 14 15 if code == "" { 16 c.Redirect(http.StatusFound, "/login?error=missing_code") 17 return 18 } 19 20 // Exchange code for user data 21 options := scalekit.AuthenticationOptions{} 22 authResult, err := scalekitClient.AuthenticateWithCode( 23 c.Request.Context(), code, 24 "https://yourapp.com/auth/callback", 25 options, 26 ) 27 28 if err != nil { 29 log.Printf("Token exchange failed: %v", err) 30 c.Redirect(http.StatusFound, "/login?error=exchange_failed") 31 return 32 } 33 34 user := authResult.User 35 // accessToken := authResult.AccessToken 36 // refreshToken := authResult.RefreshToken 37 38 // TODO: Store user session (next guide covers this) 39 // session.Set("user", user) 40 41 c.Redirect(http.StatusFound, "/dashboard") 42 } ``` * Java Spring callback handler ```java 1 @GetMapping("/auth/callback") 2 public Object authCallback( 3 @RequestParam(required = false) String code, 4 @RequestParam(required = false) String error, 5 @RequestParam(required = false) String state, 6 HttpSession session 7 ) { 8 // TODO: Add state validation here (see previous step) 9 10 // Handle errors first 11 if (error != null) { 12 System.err.println("Authentication error: " + error); 13 return new RedirectView("/login?error=auth_failed"); 14 } 15 16 if (code == null) { 17 return new RedirectView("/login?error=missing_code"); 18 } 19 20 try { 21 // Exchange code for user data 22 AuthenticationOptions options = new AuthenticationOptions(); 23 AuthenticationResponse authResult = scalekit 24 .authentication() 25 .authenticateWithCode(code, "https://yourapp.com/auth/callback", options); 26 27 var user = authResult.getIdTokenClaims(); 28 // String accessToken = authResult.getAccessToken(); 29 // String refreshToken = authResult.getRefreshToken(); 30 31 // TODO: Store user session (next guide covers this) 32 // session.setAttribute("user", user); 33 34 return new RedirectView("/dashboard"); 35 36 } catch (Exception e) { 37 System.err.println("Token exchange failed: " + e.getMessage()); 38 return new RedirectView("/login?error=exchange_failed"); 39 } 40 } ``` The authorization `code` can be redeemed only once and expires in approx \~10 minutes. Reuse or replay attempts typically return errors like `invalid_grant`. If this occurs, start a new login flow to obtain a fresh `code` and `state`. The `authResult` object returned contains: ```js { user: { email: "john.doe@example.com", emailVerified: true, givenName: "John", name: "John Doe", id: "usr_74599896446906854" }, idToken: "eyJhbGciO..", // Decode for full user details accessToken: "eyJhbGciOi..", refreshToken: "rt_8f7d6e5c4b3a2d1e0f9g8h7i6j..", expiresIn: 299 // in seconds } ``` | Key | Description | | -------------- | ------------------------------------------------------------- | | `user` | Common user details with email, name, and verification status | | `idToken` | JWT containing verified full user identity claims | | `accessToken` | Short-lived token that determines current access | | `refreshToken` | Long-lived token to obtain new access tokens | 3. ## Decoding token claims [Section titled “Decoding token claims”](#decoding-token-claims) The `idToken` and `accessToken` are JSON Web Tokens (JWT) that contain user claims. These tokens can be decoded to retrieve comprehensive user and access information. * Node.js Decode ID token ```javascript 1 // Use a library like 'jsonwebtoken' 2 const jwt = require('jsonwebtoken'); 3 4 // The idToken from the authResult object 5 const { idToken } = authResult; 6 7 // Decode the token without verifying its signature 8 const decoded = jwt.decode(idToken); 9 10 console.log('Decoded claims:', decoded); ``` * Python Decode ID token ```python 1 # Use a library like 'PyJWT' 2 import jwt 3 4 # The id_token from the auth_result object 5 id_token = auth_result.id_token 6 7 # Decode the token without verifying its signature 8 decoded = jwt.decode(id_token, options={"verify_signature": False}) 9 print(f'Decoded claims: {decoded}') ``` * Go Decode ID token ```go 1 // Use a library like 'github.com/golang-jwt/jwt/v5' 2 import ( 3 "fmt" 4 "github.com/golang-jwt/jwt/v5" 5 ) 6 7 // The IdToken from the authResult object 8 idToken := authResult.IdToken 9 token, _, err := new(jwt.Parser).ParseUnverified(idToken, jwt.MapClaims{}) 10 if err != nil { 11 fmt.Printf("Error parsing token: %v\n", err) 12 return 13 } 14 15 if claims, ok := token.Claims.(jwt.MapClaims); ok { 16 fmt.Printf("Decoded claims: %+v\n", claims) 17 } ``` * Java Decode ID token ```java 1 // Use a library like 'com.auth0:java-jwt' 2 import com.auth0.jwt.JWT; 3 import com.auth0.jwt.interfaces.DecodedJWT; 4 import com.auth0.jwt.interfaces.Claim; 5 import com.auth0.jwt.exceptions.JWTDecodeException; 6 import java.util.Map; 7 8 try { 9 // The idToken from the authResult object 10 String idToken = authResult.getIdToken(); 11 12 // Decode the token without verifying its signature 13 DecodedJWT decodedJwt = JWT.decode(idToken); 14 Map claims = decodedJwt.getClaims(); 15 16 System.out.println("Decoded claims: " + claims); 17 } catch (JWTDecodeException exception){ 18 // Invalid token 19 System.err.println("Failed to decode ID token: " + exception.getMessage()); 20 } ``` The decoded token claims contain: * Decoded ID token ID token decoded ```json 1 { 2 "iss": "https://scalekit-z44iroqaaada-dev.scalekit.cloud", // Issuer: Scalekit environment URL (must match your environment) 3 "aud": ["skc_58327482062864390"], // Audience: Your client ID (must match for validation) 4 "azp": "skc_58327482062864390", // Authorized party: Usually same as aud 5 "sub": "usr_63261014140912135", // Subject: User's unique identifier 6 "oid": "org_59615193906282635", // Organization ID: User's organization 7 "exp": 1742975822, // Expiration: Unix timestamp (validate token hasn't expired) 8 "iat": 1742974022, // Issued at: Unix timestamp when token was issued 9 "at_hash": "ec_jU2ZKpFelCKLTRWiRsg", // Access token hash: For token binding validation 10 "c_hash": "6wMreK9kWQQY6O5R0CiiYg", // Authorization code hash: For code binding validation 11 "amr": ["conn_123"], // Authentication method reference: Connection ID used for auth 12 "email": "john.doe@example.com", // User's email address 13 "email_verified": true, // Email verification status 14 "name": "John Doe", // User's full name (optional) 15 "given_name": "John", // User's first name (optional) 16 "family_name": "Doe", // User's last name (optional) 17 "picture": "https://...", // Profile picture URL (optional) 18 "locale": "en", // User's locale preference (optional) 19 "sid": "ses_65274187031249433", // Session ID: Links token to user session 20 "client_id": "skc_58327482062864390", // Client ID: Your application identifier 21 "xoid": "ext_org_123", // External organization ID (if mapped) 22 } ``` * Decoded access token Decoded access token ```json 1 { 2 "iss": "https://login.devramp.ai", // Issuer: Scalekit environment URL (must match your environment) 3 "aud": ["prd_skc_7848964512134X699"], // Audience: Your client ID (must match for validation) 4 "sub": "usr_8967800122X995270", // Subject: User's unique identifier 5 "oid": "org_89678001X21929734", // Organization ID: User's organization 6 "exp": 1758265247, // Expiration: Unix timestamp (validate token hasn't expired) 7 "iat": 1758264947, // Issued at: Unix timestamp when token was issued 8 "nbf": 1758264947, // Not before: Unix timestamp (token valid from this time) 9 "jti": "tkn_90928731115292X63", // JWT ID: Unique token identifier 10 "sid": "ses_90928729571723X24", // Session ID: Links token to user session 11 "client_id": "prd_skc_7848964512134X699", // Client ID: Your application identifier 12 "roles": ["admin"], // Roles: User roles within organization (optional, for authorization) 13 "permissions": ["workspace_data:write", "workspace_data:read"], // Permissions: resource:action format (optional, for granular access control) 14 "scope": "openid profile email", // OAuth scopes granted (optional) 15 "xoid": "ext_org_123", // External organization ID (if mapped) 16 "xuid": "ext_usr_456" // External user ID (if mapped) 17 } ``` 4. ## Verifying access tokens optional [Section titled “Verifying access tokens ”](#verifying-access-tokens-) The Scalekit SDK provides methods to validate tokens automatically. When you use the SDK’s `validateAccessToken` method, it: 1. Verifies the token signature using Scalekit’s public keys 2. Checks the token hasn’t expired (`exp` claim) 3. Validates the issuer (`iss` claim) matches your environment 4. Ensures the audience (`aud` claim) matches your client ID If you need to manually verify tokens, fetch the public signing keys from the JSON Web Key Set (JWKS) endpoint: JWKS endpoint ```sh 1 https:///keys ``` For example, if your Scalekit Environment URL is `https://your-environment.scalekit.com`, the keys can be found at `https://your-environment.scalekit.com/keys`. An `IdToken` contains comprehensive profile information about the user. You can save this in your database for app use cases, using [your own identifier](/fsa/guides/organization-identifiers/). Now, let’s utilize *access and refresh tokens* to manage user access and maintain active sessions. ## Common login scenarios [Section titled “Common login scenarios”](#common-login-scenarios) Customize the login flow by passing different parameters when creating the authorization URL. These scenarios help you route users to specific organizations, force re-authentication, or direct users to signup. --- # DOCUMENT BOUNDARY --- # Initiate user signup or login > Create authorization URLs and redirect users to Scalekit's hosted login page 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 ```sh /oauth/authorize? response_type=code& # always `code` for authorization code flow client_id=& # Dashboard > Developers > Settings > API Credentials redirect_uri=& # Dashboard > Authentication > Redirect URLs > Allowed Callback URLs scope=openid+profile+email+offline_access& # Permissions requested. Include `offline_access` for refresh tokens 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 Recommended Use `login` to force re-authentication Use `create` to trigger sign up page Use `select_account` to select an account if they have multiple accounts | | `organization_id` | Skip routing the user to the hosted login page and route them to the social connection configured for the organization Optional | | `connection_id` | Skip routing the user to the hosted login page and route them to a specific social connection Optional | | `login_hint` | Used for [Home Realm Discovery](/authenticate/auth-methods/enterprise-sso/#identify-and-enforce-sso-for-organization-users). 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 [Section titled “Set up login flow”](#set-up-login-flow) 1. #### Add `state` parameter recommended [Section titled “Add state parameter ”](#add-state-parameter-) 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 ```javascript 1 // Generate secure random state 2 const state = require('crypto').randomBytes(32).toString('hex'); 3 // Store it temporarily (session, local storage, cache, etc) 4 sessionStorage.oauthState = state; ``` * Python Generate and store state ```python 1 import os 2 import secrets 3 4 # Generate secure random state 5 state = secrets.token_hex(32) 6 # Store it temporarily (session, local storage, cache, etc) 7 session['oauth_state'] = state ``` * Go Generate and store state ```go 1 import ( 2 "crypto/rand" 3 "encoding/hex" 4 ) 5 6 // Generate secure random state 7 b := make([]byte, 32) 8 rand.Read(b) 9 state := hex.EncodeToString(b) 10 // Store it temporarily (session, local storage, cache, etc) 11 // Example for Go: use a storage library 12 // session.Set("oauth_state", state) ``` * Java Generate and store state ```java 1 import java.security.SecureRandom; 2 import java.util.Base64; 3 4 // Generate secure random state 5 SecureRandom sr = new SecureRandom(); 6 byte[] randomBytes = new byte[32]; 7 sr.nextBytes(randomBytes); 8 String state = Base64.getUrlEncoder().withoutPadding().encodeToString(randomBytes); 9 // Store it temporarily (session, local storage, cache, etc) 10 // Example for Java: use any storage library 11 // session.setAttribute("oauth_state", state); ``` 2. #### Redirect to the authorization URL [Section titled “Redirect to the authorization URL”](#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 ```diff 1 import { Scalekit } from '@scalekit-sdk/node'; 2 3 const scalekit = new Scalekit(/* your credentials */); 4 5 // Basic authorization URL for general login 6 const redirectUri = 'https://yourapp.com/auth/callback'; 7 const options = { 8 scopes: ['openid', 'profile', 'email', 'offline_access'], 9 state: sessionStorage.oauthState, 10 }; 11 12 const authorizationUrl = scalekit.getAuthorizationUrl(redirectUri, options); 13 14 // Redirect user to Scalekit's hosted login page 15 res.redirect(authorizationUrl); ``` * Python Flask ```python 1 from scalekit import ScalekitClient, AuthorizationUrlOptions 2 3 scalekit = ScalekitClient(/* your credentials */) 4 5 # Basic authorization URL for general login 6 redirect_uri = 'https://yourapp.com/auth/callback' 7 options = AuthorizationUrlOptions( 8 scopes=['openid', 'profile', 'email', 'offline_access'], 9 state=session['oauth_state'] # Add this line 10 ) 11 12 authorization_url = scalekit.get_authorization_url(redirect_uri, options) 13 14 # Redirect user to Scalekit's hosted login page 15 return redirect(authorization_url) ``` * Go Gin ```go 1 import "github.com/scalekit-inc/scalekit-sdk-go" 2 3 scalekit := scalekit.NewScalekitClient(/* your credentials */) 4 5 // Basic authorization URL for general login 6 redirectUri := "https://yourapp.com/auth/callback" 7 options := scalekit.AuthorizationUrlOptions{ 8 Scopes: []string{"openid", "profile", "email", "offline_access"}, 9 State: "your_generated_state", // Add this line 10 } 11 12 authorizationUrl, err := scalekitClient.GetAuthorizationUrl(redirectUri, options) 13 14 // Redirect user to Scalekit's hosted login page 15 c.Redirect(http.StatusFound, authorizationUrl.String()) ``` * Java Spring ```java 1 import com.scalekit.ScalekitClient; 2 import com.scalekit.internal.http.AuthorizationUrlOptions; 3 4 ScalekitClient scalekit = new ScalekitClient(/* your credentials */); 5 6 // Basic authorization URL for general login 7 String redirectUri = "https://yourapp.com/auth/callback"; 8 AuthorizationUrlOptions options = new AuthorizationUrlOptions(); 9 options.setScopes(Arrays.asList("openid", "profile", "email", "offline_access")); 10 options.setState("your_generated_state"); // Add this line 11 12 URL authorizationUrl = scalekit.authentication().getAuthorizationUrl(redirectUri, options); 13 14 // Redirect user to Scalekit's hosted login page 15 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 [Section titled “Dedicated sign up flow”](#dedicated-sign-up-flow) Cases where your app wants to keep the sign up flow seperate and dedicated to creating the user account, you can use the `prompt: 'create'` parameter to redirect the user to the sign up page. * Node.js Express.js ```diff 1 const redirectUri = 'http://localhost:3000/api/callback'; 2 const options = { 3 scopes: ['openid', 'profile', 'email', 'offline_access'], 4 prompt: 'create', // explicitly takes you to sign up flow 5 }; 6 7 const authorizationUrl = scalekit.getAuthorizationUrl(redirectUri, options); 8 9 res.redirect(authorizationUrl); ``` * Python Flask ```diff 1 from scalekit import AuthorizationUrlOptions 2 3 redirect_uri = 'http://localhost:3000/api/callback' 4 options = AuthorizationUrlOptions() 5 options.scopes=['openid', 'profile', 'email', 'offline_access'] 6 options.prompt='create' # optional: explicitly takes you to sign up flow 7 8 authorization_url = scalekit.get_authorization_url(redirect_uri, options) 9 10 # For web frameworks like Flask/Django: 11 # return redirect(authorization_url) ``` * Go Gin ```diff 1 redirectUri := "http://localhost:3000/api/callback" 2 options := scalekit.AuthorizationUrlOptions{ 3 Scopes: []string{"openid", "profile", "email", "offline_access"}, 4 +Prompt: "create", // explicitly takes you to sign up flow 5 } 6 7 authorizationUrl, err := scalekitClient.GetAuthorizationUrl(redirectUri, options) 8 if err != nil { 9 // handle error appropriately 10 panic(err) 11 } 12 13 // For web frameworks like Gin: 14 // c.Redirect(http.StatusFound, authorizationUrl.String()) ``` * Java Spring ```diff 1 import com.scalekit.internal.http.AuthorizationUrlOptions; 2 import java.net.URL; 3 import java.util.Arrays; 4 5 String redirectUri = "http://localhost:3000/api/callback"; 6 AuthorizationUrlOptions options = new AuthorizationUrlOptions(); 7 options.setScopes(Arrays.asList("openid", "profile", "email", "offline_access")); 8 +options.setPrompt("create"); 9 10 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. --- # DOCUMENT BOUNDARY --- # Assign roles to users > Learn how to assign roles to users in your application using to dashboard, SDK, or automated provisioning After registering roles and permissions for your application, Scalekit provides multiple ways to assign roles to users. These roles allow your app to make the access control decisions as scalekit sends them to your app in the access token. ## Auto assign roles as users join organizations [Section titled “Auto assign roles as users join organizations”](#auto-assign-roles-as-users-join-organizations) By default, the organization creator automatically receives the `admin` role, while users who join later receive the `member` role. You can customize these defaults to match your application’s security requirements. For instance, in a CRM system, you may want to set the default role for new members to a read-only role like `viewer` to prevent accidental data modifications. 1. Go to **Dashboard** > **Roles & Permissions** > **Roles** tab 2. Select the roles available and choose defaults for organization creator and member  This automatically assigns these roles to every users who joins any organization in your Scalekit environment. ## Set a default role for new organization members [Section titled “Set a default role for new organization members”](#set-a-default-role-for-new-organization-members) You can also configure a default role that is automatically assigned to users who join a specific organization. This organization-level setting **overrides** the application-level default role described above, allowing finer-grained control per organization.  ## Let users assign roles to others API [Section titled “Let users assign roles to others ”](#let-users-assign-roles-to-others-) Enable organization administrators to manage user roles directly within your application. By building features like “Change role” or “Assign permissions” into your app, you can provide a management experience without requiring administrators to leave your app. To implement role assignment functionality, follow these essential prerequisites: 1. **Verify administrator permissions**: Ensure the user performing the role assignment has the `admin` role or an equivalent role with the necessary permissions. Check the `permissions` property in their access token to confirm they have role management capabilities. * Node.js Verify permissions ```javascript 1 // Decode JWT and check admin permissions 2 const decodedToken = decodeJWT(adminAccessToken); 3 4 // Check if user has admin role or required permissions 5 const isAdmin = decodedToken.roles.includes('admin'); 6 const hasPermission = decodedToken.permissions?.includes('users.write') || 7 decodedToken.permissions?.includes('roles.assign'); 8 9 if (!isAdmin && !hasPermission) { 10 throw new Error('Insufficient permissions to assign roles'); 11 } ``` * Python Verify permissions ```python 1 # Decode JWT and check admin permissions 2 decoded_token = decode_jwt(access_token) 3 4 # Check if user has admin role or required permissions 5 is_admin = 'admin' in decoded_token.get('roles', []) 6 has_permission = any(perm in decoded_token.get('permissions', []) 7 for perm in ['users.write', 'roles.assign']) 8 9 if not is_admin and not has_permission: 10 raise PermissionError("Insufficient permissions to assign roles") ``` * Go Verify permissions ```go 1 // Decode JWT and check admin permissions 2 decodedToken, err := decodeJWT(accessToken) 3 if err != nil { 4 return ValidationResult{Success: false, Error: "Invalid token"} 5 } 6 7 // Check if user has admin role or required permissions 8 roles := decodedToken["roles"].([]interface{}) 9 permissions := decodedToken["permissions"].([]interface{}) 10 11 isAdmin := false 12 hasPermission := false 13 14 for _, role := range roles { 15 if role == "admin" { 16 isAdmin = true 17 break 18 } 19 } 20 21 for _, perm := range permissions { 22 if perm == "users.write" || perm == "roles.assign" { 23 hasPermission = true 24 break 25 } 26 } 27 28 if !isAdmin && !hasPermission { 29 return ValidationResult{Success: false, Error: "Insufficient permissions"} 30 } ``` * Java Verify permissions ```java 1 // Decode JWT and check admin permissions 2 Claims decodedToken = decodeJWT(accessToken); 3 4 @SuppressWarnings("unchecked") 5 List userRoles = (List) decodedToken.get("roles"); 6 @SuppressWarnings("unchecked") 7 List permissions = (List) decodedToken.get("permissions"); 8 9 // Check if user has admin role or required permissions 10 boolean isAdmin = userRoles != null && userRoles.contains("admin"); 11 boolean hasPermission = permissions != null && 12 (permissions.contains("users.write") || permissions.contains("roles.assign")); 13 14 if (!isAdmin && !hasPermission) { 15 throw new SecurityException("Insufficient permissions to assign roles"); 16 } ``` 2. **Collect required identifiers**: Gather the necessary parameters for the API call: * `user_id`: The unique identifier of the user whose role you’re changing * `organization_id`: The organization where the role assignment applies * `roles`: An array of role names to assign to the user - Node.js Collect and validate identifiers ```javascript 1 // Structure and validate role assignment data 2 const roleAssignmentData = { 3 user_id: targetUserId, 4 organization_id: targetOrgId, 5 roles: newRoles, 6 // Additional metadata for auditing 7 performed_by: decodedToken.sub, 8 timestamp: new Date().toISOString() 9 }; 10 11 // Validate required fields 12 if (!roleAssignmentData.user_id || !roleAssignmentData.organization_id || !roleAssignmentData.roles) { 13 throw new Error('Missing required identifiers for role assignment'); 14 } ``` - Python Collect and validate identifiers ```python 1 # Structure and validate role assignment data 2 role_assignment_data = { 3 'user_id': target_user_id, 4 'organization_id': target_org_id, 5 'roles': new_roles, 6 # Additional metadata for auditing 7 'performed_by': decoded_token.get('sub'), 8 'timestamp': datetime.utcnow().isoformat() 9 } 10 11 # Validate required fields 12 if not all([role_assignment_data['user_id'], 13 role_assignment_data['organization_id'], 14 role_assignment_data['roles']]): 15 raise ValueError("Missing required identifiers for role assignment") ``` - Go Collect and validate identifiers ```go 1 // Structure and validate role assignment data 2 roleAssignmentData := map[string]interface{}{ 3 "user_id": req.UserID, 4 "organization_id": req.OrganizationID, 5 "roles": req.Roles, 6 // Additional metadata for auditing 7 "performed_by": decodedToken["sub"], 8 "timestamp": time.Now().UTC().Format(time.RFC3339), 9 } 10 11 // Validate required fields 12 if req.UserID == "" || req.OrganizationID == "" || len(req.Roles) == 0 { 13 return ValidationResult{Success: false, Error: "Missing required identifiers"} 14 } ``` - Java Collect and validate identifiers ```java 1 // Structure and validate role assignment data 2 Map roleAssignmentData = new HashMap<>(); 3 roleAssignmentData.put("user_id", request.userId); 4 roleAssignmentData.put("organization_id", request.organizationId); 5 roleAssignmentData.put("roles", request.roles); 6 7 // Additional metadata for auditing 8 roleAssignmentData.put("performed_by", decodedToken.getSubject()); 9 roleAssignmentData.put("timestamp", Instant.now().toString()); 10 11 // Validate required fields 12 if (request.userId == null || request.organizationId == null || request.roles == null) { 13 throw new IllegalArgumentException("Missing required identifiers for role assignment"); 14 } ``` 3. **Call Scalekit SDK to update user role**: Use the validated data to make the API call that assigns the new roles to the user through the Scalekit membership update endpoint. * Node.js Update user role with Scalekit SDK ```javascript 1 // Use case: Update user membership after validation 2 const validationResult = await prepareRoleAssignment( 3 adminAccessToken, 4 targetUserId, 5 targetOrgId, 6 newRoles 7 ); 8 9 if (!validationResult.success) { 10 return res.status(403).json({ error: validationResult.error }); 11 } 12 13 // Initialize Scalekit client (reference installation guide for setup) 14 const scalekit = new ScalekitClient( 15 process.env.SCALEKIT_ENVIRONMENT_URL, 16 process.env.SCALEKIT_CLIENT_ID, 17 process.env.SCALEKIT_CLIENT_SECRET 18 ); 19 20 // Make the API call to update user roles 21 try { 22 const result = await scalekit.user.updateMembership({ 23 user_id: validationResult.data.user_id, 24 organization_id: validationResult.data.organization_id, 25 roles: validationResult.data.roles 26 }); 27 28 console.log(`Role assigned successfully:`, result); 29 return res.json({ 30 success: true, 31 message: "Role updated successfully", 32 data: result 33 }); 34 } catch (error) { 35 console.error(`Failed to assign role: ${error.message}`); 36 return res.status(500).json({ 37 error: "Failed to update role", 38 details: error.message 39 }); 40 } ``` * Python Update user role with Scalekit SDK ```python 1 # Use case: Update user membership after validation 2 validation_result = prepare_role_assignment( 3 access_token, 4 target_user_id, 5 target_org_id, 6 new_roles 7 ) 8 9 if not validation_result['success']: 10 return jsonify({'error': validation_result['error']}), 403 11 12 # Initialize Scalekit client (reference installation guide for setup) 13 scalekit_client = ScalekitClient( 14 env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"), 15 client_id=os.getenv("SCALEKIT_CLIENT_ID"), 16 client_secret=os.getenv("SCALEKIT_CLIENT_SECRET") 17 ) 18 19 # Make the API call to update user roles 20 try: 21 from scalekit.v1.users.users_pb2 import UpdateMembershipRequest 22 23 request = UpdateMembershipRequest( 24 user_id=validation_result['data']['user_id'], 25 organization_id=validation_result['data']['organization_id'], 26 roles=validation_result['data']['roles'] 27 ) 28 29 result = scalekit_client.users.update_membership(request=request) 30 print(f"Role assigned successfully: {result}") 31 32 return jsonify({ 33 'success': True, 34 'message': 'Role updated successfully', 35 'data': str(result) 36 }) 37 38 except Exception as error: 39 print(f"Failed to assign role: {error}") 40 return jsonify({ 41 'error': 'Failed to update role', 42 'details': str(error) 43 }), 500 ``` * Go Update user role with Scalekit SDK ```go 1 // Use case: Update user membership after validation 2 validationResult := prepareRoleAssignment(ctx, accessToken, req) 3 4 if !validationResult.Success { 5 http.Error(w, validationResult.Error, http.StatusForbidden) 6 return 7 } 8 9 // Initialize Scalekit client (reference installation guide for setup) 10 scalekitClient := scalekit.NewScalekitClient( 11 os.Getenv("SCALEKIT_ENVIRONMENT_URL"), 12 os.Getenv("SCALEKIT_CLIENT_ID"), 13 os.Getenv("SCALEKIT_CLIENT_SECRET"), 14 ) 15 16 // Make the API call to update user roles 17 data := validationResult.Data.(map[string]interface{}) 18 updateRequest := &scalekit.UpdateMembershipRequest{ 19 UserId: data["user_id"].(string), 20 OrganizationId: data["organization_id"].(string), 21 Roles: data["roles"].([]string), 22 } 23 24 result, err := scalekitClient.Membership().UpdateMembership(ctx, updateRequest) 25 if err != nil { 26 log.Printf("Failed to assign role: %v", err) 27 http.Error(w, "Failed to update role", http.StatusInternalServerError) 28 return 29 } 30 31 log.Printf("Role assigned successfully: %+v", result) 32 json.NewEncoder(w).Encode(map[string]interface{}{ 33 "success": true, 34 "message": "Role updated successfully", 35 "data": result, 36 }) ``` * Java Update user role with Scalekit SDK ```java 1 // Use case: Update user membership after validation 2 ValidationResult validationResult = prepareRoleAssignment(accessToken, request); 3 4 if (!validationResult.success) { 5 return ResponseEntity.status(403).body(Map.of("error", validationResult.error)); 6 } 7 8 // Initialize Scalekit client (reference installation guide for setup) 9 ScalekitClient scalekitClient = new ScalekitClient( 10 System.getenv("SCALEKIT_ENVIRONMENT_URL"), 11 System.getenv("SCALEKIT_CLIENT_ID"), 12 System.getenv("SCALEKIT_CLIENT_SECRET") 13 ); 14 15 // Make the API call to update user roles 16 try { 17 @SuppressWarnings("unchecked") 18 Map data = (Map) validationResult.data; 19 20 UpdateMembershipRequest updateRequest = UpdateMembershipRequest.newBuilder() 21 .setUserId((String) data.get("user_id")) 22 .setOrganizationId((String) data.get("organization_id")) 23 .addAllRoles((List) data.get("roles")) 24 .build(); 25 26 UpdateMembershipResponse response = scalekitClient.users().updateMembership(updateRequest); 27 System.out.println("Role assigned successfully: " + response); 28 29 return ResponseEntity.ok(Map.of( 30 "success", true, 31 "message", "Role updated successfully", 32 "data", response.toString() 33 )); 34 35 } catch (Exception e) { 36 System.err.println("Failed to assign role: " + e.getMessage()); 37 return ResponseEntity.status(500).body(Map.of( 38 "error", "Failed to update role", 39 "details", e.getMessage() 40 )); 41 } ``` 4. **Handle response and provide feedback**: Return appropriate success/error responses to the administrator and update your application’s UI accordingly. * Node.js Handle API response ```javascript 1 // Success response handling 2 if (result.success) { 3 // Update UI to reflect role change 4 await updateUserInterface(targetUserId, newRoles); 5 6 // Send notification to user (optional) 7 await notifyUserOfRoleChange(targetUserId, newRoles); 8 9 // Log the action for audit purposes 10 await logRoleChange({ 11 performed_by: decodedToken.sub, 12 target_user: targetUserId, 13 organization: targetOrgId, 14 old_roles: previousRoles, 15 new_roles: newRoles, 16 timestamp: new Date().toISOString() 17 }); 18 } ``` * Python Handle API response ```python 1 # Success response handling 2 if result.get('success'): 3 # Update UI to reflect role change 4 await update_user_interface(target_user_id, new_roles) 5 6 # Send notification to user (optional) 7 await notify_user_of_role_change(target_user_id, new_roles) 8 9 # Log the action for audit purposes 10 await log_role_change({ 11 'performed_by': decoded_token.get('sub'), 12 'target_user': target_user_id, 13 'organization': target_org_id, 14 'old_roles': previous_roles, 15 'new_roles': new_roles, 16 'timestamp': datetime.utcnow().isoformat() 17 }) ``` * Go Handle API response ```go 1 // Success response handling 2 if success { 3 // Update UI to reflect role change 4 updateUserInterface(targetUserID, newRoles) 5 6 // Send notification to user (optional) 7 notifyUserOfRoleChange(targetUserID, newRoles) 8 9 // Log the action for audit purposes 10 logRoleChange(map[string]interface{}{ 11 "performed_by": decodedToken["sub"], 12 "target_user": targetUserID, 13 "organization": targetOrgID, 14 "old_roles": previousRoles, 15 "new_roles": newRoles, 16 "timestamp": time.Now().UTC().Format(time.RFC3339), 17 }) 18 } ``` * Java Handle API response ```java 1 // Success response handling 2 if (response.getBody().containsKey("success") && 3 Boolean.TRUE.equals(response.getBody().get("success"))) { 4 5 // Update UI to reflect role change 6 updateUserInterface(targetUserId, newRoles); 7 8 // Send notification to user (optional) 9 notifyUserOfRoleChange(targetUserId, newRoles); 10 11 // Log the action for audit purposes 12 logRoleChange(Map.of( 13 "performed_by", decodedToken.getSubject(), 14 "target_user", targetUserId, 15 "organization", targetOrgId, 16 "old_roles", previousRoles, 17 "new_roles", newRoles, 18 "timestamp", Instant.now().toString() 19 )); 20 } ``` --- # DOCUMENT BOUNDARY --- # Create and manage roles and permissions > Set up roles and permissions to control access in your application Before writing any code, take a moment to plan your application’s authorization model. A well-designed structure for roles and permissions is crucial for security and maintainability. Start by considering the following questions: * What are the actions your users can perform? * How many distinct roles does your application need? Your application’s use cases will determine the answers. Here are a few common patterns: * **Simple roles**: Some applications, like an online whiteboarding tool, may only need a few roles with implicit permissions. For example, `Admin`, `Editor`, and `Viewer`. In this case, you might not even need to define granular permissions. * **Pre-defined roles and permissions**: Many applications have a fixed set of roles built from specific permissions. For a project management tool, you could define permissions like `projects:create` and `tasks:assign`, then group them into roles like `Project Manager` and `Team Member`. * **Customer-defined Roles**: For complex applications, you might allow organization owners to create custom roles with a specific set of permissions. These roles are specific to an organization rather than global to your application. Scalekit provides the flexibility to build authorization for any of these use cases. Once you have a clear plan, you can start creating your permissions and roles. Define the permissions your application needs by registering them with Scalekit. Use the `resource:action` format for clear, self-documenting permission names. You can skip this step, in case permissions may not fit your app’s authorization model. 1. ## Define the actions your users can perform as permissions [Section titled “Define the actions your users can perform as permissions”](#define-the-actions-your-users-can-perform-as-permissions) * Node.js Create permissions ```javascript 1 // Initialize Scalekit client 2 // Use case: Register all available actions in your project management app 3 import { ScalekitClient } from "@scalekit-sdk/node"; 4 5 const scalekit = new ScalekitClient( 6 process.env.SCALEKIT_ENVIRONMENT_URL, 7 process.env.SCALEKIT_CLIENT_ID, 8 process.env.SCALEKIT_CLIENT_SECRET 9 ); 10 11 // Define your application's permissions 12 const permissions = [ 13 { 14 name: "projects:create", 15 description: "Allows users to create new projects" 16 }, 17 { 18 name: "projects:read", 19 description: "Allows users to view project details" 20 }, 21 { 22 name: "projects:update", 23 description: "Allows users to modify existing projects" 24 }, 25 { 26 name: "projects:delete", 27 description: "Allows users to remove projects" 28 }, 29 { 30 name: "tasks:assign", 31 description: "Allows users to assign tasks to team members" 32 } 33 ]; 34 35 // Register each permission with Scalekit 36 for (const permission of permissions) { 37 await scalekit.permission.createPermission(permission); 38 console.log(`Created permission: ${permission.name}`); 39 } 40 41 // Your application's permissions are now registered with Scalekit ``` * Python Create permissions ```python 1 # Initialize Scalekit client 2 # Use case: Register all available actions in your project management app 3 from scalekit import ScalekitClient 4 5 scalekit_client = ScalekitClient( 6 env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"), 7 client_id=os.getenv("SCALEKIT_CLIENT_ID"), 8 client_secret=os.getenv("SCALEKIT_CLIENT_SECRET") 9 ) 10 11 # Define your application's permissions 12 from scalekit.v1.roles.roles_pb2 import CreatePermission 13 14 permissions = [ 15 CreatePermission( 16 name="projects:create", 17 description="Allows users to create new projects" 18 ), 19 CreatePermission( 20 name="projects:read", 21 description="Allows users to view project details" 22 ), 23 CreatePermission( 24 name="projects:update", 25 description="Allows users to modify existing projects" 26 ), 27 CreatePermission( 28 name="projects:delete", 29 description="Allows users to remove projects" 30 ), 31 CreatePermission( 32 name="tasks:assign", 33 description="Allows users to assign tasks to team members" 34 ) 35 ] 36 37 # Register each permission with Scalekit 38 for permission in permissions: 39 scalekit_client.permissions.create_permission(permission=permission) 40 print(f"Created permission: {permission.name}") 41 42 # Your application's permissions are now registered with Scalekit ``` * Go Create permissions ```go 1 // Initialize Scalekit client 2 // Use case: Register all available actions in your project management app 3 package main 4 5 import ( 6 "context" 7 "log" 8 "github.com/scalekit-inc/scalekit-sdk-go" 9 ) 10 11 func main() { 12 sc := scalekit.NewScalekitClient( 13 os.Getenv("SCALEKIT_ENVIRONMENT_URL"), 14 os.Getenv("SCALEKIT_CLIENT_ID"), 15 os.Getenv("SCALEKIT_CLIENT_SECRET"), 16 ) 17 18 // Define your application's permissions 19 permissions := []*scalekit.CreatePermission{ 20 { 21 Name: "projects:create", 22 Description: "Allows users to create new projects", 23 }, 24 { 25 Name: "projects:read", 26 Description: "Allows users to view project details", 27 }, 28 { 29 Name: "projects:update", 30 Description: "Allows users to modify existing projects", 31 }, 32 { 33 Name: "projects:delete", 34 Description: "Allows users to remove projects", 35 }, 36 { 37 Name: "tasks:assign", 38 Description: "Allows users to assign tasks to team members", 39 }, 40 } 41 42 // Register each permission with Scalekit 43 for _, permission := range permissions { 44 _, err := sc.Permission().CreatePermission(ctx, permission) 45 if err != nil { 46 log.Printf("Failed to create permission: %s", permission.Name) 47 continue 48 } 49 fmt.Printf("Created permission: %s\n", permission.Name) 50 } 51 52 // Your application's permissions are now registered with Scalekit 53 } ``` * Java Create permissions ```java 1 // Initialize Scalekit client 2 // Use case: Register all available actions in your project management app 3 import com.scalekit.ScalekitClient; 4 import com.scalekit.grpc.scalekit.v1.roles.*; 5 6 ScalekitClient scalekitClient = new ScalekitClient( 7 System.getenv("SCALEKIT_ENVIRONMENT_URL"), 8 System.getenv("SCALEKIT_CLIENT_ID"), 9 System.getenv("SCALEKIT_CLIENT_SECRET") 10 ); 11 12 // Define your application's permissions 13 List permissions = Arrays.asList( 14 CreatePermission.newBuilder() 15 .setName("projects:create") 16 .setDescription("Allows users to create new projects") 17 .build(), 18 CreatePermission.newBuilder() 19 .setName("projects:read") 20 .setDescription("Allows users to view project details") 21 .build(), 22 CreatePermission.newBuilder() 23 .setName("projects:update") 24 .setDescription("Allows users to modify existing projects") 25 .build(), 26 CreatePermission.newBuilder() 27 .setName("projects:delete") 28 .setDescription("Allows users to remove projects") 29 .build(), 30 CreatePermission.newBuilder() 31 .setName("tasks:assign") 32 .setDescription("Allows users to assign tasks to team members") 33 .build() 34 ); 35 36 // Register each permission with Scalekit 37 for (CreatePermission permission : permissions) { 38 try { 39 CreatePermissionRequest request = CreatePermissionRequest.newBuilder() 40 .setPermission(permission) 41 .build(); 42 43 scalekitClient.permissions().createPermission(request); 44 System.out.println("Created permission: " + permission.getName()); 45 } catch (Exception e) { 46 System.err.println("Error creating permission: " + e.getMessage()); 47 } 48 } 49 50 // Your application's permissions are now registered with Scalekit ``` 2. ## Register roles your applications will use [Section titled “Register roles your applications will use”](#register-roles-your-applications-will-use) Once you have defined permissions, group them into roles that match your application’s access patterns. * Node.js Create roles with permissions ```javascript 1 // Define roles with their associated permissions 2 // Use case: Create standard roles for your project management application 3 const roles = [ 4 { 5 name: 'project_admin', 6 display_name: 'Project Administrator', 7 description: 'Full access to manage projects and team members', 8 permissions: [ 9 'projects:create', 'projects:read', 'projects:update', 'projects:delete', 10 'tasks:assign' 11 ] 12 }, 13 { 14 name: 'project_manager', 15 display_name: 'Project Manager', 16 description: 'Can manage projects and assign tasks', 17 permissions: [ 18 'projects:create', 'projects:read', 'projects:update', 19 'tasks:assign' 20 ] 21 }, 22 { 23 name: 'team_member', 24 display_name: 'Team Member', 25 description: 'Can view projects and participate in tasks', 26 permissions: [ 27 'projects:read' 28 ] 29 } 30 ]; 31 32 // Register each role with Scalekit 33 for (const role of roles) { 34 await scalekit.role.createRole(role); 35 console.log(`Created role: ${role.name}`); 36 } 37 38 // Your application's roles are now registered with Scalekit ``` * Python Create roles with permissions ```python 1 # Define roles with their associated permissions 2 # Use case: Create standard roles for your project management application 3 from scalekit.v1.roles.roles_pb2 import CreateRole 4 5 roles = [ 6 CreateRole( 7 name="project_admin", 8 display_name="Project Administrator", 9 description="Full access to manage projects and team members", 10 permissions=["projects:create", "projects:read", "projects:update", "projects:delete", "tasks:assign"] 11 ), 12 CreateRole( 13 name="project_manager", 14 display_name="Project Manager", 15 description="Can manage projects and assign tasks", 16 permissions=["projects:create", "projects:read", "projects:update", "tasks:assign"] 17 ), 18 CreateRole( 19 name="team_member", 20 display_name="Team Member", 21 description="Can view projects and participate in tasks", 22 permissions=["projects:read"] 23 ) 24 ] 25 26 # Register each role with Scalekit 27 for role in roles: 28 scalekit_client.roles.create_role(role=role) 29 print(f"Created role: {role.name}") 30 31 # Your application's roles are now registered with Scalekit ``` * Go Create roles with permissions ```go 1 // Define roles with their associated permissions 2 // Use case: Create standard roles for your project management application 3 roles := []*scalekit.CreateRole{ 4 { 5 Name: "project_admin", 6 DisplayName: "Project Administrator", 7 Description: "Full access to manage projects and team members", 8 Permissions: []string{"projects:create", "projects:read", "projects:update", "projects:delete", "tasks:assign"}, 9 }, 10 { 11 Name: "project_manager", 12 DisplayName: "Project Manager", 13 Description: "Can manage projects and assign tasks", 14 Permissions: []string{"projects:create", "projects:read", "projects:update", "tasks:assign"}, 15 }, 16 { 17 Name: "team_member", 18 DisplayName: "Team Member", 19 Description: "Can view projects and participate in tasks", 20 Permissions: []string{"projects:read"}, 21 }, 22 } 23 24 // Register each role with Scalekit 25 for _, role := range roles { 26 _, err := sc.Role().CreateRole(ctx, role) 27 if err != nil { 28 log.Printf("Failed to create role: %s", role.Name) 29 continue 30 } 31 fmt.Printf("Created role: %s\n", role.Name) 32 } 33 34 // Your application's roles are now registered with Scalekit ``` * Java Create roles with permissions ```java 1 // Define roles with their associated permissions 2 // Use case: Create standard roles for your project management application 3 List roles = Arrays.asList( 4 CreateRole.newBuilder() 5 .setName("project_admin") 6 .setDisplayName("Project Administrator") 7 .setDescription("Full access to manage projects and team members") 8 .addAllPermissions(Arrays.asList("projects:create", "projects:read", "projects:update", "projects:delete", "tasks:assign")) 9 .build(), 10 CreateRole.newBuilder() 11 .setName("project_manager") 12 .setDisplayName("Project Manager") 13 .setDescription("Can manage projects and assign tasks") 14 .addAllPermissions(Arrays.asList("projects:create", "projects:read", "projects:update", "tasks:assign")) 15 .build(), 16 CreateRole.newBuilder() 17 .setName("team_member") 18 .setDisplayName("Team Member") 19 .setDescription("Can view projects and participate in tasks") 20 .addPermissions("projects:read") 21 .build() 22 ); 23 24 // Register each role with Scalekit 25 for (CreateRole role : roles) { 26 try { 27 CreateRoleRequest request = CreateRoleRequest.newBuilder() 28 .setRole(role) 29 .build(); 30 31 scalekitClient.roles().createRole(request); 32 System.out.println("Created role: " + role.getName()); 33 } catch (Exception e) { 34 System.err.println("Error creating role: " + e.getMessage()); 35 } 36 } 37 38 // Your application's roles are now registered with Scalekit ``` ## Inherit permissions through roles [Section titled “Inherit permissions through roles”](#inherit-permissions-through-roles) Large applications with extensive feature sets require sophisticated role and permission management. Scalekit enables role inheritance, allowing you to create a hierarchical access control system. Permissions can be grouped into roles, and new roles can be derived from existing base roles, providing a flexible and scalable approach to defining user access. Role assignment in Scalekit automatically grants a user all permissions defined within that role. This is how you can implement use it: 1. Your app defines the permissions and assigns to a role. Let’s say `viewer` role. 2. When creating new role called `editor`, you specify that it inherits the permissions from the `viewer` role. 3. When creating new role called `project_owner`, you specify that it inherits the permissions from the `editor` role. Take a look at our [Roles and Permissions APIs](https://docs.scalekit.com/apis/#tag/roles/get/api/v1/roles). ## Manage roles and permissions in the dashboard [Section titled “Manage roles and permissions in the dashboard”](#manage-roles-and-permissions-in-the-dashboard) For most applications, the simplest way to create and manage roles and permissions is through the Scalekit dashboard. This approach works well when you have a fixed set of roles and permissions that don’t need to be modified by users in your application. You can set up your authorization model once during application configuration and manage it through the dashboard going forward.  1. Navigate to **Dashboard** > **Roles & Permissions** > **Permissions** to create permissions: * Click **Create Permission** and provide: * **Name** - Machine-friendly identifier (e.g., `projects:create`) * **Display Name** - Human-readable label (e.g., “Create Projects”) * **Description** - Clear explanation of what this permission allows 2. Go to **Dashboard** > **Roles & Permissions** > **Roles** to create roles: * Click **Create Role** and provide: * **Name** - Machine-friendly identifier (e.g., `project_manager`) * **Display Name** - Human-readable label (e.g., “Project Manager”) * **Description** - Clear explanation of the role’s purpose * **Permissions** - Select the permissions to include in this role 3. Configure default roles for new users who join organizations 4. Organization administrators can create organization-specific roles by going to **Dashboard** > **Organizations** > **Select organization** > **Roles** Now that you have created roles and permissions in Scalekit, the next step is to assign these roles to users in your application. ### Configure organization specific roles [Section titled “Configure organization specific roles”](#configure-organization-specific-roles) Organization-level roles let organization administrators create custom roles that apply only within their specific organization. These roles are separate from any application-level roles you define.  You can create organization-level roles from the Scalekit Dashboard: * Go to **Organizations → Select an organization → Roles** * In **Organization roles** section, Click **+ Add role** and provide: * **Display name**: Human-readable name (e.g., “Manager”) * **Name (key)**: Machine-friendly identifier (e.g., `manager`) * **Description**: Clear explanation of what users with this role can do --- # DOCUMENT BOUNDARY --- # Implement access control > Verify permissions and roles in your application code to control user access After configuring permissions and roles, the next critical step is implementing access control directly within your application code. This is achieved by carefully examining the roles and permissions embedded in the user’s access token to make authorization decisions. Scalekit conveniently packages these authorization details during the authentication process, providing you with a comprehensive set of data to make precise access control decisions without requiring additional API calls. This section focuses on implementing access control, which naturally follows user authentication. We recommend completing the authentication [quickstart](/authenticate/fsa/quickstart) before diving into these access control implementation details. ## Start by inspecting the access token [Section titled “Start by inspecting the access token”](#start-by-inspecting-the-access-token) When you [exchange the code for a user profile](/authenticate/fsa/complete-login/), Scalekit also adds additional information that help your app determine the access control decisions. * Auth result ```js 1 { 2 user: { 3 email: "john.doe@example.com", 4 emailVerified: true, 5 givenName: "John", 6 name: "John Doe", 7 id: "usr_74599896446906854" 8 }, 9 idToken: "eyJhbGciO..", // Decode for full user details 10 11 accessToken: "eyJhbGciOi..", 12 refreshToken: "rt_8f7d6e5c4b3a2d1e0f9g8h7i6j..", 13 expiresIn: 299 // in seconds 14 } ``` * Decoded ID token ID token decoded ```json 1 { 2 "at_hash": "ec_jU2ZKpFelCKLTRWiRsg", 3 "aud": [ 4 "skc_58327482062864390" 5 ], 6 "azp": "skc_58327482062864390", 7 "c_hash": "6wMreK9kWQQY6O5R0CiiYg", 8 "client_id": "skc_58327482062864390", 9 "email": "john.doe@example.com", 10 "email_verified": true, 11 "exp": 1742975822, 12 "family_name": "Doe", 13 "given_name": "John", 14 "iat": 1742974022, 15 "iss": "https://scalekit-z44iroqaaada-dev.scalekit.cloud", 16 "name": "John Doe", 17 "oid": "org_59615193906282635", 18 "sid": "ses_65274187031249433", 19 "sub": "usr_63261014140912135" 20 } ``` * Decoded access token Decoded access token ```json 1 { 2 "aud": [ 3 "prd_skc_7848964512134X699" 4 ], 5 "client_id": "prd_skc_7848964512134X699", 6 "exp": 1758265247, 7 "iat": 1758264947, 8 "iss": "https://login.devramp.ai", 9 "jti": "tkn_90928731115292X63", 10 "nbf": 1758264947, 11 "oid": "org_89678001X21929734", 12 "permissions": [ 13 "workspace_data:write", 14 "workspace_data:read" 15 ], 16 "roles": [ 17 "admin" 18 ], 19 "sid": "ses_90928729571723X24", 20 "sub": "usr_8967800122X995270", 21 // External identifiers if updated on Scalekit 22 "xoid": "ext_org_123", // Organization ID 23 "xuid": "ext_usr_456", // User ID 24 } ``` Let’s closely look at the access token: Decoded access token ```json { "aud": ["skc_987654321098765432"], "client_id": "skc_987654321098765432", "exp": 1750850145, "iat": 1750849845, "iss": "http://example.localhost:8889", "jti": "tkn_987654321098765432", "nbf": 1750849845, "roles": ["project_manager", "member"], "oid": "org_69615647365005430", "permissions": ["projects:create", "projects:read", "projects:update", "tasks:assign"], "sid": "ses_987654321098765432", "sub": "usr_987654321098765432" } ``` The `roles` and `permissions` values provide runtime insights into the user’s access constraints directly within the access token, eliminating the need for additional API requests. Crucially, always validate the token’s integrity before relying on the embedded authorization details. * Node.js Validate and decode access token in middleware ```javascript 1 // Middleware to validate tokens and extract authorization data 2 const validateAndExtractAuth = async (req, res, next) => { 3 try { 4 // Extract access token from cookie (decrypt if needed) 5 const accessToken = decrypt(req.cookies.accessToken); 6 7 // Validate the token using Scalekit SDK 8 const isValid = await scalekit.validateAccessToken(accessToken); 9 10 if (!isValid) { 11 return res.status(401).json({ error: 'Invalid or expired token' }); 12 } 13 14 // Decode token to get roles and permissions using any JWT decode library 15 const tokenData = await decodeAccessToken(accessToken); 16 17 // Make authorization data available to route handlers 18 req.user = { 19 id: tokenData.sub, 20 organizationId: tokenData.oid, 21 roles: tokenData.roles || [], 22 permissions: tokenData.permissions || [] 23 }; 24 25 next(); 26 } catch (error) { 27 return res.status(401).json({ error: 'Authentication failed' }); 28 } 29 }; ``` * Python Validate and decode access token ```python 1 from scalekit import ScalekitClient 2 from functools import wraps 3 import jwt 4 5 scalekit_client = ScalekitClient(/* your credentials */) 6 7 def validate_and_extract_auth(f): 8 @wraps(f) 9 def decorated_function(*args, **kwargs): 10 try: 11 # Extract access token from cookie (decrypt if needed) 12 access_token = decrypt(request.cookies.get('accessToken')) 13 14 # Validate the token using Scalekit SDK 15 is_valid = scalekit_client.validate_access_token(access_token) 16 17 if not is_valid: 18 return jsonify({'error': 'Invalid or expired token'}), 401 19 20 # Decode token to get roles and permissions 21 token_data = scalekit_client.decode_access_token(access_token) 22 23 # Make authorization data available to route handlers 24 request.user = { 25 'id': token_data.get('sub'), 26 'organization_id': token_data.get('oid'), 27 'roles': token_data.get('roles', []), 28 'permissions': token_data.get('permissions', []) 29 } 30 31 return f(*args, **kwargs) 32 except Exception as e: 33 return jsonify({'error': 'Authentication failed'}), 401 34 35 return decorated_function ``` * Go Validate and decode access token ```go 1 import ( 2 "context" 3 "encoding/json" 4 "net/http" 5 "github.com/scalekit-inc/scalekit-sdk-go" 6 ) 7 8 scalekitClient := scalekit.NewScalekitClient(/* your credentials */) 9 10 func validateAndExtractAuth(next http.HandlerFunc) http.HandlerFunc { 11 return func(w http.ResponseWriter, r *http.Request) { 12 // Extract access token from cookie (decrypt if needed) 13 cookie, err := r.Cookie("accessToken") 14 if err != nil { 15 http.Error(w, `{"error": "No access token provided"}`, http.StatusUnauthorized) 16 return 17 } 18 19 accessToken, err := decrypt(cookie.Value) 20 if err != nil { 21 http.Error(w, `{"error": "Token decryption failed"}`, http.StatusUnauthorized) 22 return 23 } 24 25 // Validate the token using Scalekit SDK 26 isValid, err := scalekitClient.ValidateAccessToken(r.Context(), accessToken) 27 if err != nil || !isValid { 28 http.Error(w, `{"error": "Invalid or expired token"}`, http.StatusUnauthorized) 29 return 30 } 31 32 // Decode token to get roles and permissions using any JWT decode lib 33 tokenData, err := DecodeAccessToken(accessToken) 34 if err != nil { 35 http.Error(w, `{"error": "Token decode failed"}`, http.StatusUnauthorized) 36 return 37 } 38 39 // Add authorization data to request context 40 user := map[string]interface{}{ 41 "id": tokenData["sub"], 42 "organization_id": tokenData["oid"], 43 "roles": tokenData["roles"], 44 "permissions": tokenData["permissions"], 45 } 46 47 ctx := context.WithValue(r.Context(), "user", user) 48 next(w, r.WithContext(ctx)) 49 } 50 } ``` * Java Validate and decode access token ```java 1 import com.scalekit.ScalekitClient; 2 import javax.servlet.http.HttpServletRequest; 3 import javax.servlet.http.HttpServletResponse; 4 import org.springframework.web.servlet.HandlerInterceptor; 5 import java.util.Map; 6 import java.util.HashMap; 7 8 @Component 9 public class AuthorizationInterceptor implements HandlerInterceptor { 10 private final ScalekitClient scalekit; 11 12 @Override 13 public boolean preHandle( 14 HttpServletRequest request, 15 HttpServletResponse response, 16 Object handler 17 ) throws Exception { 18 try { 19 // Extract access token from cookie (decrypt if needed) 20 String accessToken = getCookieValue(request, "accessToken"); 21 String decryptedToken = decrypt(accessToken); 22 23 // Validate the token using Scalekit SDK 24 boolean isValid = scalekit.authentication().validateAccessToken(decryptedToken); 25 26 if (!isValid) { 27 response.setStatus(HttpStatus.UNAUTHORIZED.value()); 28 response.getWriter().write("{\"error\": \"Invalid or expired token\"}"); 29 return false; 30 } 31 32 // Decode token to get roles and permissions using any JWT decode lib 33 Map tokenData = decodeAccessToken(decryptedToken); 34 35 // Make authorization data available to controllers 36 Map user = new HashMap<>(); 37 user.put("id", tokenData.get("sub")); 38 user.put("organizationId", tokenData.get("oid")); 39 user.put("roles", tokenData.get("roles")); 40 user.put("permissions", tokenData.get("permissions")); 41 42 request.setAttribute("user", user); 43 return true; 44 45 } catch (Exception e) { 46 response.setStatus(HttpStatus.UNAUTHORIZED.value()); 47 response.getWriter().write("{\"error\": \"Authentication failed\"}"); 48 return false; 49 } 50 } 51 } ``` This approach makes user roles and permissions available throughout different routes of your application, enabling consistent and secure access control across all endpoints. ## Verify user’s role to allow access to protected resources [Section titled “Verify user’s role to allow access to protected resources”](#verify-users-role-to-allow-access-to-protected-resources) Role-based access control (RBAC) provides a straightforward way to manage permissions by grouping them into logical roles. Instead of checking individual permissions for every action, your application can simply verify if the user has the required role, making access control decisions more efficient and easier to maintain. * Node.js Role-based access control ```javascript 1 // Helper function to check roles 2 function hasRole(user, requiredRole) { 3 return user.roles && user.roles.includes(requiredRole); 4 } 5 6 // Middleware to require specific roles 7 function requireRole(role) { 8 return (req, res, next) => { 9 if (!hasRole(req.user, role)) { 10 return res.status(403).json({ 11 error: `Access denied. Required role: ${role}` 12 }); 13 } 14 next(); 15 }; 16 } 17 18 // Admin-only routes 19 app.get('/api/admin/users', validateAndExtractAuth, requireRole('admin'), (req, res) => { 20 // Only admin users can access this endpoint 21 res.json(getAllUsers(req.user.organizationId)); 22 }); 23 24 // Multiple role check 25 app.post('/api/admin/invite-user', validateAndExtractAuth, (req, res) => { 26 const user = req.user; 27 28 // Allow admins or managers to invite users 29 if (!hasRole(user, 'admin') && !hasRole(user, 'manager')) { 30 return res.status(403).json({ error: 'Only admins and managers can invite users' }); 31 } 32 33 const invitation = createUserInvitation(req.body, user.organizationId); 34 res.json(invitation); 35 }); ``` * Python Role-based access control ```python 1 # Helper function to check roles 2 def has_role(user, required_role): 3 roles = user.get('roles', []) 4 return required_role in roles 5 6 # Decorator to require specific roles 7 def require_role(role): 8 def decorator(f): 9 @wraps(f) 10 def decorated_function(*args, **kwargs): 11 user = getattr(request, 'user', {}) 12 if not has_role(user, role): 13 return jsonify({'error': f'Access denied. Required role: {role}'}), 403 14 return f(*args, **kwargs) 15 return decorated_function 16 return decorator 17 18 # Admin-only routes 19 @app.route('/api/admin/users') 20 @validate_and_extract_auth 21 @require_role('admin') 22 def get_all_users(): 23 # Only admin users can access this endpoint 24 return jsonify(get_all_users_for_org(request.user['organization_id'])) 25 26 # Multiple role check 27 @app.route('/api/admin/invite-user', methods=['POST']) 28 @validate_and_extract_auth 29 def invite_user(): 30 user = request.user 31 32 # Allow admins or managers to invite users 33 if not has_role(user, 'admin') and not has_role(user, 'manager'): 34 return jsonify({'error': 'Only admins and managers can invite users'}), 403 35 36 invitation = create_user_invitation(request.json, user['organization_id']) 37 return jsonify(invitation) ``` * Go Role-based access control ```go 1 // Helper function to check roles 2 func hasRole(user map[string]interface{}, requiredRole string) bool { 3 roles, ok := user["roles"].([]interface{}) 4 if !ok { 5 return false 6 } 7 8 for _, role := range roles { 9 if roleStr, ok := role.(string); ok && roleStr == requiredRole { 10 return true 11 } 12 } 13 return false 14 } 15 16 // Middleware to require specific roles 17 func requireRole(role string) func(http.HandlerFunc) http.HandlerFunc { 18 return func(next http.HandlerFunc) http.HandlerFunc { 19 return func(w http.ResponseWriter, r *http.Request) { 20 user := r.Context().Value("user").(map[string]interface{}) 21 22 if !hasRole(user, role) { 23 http.Error(w, fmt.Sprintf(`{"error": "Access denied. Required role: %s"}`, role), http.StatusForbidden) 24 return 25 } 26 27 next(w, r) 28 } 29 } 30 } 31 32 // Admin-only routes 33 func getAllUsersHandler(w http.ResponseWriter, r *http.Request) { 34 user := r.Context().Value("user").(map[string]interface{}) 35 orgId := user["organization_id"].(string) 36 37 // Only admin users can access this endpoint 38 users := getAllUsersForOrg(orgId) 39 json.NewEncoder(w).Encode(users) 40 } 41 42 // Route setup with role middleware 43 http.HandleFunc("/api/admin/users", validateAndExtractAuth(requireRole("admin")(getAllUsersHandler))) ``` * Java Role-based access control ```java 1 @RestController 2 public class AdminController { 3 4 // Helper method to check roles 5 private boolean hasRole(Map user, String requiredRole) { 6 List roles = (List) user.get("roles"); 7 return roles != null && roles.contains(requiredRole); 8 } 9 10 // Admin-only endpoint 11 @GetMapping("/api/admin/users") 12 public ResponseEntity> getAllUsers(HttpServletRequest request) { 13 Map user = (Map) request.getAttribute("user"); 14 15 // Check for admin role 16 if (!hasRole(user, "admin")) { 17 return ResponseEntity.status(HttpStatus.FORBIDDEN).build(); 18 } 19 20 String orgId = (String) user.get("organizationId"); 21 List users = userService.getAllUsersForOrg(orgId); 22 return ResponseEntity.ok(users); 23 } 24 25 @PostMapping("/api/admin/invite-user") 26 public ResponseEntity inviteUser( 27 @RequestBody InviteUserRequest request, 28 HttpServletRequest httpRequest 29 ) { 30 Map user = (Map) httpRequest.getAttribute("user"); 31 32 // Allow admins or managers to invite users 33 if (!hasRole(user, "admin") && !hasRole(user, "manager")) { 34 return ResponseEntity.status(HttpStatus.FORBIDDEN).build(); 35 } 36 37 String orgId = (String) user.get("organizationId"); 38 Invitation invitation = userService.createInvitation(request, orgId); 39 return ResponseEntity.ok(invitation); 40 } 41 } ``` ## Verify user’s permissions to allow specific actions [Section titled “Verify user’s permissions to allow specific actions”](#verify-users-permissions-to-allow-specific-actions) Permission-based access control provides granular control over specific actions and resources within your application. While roles offer broad access patterns, permissions allow you to define exactly what operations users can perform, enabling precise security controls and the principle of least privilege. * Node.js Permission-based access control ```javascript 1 // Helper function to check permissions 2 function hasPermission(user, requiredPermission) { 3 return user.permissions && user.permissions.includes(requiredPermission); 4 } 5 6 // Middleware to require specific permissions 7 function requirePermission(permission) { 8 return (req, res, next) => { 9 if (!hasPermission(req.user, permission)) { 10 return res.status(403).json({ 11 error: `Access denied. Required permission: ${permission}` 12 }); 13 } 14 next(); 15 }; 16 } 17 18 // Protected routes with permission checks 19 app.get('/api/projects', validateAndExtractAuth, requirePermission('projects:read'), (req, res) => { 20 // User has projects:read permission - allow access 21 res.json(getProjects(req.user.organizationId)); 22 }); 23 24 app.post('/api/projects', validateAndExtractAuth, requirePermission('projects:create'), (req, res) => { 25 // User has projects:create permission - allow creation 26 const newProject = createProject(req.body, req.user.organizationId); 27 res.json(newProject); 28 }); 29 30 // Multiple permission check 31 app.delete('/api/projects/:id', validateAndExtractAuth, (req, res) => { 32 const user = req.user; 33 34 // Check if user has either admin role or specific delete permission 35 if (!hasPermission(user, 'projects:delete') && !user.roles.includes('admin')) { 36 return res.status(403).json({ error: 'Cannot delete projects' }); 37 } 38 39 deleteProject(req.params.id, user.organizationId); 40 res.json({ success: true }); 41 }); ``` * Python Permission-based access control ```python 1 # Helper function to check permissions 2 def has_permission(user, required_permission): 3 permissions = user.get('permissions', []) 4 return required_permission in permissions 5 6 # Decorator to require specific permissions 7 def require_permission(permission): 8 def decorator(f): 9 @wraps(f) 10 def decorated_function(*args, **kwargs): 11 user = getattr(request, 'user', {}) 12 if not has_permission(user, permission): 13 return jsonify({'error': f'Access denied. Required permission: {permission}'}), 403 14 return f(*args, **kwargs) 15 return decorated_function 16 return decorator 17 18 # Protected routes with permission checks 19 @app.route('/api/projects') 20 @validate_and_extract_auth 21 @require_permission('projects:read') 22 def get_projects(): 23 # User has projects:read permission - allow access 24 return jsonify(get_projects_for_org(request.user['organization_id'])) 25 26 @app.route('/api/projects', methods=['POST']) 27 @validate_and_extract_auth 28 @require_permission('projects:create') 29 def create_project(): 30 # User has projects:create permission - allow creation 31 new_project = create_project_for_org(request.json, request.user['organization_id']) 32 return jsonify(new_project) 33 34 # Multiple permission check 35 @app.route('/api/projects/', methods=['DELETE']) 36 @validate_and_extract_auth 37 def delete_project(project_id): 38 user = request.user 39 40 # Check if user has either admin role or specific delete permission 41 if not has_permission(user, 'projects:delete') and 'admin' not in user.get('roles', []): 42 return jsonify({'error': 'Cannot delete projects'}), 403 43 44 delete_project_from_org(project_id, user['organization_id']) 45 return jsonify({'success': True}) ``` * Go Permission-based access control ```go 1 // Helper function to check permissions 2 func hasPermission(user map[string]interface{}, requiredPermission string) bool { 3 permissions, ok := user["permissions"].([]interface{}) 4 if !ok { 5 return false 6 } 7 8 for _, perm := range permissions { 9 if permStr, ok := perm.(string); ok && permStr == requiredPermission { 10 return true 11 } 12 } 13 return false 14 } 15 16 // Middleware to require specific permissions 17 func requirePermission(permission string) func(http.HandlerFunc) http.HandlerFunc { 18 return func(next http.HandlerFunc) http.HandlerFunc { 19 return func(w http.ResponseWriter, r *http.Request) { 20 user := r.Context().Value("user").(map[string]interface{}) 21 22 if !hasPermission(user, permission) { 23 http.Error(w, fmt.Sprintf(`{"error": "Access denied. Required permission: %s"}`, permission), http.StatusForbidden) 24 return 25 } 26 27 next(w, r) 28 } 29 } 30 } 31 32 // Protected routes with permission checks 33 func getProjectsHandler(w http.ResponseWriter, r *http.Request) { 34 user := r.Context().Value("user").(map[string]interface{}) 35 orgId := user["organization_id"].(string) 36 37 // User has projects:read permission - allow access 38 projects := getProjectsForOrg(orgId) 39 json.NewEncoder(w).Encode(projects) 40 } 41 42 func createProjectHandler(w http.ResponseWriter, r *http.Request) { 43 user := r.Context().Value("user").(map[string]interface{}) 44 orgId := user["organization_id"].(string) 45 46 // User has projects:create permission - allow creation 47 var projectData map[string]interface{} 48 json.NewDecoder(r.Body).Decode(&projectData) 49 50 newProject := createProjectForOrg(projectData, orgId) 51 json.NewEncoder(w).Encode(newProject) 52 } 53 54 // Route setup with middleware 55 http.HandleFunc("/api/projects", validateAndExtractAuth(requirePermission("projects:read")(getProjectsHandler))) 56 http.HandleFunc("/api/projects/create", validateAndExtractAuth(requirePermission("projects:create")(createProjectHandler))) ``` * Java Permission-based access control ```java 1 @RestController 2 public class ProjectController { 3 4 // Helper method to check permissions 5 private boolean hasPermission(Map user, String requiredPermission) { 6 List permissions = (List) user.get("permissions"); 7 return permissions != null && permissions.contains(requiredPermission); 8 } 9 10 // Annotation-based permission checking 11 @GetMapping("/api/projects") 12 @PreAuthorize("hasPermission('projects:read')") 13 public ResponseEntity> getProjects(HttpServletRequest request) { 14 Map user = (Map) request.getAttribute("user"); 15 String orgId = (String) user.get("organizationId"); 16 17 // User has projects:read permission - allow access 18 List projects = projectService.getProjectsForOrg(orgId); 19 return ResponseEntity.ok(projects); 20 } 21 22 @PostMapping("/api/projects") 23 public ResponseEntity createProject( 24 @RequestBody CreateProjectRequest request, 25 HttpServletRequest httpRequest 26 ) { 27 Map user = (Map) httpRequest.getAttribute("user"); 28 29 // Check permission manually 30 if (!hasPermission(user, "projects:create")) { 31 return ResponseEntity.status(HttpStatus.FORBIDDEN) 32 .body(null); 33 } 34 35 String orgId = (String) user.get("organizationId"); 36 Project newProject = projectService.createProject(request, orgId); 37 return ResponseEntity.ok(newProject); 38 } 39 40 @DeleteMapping("/api/projects/{projectId}") 41 public ResponseEntity> deleteProject( 42 @PathVariable String projectId, 43 HttpServletRequest request 44 ) { 45 Map user = (Map) request.getAttribute("user"); 46 List roles = (List) user.get("roles"); 47 48 // Check if user has either admin role or specific delete permission 49 if (!hasPermission(user, "projects:delete") && !roles.contains("admin")) { 50 return ResponseEntity.status(HttpStatus.FORBIDDEN) 51 .body(Map.of("error", true)); 52 } 53 54 String orgId = (String) user.get("organizationId"); 55 projectService.deleteProject(projectId, orgId); 56 return ResponseEntity.ok(Map.of("success", true)); 57 } 58 } ``` By implementing both role-based and permission-based access control, your application now has a comprehensive security framework that protects different routes and endpoints. You can combine both approaches to create fine-grained access control that matches your application’s specific requirements. **Admin bypass pattern**: Allow users with `admin` role to bypass certain permission checks while maintaining granular control for other users **Resource ownership pattern**: Combine role/permission checks with resource ownership verification (e.g., users can only edit their own projects unless they have admin role) **Time-based access pattern**: Consider implementing time-based restrictions for sensitive operations, especially for roles with elevated permissions Caution Never implement authorization logic solely on the client side. Always perform server-side validation of roles and permissions, as client-side checks can be bypassed by malicious users. --- # DOCUMENT BOUNDARY --- # Code samples > Full stack auth code samples demonstrating complete authentication implementations with hosted login and session management ### [Full Stack Auth with Next.js](https://github.com/scalekit-inc/scalekit-nextjs-auth-example) [Complete authentication solution for Next.js apps. Includes hosted login pages, session management, and protected routes](https://github.com/scalekit-inc/scalekit-nextjs-auth-example) ### [Full Stack Auth with FastAPI](https://github.com/scalekit-inc/scalekit-fastapi-auth-example) [Authentication template for FastAPI projects. Featuring integrated user sessions, hosted login flow, and ready-to-use route protection specifically tailored for Python web backends.](https://github.com/scalekit-inc/scalekit-fastapi-auth-example) ### [Full Stack Auth with Flask](https://github.com/scalekit-inc/scalekit-flask-auth-example) [Authentication template for Flask applications. Features session management, hosted login flow, and decorator-based route protection](https://github.com/scalekit-inc/scalekit-flask-auth-example) ### [Full Stack Auth with Django](https://github.com/scalekit-inc/scalekit-django-auth-example) [Authentication template for Django projects. Features session management, hosted login flow, and middleware-based route protection](https://github.com/scalekit-inc/scalekit-django-auth-example) ### [Full Stack Auth with Express](https://github.com/scalekit-inc/scalekit-express-auth-example) [Complete authentication solution for Express.js applications. Includes hosted login pages, session management, and middleware-protected routes](https://github.com/scalekit-inc/scalekit-express-auth-example) ### [Full Stack Auth with Spring Boot](https://github.com/scalekit-inc/scalekit-springboot-auth-example) [End-to-end authentication for Java applications. Features Spring Security integration, hosted login, and session handling](https://github.com/scalekit-inc/scalekit-springboot-auth-example) ### [Full Stack Auth with Laravel](https://github.com/scalekit-inc/scalekit-laravel-auth-example) [Complete authentication solution for Laravel applications. Includes hosted login pages, session management, and middleware-protected routes](https://github.com/scalekit-inc/scalekit-laravel-auth-example) ### End to end full stack auth demo Coffee Desk App Complete coffee shop management application with full stack. Features workspaces, organization switcher, and mulitple auth methods [View demo](https://dashboard.coffeedesk.app/) | [View code](https://github.com/scalekit-inc/coffee-desk-demo) --- # DOCUMENT BOUNDARY --- # Implement logout > Terminate user sessions across your application and Scalekit When implementing logout functionality, you need to consider three session layers where user authentication state is maintained: 1. **Application session layer**: Your application stores session tokens (access tokens, refresh tokens, ID tokens) in browser cookies. You control this layer completely. 2. **Scalekit session layer**: Scalekit maintains a session for the user and stores their information. When users return to Scalekit’s authentication page, their information is remembered for a smoother experience. 3. **Identity provider session layer**: When users authenticate with external providers (for example, Okta through enterprise SSO), those providers maintain their own sessions. Users won’t be prompted to sign in again if they’re already signed into the provider. This guide shows you how to clear the application session layer and invalidate the Scalekit session layer in a single logout endpoint.  1. ## Create a logout endpoint [Section titled “Create a logout endpoint”](#create-a-logout-endpoint) Create a `/logout` endpoint in your application that handles the complete logout flow: extracting the ID token, generating the Scalekit logout URL (which points to Scalekit’s `/oidc/logout` endpoint), clearing session cookies, and redirecting to Scalekit. * Node.js Express.js ```javascript 1 app.get('/logout', (req, res) => { 2 // Step 1: Extract the ID token (needed for Scalekit logout) 3 const idTokenHint = req.cookies.idToken; 4 const postLogoutRedirectUri = 'http://localhost:3000/login'; 5 6 // Step 2: Generate the Scalekit logout URL (points to /oidc/logout endpoint) 7 const logoutUrl = scalekit.getLogoutUrl( 8 idTokenHint, // ID token to invalidate 9 postLogoutRedirectUri // URL that scalekit redirects after session invalidation 10 ); 11 12 // Step 3: Clear all session cookies 13 res.clearCookie('accessToken'); 14 res.clearCookie('refreshToken'); 15 res.clearCookie('idToken'); // Clear AFTER using it for logout URL 16 17 // Step 4: Redirect to Scalekit to invalidate the session 18 res.redirect(logoutUrl); 19 }); ``` * Python Flask ```python 1 from flask import request, redirect, make_response 2 from scalekit import LogoutUrlOptions 3 4 @app.route('/logout') 5 def logout(): 6 # Step 1: Extract the ID token (needed for Scalekit logout) 7 id_token = request.cookies.get('idToken') 8 post_logout_redirect_uri = 'http://localhost:3000/login' 9 10 # Step 2: Generate the Scalekit logout URL (points to /oidc/logout endpoint) 11 logout_url = scalekit_client.get_logout_url( 12 LogoutUrlOptions( 13 id_token_hint=id_token, 14 post_logout_redirect_uri=post_logout_redirect_uri 15 ) 16 ) 17 18 # Step 3: Create response and clear all session cookies 19 response = make_response(redirect(logout_url)) 20 response.set_cookie('accessToken', '', max_age=0) 21 response.set_cookie('refreshToken', '', max_age=0) 22 response.set_cookie('idToken', '', max_age=0) # Clear AFTER using it for logout URL 23 24 # Step 4: Return response that redirects to Scalekit 25 return response ``` * Go Gin ```go 1 func logoutHandler(c *gin.Context) { 2 // Step 1: Extract the ID token (needed for Scalekit logout) 3 idToken, _ := c.Cookie("idToken") 4 postLogoutRedirectURI := "http://localhost:3000/login" 5 6 // Step 2: Generate the Scalekit logout URL (points to /oidc/logout endpoint) 7 logoutURL, err := scalekitClient.GetLogoutUrl(LogoutUrlOptions{ 8 IdTokenHint: idToken, 9 PostLogoutRedirectUri: postLogoutRedirectURI, 10 }) 11 if err != nil { 12 c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()}) 13 return 14 } 15 16 // Step 3: Clear all session cookies 17 c.SetCookie("accessToken", "", -1, "/", "", true, true) 18 c.SetCookie("refreshToken", "", -1, "/", "", true, true) 19 c.SetCookie("idToken", "", -1, "/", "", true, true) // Clear AFTER using it for logout URL 20 21 // Step 4: Redirect to Scalekit to invalidate the session 22 c.Redirect(http.StatusFound, logoutURL.String()) 23 } ``` * Java Spring Boot ```java 1 @GetMapping("/logout") 2 public void logout(HttpServletRequest request, HttpServletResponse response) throws IOException { 3 // Step 1: Extract the ID token (needed for Scalekit logout) 4 String idToken = request.getCookies() != null ? 5 Arrays.stream(request.getCookies()) 6 .filter(c -> c.getName().equals("idToken")) 7 .findFirst() 8 .map(Cookie::getValue) 9 .orElse(null) : null; 10 11 String postLogoutRedirectUri = "http://localhost:3000/login"; 12 13 // Step 2: Generate the Scalekit logout URL (points to /oidc/logout endpoint) 14 LogoutUrlOptions options = new LogoutUrlOptions(); 15 options.setIdTokenHint(idToken); 16 options.setPostLogoutRedirectUri(postLogoutRedirectUri); 17 URL logoutUrl = scalekitClient.authentication().getLogoutUrl(options); 18 19 // Step 3: Clear all session cookies with security attributes 20 Cookie accessTokenCookie = new Cookie("accessToken", null); 21 accessTokenCookie.setMaxAge(0); 22 accessTokenCookie.setPath("/"); 23 accessTokenCookie.setHttpOnly(true); 24 accessTokenCookie.setSecure(true); 25 response.addCookie(accessTokenCookie); 26 27 Cookie refreshTokenCookie = new Cookie("refreshToken", null); 28 refreshTokenCookie.setMaxAge(0); 29 refreshTokenCookie.setPath("/"); 30 refreshTokenCookie.setHttpOnly(true); 31 refreshTokenCookie.setSecure(true); 32 response.addCookie(refreshTokenCookie); 33 34 Cookie idTokenCookie = new Cookie("idToken", null); 35 idTokenCookie.setMaxAge(0); 36 idTokenCookie.setPath("/"); 37 idTokenCookie.setHttpOnly(true); 38 idTokenCookie.setSecure(true); 39 response.addCookie(idTokenCookie); // Clear AFTER using it for logout URL 40 41 // Step 4: Redirect to Scalekit to invalidate the session 42 response.sendRedirect(logoutUrl.toString()); 43 } ``` The logout flow clears cookies **AFTER** extracting the ID token and generating the logout URL. This ensures the ID token is available for Scalekit’s logout endpoint. 2. ## Configure post-logout redirect URL [Section titled “Configure post-logout redirect URL”](#configure-post-logout-redirect-url) After users log out, Scalekit redirects them to the URL you specify in the `post_logout_redirect_uri` parameter. This URL must be registered in your Scalekit dashboard under **Dashboard > Authentication > Redirects > Post Logout URL**. Scalekit only redirects to URLs from your allow list. This prevents unauthorized redirects and protects your users. If you need different redirect URLs for different applications, you can register multiple post-logout URLs in your dashboard. ## Common logout scenarios [Section titled “Common logout scenarios”](#common-logout-scenarios) --- # DOCUMENT BOUNDARY --- # Manage user sessions > Store tokens safely with proper cookie security, validate on every request, and refresh with rotation to keep sessions secure User sessions determine how long users stay signed in to your application. After users successfully authenticate, you receive session tokens that manage their access. These tokens control session duration, multi-device access, and cross-product authentication within your company’s ecosystem. This guide shows you how to store these tokens securely with encryption and proper cookie attributes, validate them on every request, and refresh them transparently in middleware to maintain seamless user sessions. 1. ## Store session tokens securely [Section titled “Store session tokens securely”](#store-session-tokens-securely) After successful identity verification using any of the auth methods (Magic Link & OTP, social, enterprise SSO), your application receives session tokens(access and refresh tokens) towards the [end of the login](/authenticate/fsa/complete-login/). * Auth result ```js 1 { 2 user: { 3 email: "john.doe@example.com", 4 emailVerified: true, 5 givenName: "John", 6 name: "John Doe", 7 id: "usr_74599896446906854" 8 }, 9 idToken: "eyJhbGciO..", // Decode for full user details 10 11 accessToken: "eyJhbGciOi..", 12 refreshToken: "rt_8f7d6e5c4b3a2d1e0f9g8h7i6j..", 13 expiresIn: 299 // in seconds 14 } ``` * Decoded ID token ID token decoded ```json 1 { 2 "at_hash": "ec_jU2ZKpFelCKLTRWiRsg", 3 "aud": [ 4 "skc_58327482062864390" 5 ], 6 "azp": "skc_58327482062864390", 7 "c_hash": "6wMreK9kWQQY6O5R0CiiYg", 8 "client_id": "skc_58327482062864390", 9 "email": "john.doe@example.com", 10 "email_verified": true, 11 "exp": 1742975822, 12 "family_name": "Doe", 13 "given_name": "John", 14 "iat": 1742974022, 15 "iss": "https://scalekit-z44iroqaaada-dev.scalekit.cloud", 16 "name": "John Doe", 17 "oid": "org_59615193906282635", 18 "sid": "ses_65274187031249433", 19 "sub": "usr_63261014140912135" 20 } ``` * Decoded access token Decoded access token ```json 1 { 2 "aud": [ 3 "prd_skc_7848964512134X699" 4 ], 5 "client_id": "prd_skc_7848964512134X699", 6 "exp": 1758265247, 7 "iat": 1758264947, 8 "iss": "https://login.devramp.ai", 9 "jti": "tkn_90928731115292X63", 10 "nbf": 1758264947, 11 "oid": "org_89678001X21929734", 12 "permissions": [ 13 "workspace_data:write", 14 "workspace_data:read" 15 ], 16 "roles": [ 17 "admin" 18 ], 19 "sid": "ses_90928729571723X24", 20 "sub": "usr_8967800122X995270", 21 // External identifiers if updated on Scalekit 22 "xoid": "ext_org_123", // Organization ID 23 "xuid": "ext_usr_456", // User ID 24 } ``` Request offline\_access to receive a refresh token A refresh token is only included in the authentication response when you include the `offline_access` scope in your authorization URL. If your authorization URL does not include `offline_access`, `authResult.refreshToken` will be `null` or undefined. Always include `offline_access` alongside `openid`, `profile`, and `email` when building your authorization URL: ```js 1 scopes: ['openid', 'profile', 'email', 'offline_access'] ``` Additionally, Scalekit **rotates refresh tokens** — every time you use a refresh token to get a new access token, you receive a new refresh token. Store the new refresh token immediately and discard the old one. Replaying a used refresh token will result in an error. Store each token based on its security requirements. For SPAs and mobile apps, consider storing access tokens in memory and sending via `Authorization: Bearer` headers to minimize CSRF exposure. For traditional web apps, use the cookie-based approach below: * **Access Token**: Store in a secure, HttpOnly cookie with proper `Path` scoping (e.g., `/api`) to prevent XSS attacks. This token has a short lifespan and provides access to protected resources. * **Refresh Token**: Store in a separate HttpOnly, Secure cookie with `Path=/auth/refresh` scoping. This limits the refresh token to only be sent to your refresh endpoint, reducing exposure. Rotate the token on each use to detect theft. * **ID Token**: Ensure it is stored in local storage or a cookie so that it remains accessible at runtime, which is necessary for logging the user out successfully. - Node.js Express.js ```javascript 1 import cookieParser from 'cookie-parser'; 2 // Enable parsing of cookies from request headers 3 app.use(cookieParser()); 4 5 // Extract authentication data from the successful authentication response 6 const { accessToken, expiresIn, refreshToken, user } = authResult; 7 8 // Encrypt tokens before storing to add an additional security layer 9 const encryptedAccessToken = encrypt(accessToken); 10 const encryptedRefreshToken = encrypt(refreshToken); 11 12 // Store encrypted access token in HttpOnly cookie 13 res.cookie('accessToken', encryptedAccessToken, { 14 maxAge: (expiresIn - 60) * 1000, // Subtract 60s buffer for clock skew (milliseconds) 15 httpOnly: true, // Prevents JavaScript access to mitigate XSS attacks 16 secure: process.env.NODE_ENV === 'production', // HTTPS-only in production 17 sameSite: 'strict' // Prevents CSRF attacks 18 }); 19 20 // Store encrypted refresh token in separate HttpOnly cookie 21 res.cookie('refreshToken', encryptedRefreshToken, { 22 httpOnly: true, // Prevents JavaScript access to mitigate XSS attacks 23 secure: process.env.NODE_ENV === 'production', // HTTPS-only in production 24 sameSite: 'strict' // Prevents CSRF attacks 25 }); ``` - Python Flask ```python 1 from flask import Flask, make_response, request 2 import os 3 app = Flask(__name__) 4 5 # Extract authentication data from the successful authentication response 6 access_token = auth_result.access_token 7 expires_in = auth_result.expires_in 8 refresh_token = auth_result.refresh_token 9 user = auth_result.user 10 11 # Encrypt tokens before storing to add an additional security layer 12 encrypted_access_token = encrypt(access_token) 13 encrypted_refresh_token = encrypt(refresh_token) 14 15 response = make_response() 16 17 # Store encrypted access token in HttpOnly cookie 18 response.set_cookie( 19 'accessToken', 20 encrypted_access_token, 21 max_age=expires_in - 60, # Subtract 60s buffer for clock skew (seconds in Flask) 22 httponly=True, # Prevents JavaScript access to mitigate XSS attacks 23 secure=os.environ.get('FLASK_ENV') == 'production', # HTTPS-only in production 24 samesite='Strict' # Prevents CSRF attacks 25 ) 26 27 # Store encrypted refresh token in separate HttpOnly cookie 28 response.set_cookie( 29 'refreshToken', 30 encrypted_refresh_token, 31 httponly=True, # Prevents JavaScript access to mitigate XSS attacks 32 secure=os.environ.get('FLASK_ENV') == 'production', # HTTPS-only in production 33 samesite='Strict' # Prevents CSRF attacks 34 ) ``` - Go Gin ```go 1 import ( 2 "net/http" 3 "os" 4 "time" 5 "github.com/gin-gonic/gin" 6 ) 7 8 // Extract authentication data from the successful authentication response 9 accessToken := authResult.AccessToken 10 expiresIn := authResult.ExpiresIn 11 refreshToken := authResult.RefreshToken 12 user := authResult.User 13 14 // Encrypt tokens before storing to add an additional security layer 15 encryptedAccessToken := encrypt(accessToken) 16 encryptedRefreshToken := encrypt(refreshToken) 17 18 // Set SameSite mode for CSRF protection 19 c.SetSameSite(http.SameSiteStrictMode) // Prevents CSRF attacks 20 21 // Store encrypted access token in HttpOnly cookie 22 c.SetCookie( 23 "accessToken", 24 encryptedAccessToken, 25 expiresIn-60, // Subtract 60s buffer for clock skew (seconds in Gin) 26 "/", // Available on all routes 27 "", 28 os.Getenv("GIN_MODE") == "release", // HTTPS-only in production 29 true, // Prevents JavaScript access to mitigate XSS attacks 30 ) 31 32 // Store encrypted refresh token in separate HttpOnly cookie 33 c.SetCookie( 34 "refreshToken", 35 encryptedRefreshToken, 36 0, // No expiry for refresh token cookie (session lifetime controlled server-side) 37 "/", // Available on all routes 38 "", 39 os.Getenv("GIN_MODE") == "release", // HTTPS-only in production 40 true, // Prevents JavaScript access to mitigate XSS attacks 41 ) ``` - Java Spring ```java 1 import javax.servlet.http.Cookie; 2 import javax.servlet.http.HttpServletResponse; 3 import org.springframework.core.env.Environment; 4 @Autowired 5 private Environment env; 6 7 // Extract authentication data from the successful authentication response 8 String accessToken = authResult.getAccessToken(); 9 int expiresIn = authResult.getExpiresIn(); 10 String refreshToken = authResult.getRefreshToken(); 11 User user = authResult.getUser(); 12 13 // Encrypt tokens before storing to add an additional security layer 14 String encryptedAccessToken = encrypt(accessToken); 15 String encryptedRefreshToken = encrypt(refreshToken); 16 17 // Store encrypted access token in HttpOnly cookie 18 Cookie accessTokenCookie = new Cookie("accessToken", encryptedAccessToken); 19 accessTokenCookie.setMaxAge(expiresIn - 60); // Subtract 60s buffer for clock skew (seconds in Spring) 20 accessTokenCookie.setHttpOnly(true); // Prevents JavaScript access to mitigate XSS attacks 21 accessTokenCookie.setSecure("production".equals(env.getActiveProfiles()[0])); // HTTPS-only in production 22 accessTokenCookie.setPath("/"); // Available on all routes 23 response.addCookie(accessTokenCookie); 24 response.setHeader("Set-Cookie", 25 response.getHeader("Set-Cookie") + "; SameSite=Strict"); // Prevents CSRF attacks 26 27 // Store encrypted refresh token in separate HttpOnly cookie 28 Cookie refreshTokenCookie = new Cookie("refreshToken", encryptedRefreshToken); 29 refreshTokenCookie.setHttpOnly(true); // Prevents JavaScript access to mitigate XSS attacks 30 refreshTokenCookie.setSecure("production".equals(env.getActiveProfiles()[0])); // HTTPS-only in production 31 refreshTokenCookie.setPath("/"); // Available on all routes 32 response.addCookie(refreshTokenCookie); ``` 2. ## Check the access token before handling requests [Section titled “Check the access token before handling requests”](#check-the-access-token-before-handling-requests) Validate every request for a valid access token in your application. Create middleware to protect your application routes. This middleware validates the access token on every request to secured endpoints. For APIs, consider reading from `Authorization: Bearer` headers instead of cookies to minimize CSRF risk. Here’s an example middleware method validating the access token and refreshing it if expired for every request. * Node.js middleware/auth.js ```javascript 1 async function verifyToken(req, res, next) { 2 // Extract encrypted tokens from request cookies 3 const { accessToken, refreshToken } = req.cookies; 4 5 if (!accessToken) { 6 return res.status(401).json({ error: 'Authentication required' }); 7 } 8 9 try { 10 // Decrypt the access token before validation 11 const decryptedAccessToken = decrypt(accessToken); 12 13 // Verify token validity using Scalekit's validation method 14 const isValid = await scalekit.validateAccessToken(decryptedAccessToken); 15 16 if (!isValid && refreshToken) { 17 // Token expired - refresh it transparently 18 const decryptedRefreshToken = decrypt(refreshToken); 19 const authResult = await scalekit.refreshAccessToken(decryptedRefreshToken); 20 21 // Encrypt and store new tokens 22 res.cookie('accessToken', encrypt(authResult.accessToken), { 23 maxAge: (authResult.expiresIn - 60) * 1000, 24 httpOnly: true, 25 secure: process.env.NODE_ENV === 'production', 26 sameSite: 'strict' 27 }); 28 29 res.cookie('refreshToken', encrypt(authResult.refreshToken), { 30 httpOnly: true, 31 secure: process.env.NODE_ENV === 'production', 32 sameSite: 'strict' 33 }); 34 35 return next(); 36 } 37 38 if (!isValid) { 39 return res.status(401).json({ error: 'Session expired. Please sign in again.' }); 40 } 41 42 // Token is valid, proceed to the next middleware or route handler 43 next(); 44 } catch (error) { 45 return res.status(401).json({ error: 'Authentication failed' }); 46 } 47 } ``` * Python middleware/auth.py ```python 1 from flask import request, jsonify 2 from functools import wraps 3 def verify_token(f): 4 @wraps(f) 5 def decorated_function(*args, **kwargs): 6 # Extract encrypted tokens from request cookies 7 access_token = request.cookies.get('accessToken') 8 refresh_token = request.cookies.get('refreshToken') 9 10 if not access_token: 11 return jsonify({'error': 'Authentication required'}), 401 12 13 try: 14 # Decrypt the access token before validation 15 decrypted_access_token = decrypt(access_token) 16 17 # Verify token validity using Scalekit's validation method 18 is_valid = scalekit_client.validate_access_token(decrypted_access_token) 19 20 if not is_valid and refresh_token: 21 # Token expired - refresh it transparently 22 decrypted_refresh_token = decrypt(refresh_token) 23 auth_result = scalekit_client.refresh_access_token(decrypted_refresh_token) 24 25 # Encrypt and store new tokens 26 response = make_response(f(*args, **kwargs)) 27 response.set_cookie( 28 'accessToken', 29 encrypt(auth_result.access_token), 30 max_age=auth_result.expires_in - 60, 31 httponly=True, 32 secure=os.environ.get('FLASK_ENV') == 'production', 33 samesite='Strict' 34 ) 35 response.set_cookie( 36 'refreshToken', 37 encrypt(auth_result.refresh_token), 38 httponly=True, 39 secure=os.environ.get('FLASK_ENV') == 'production', 40 samesite='Strict' 41 ) 42 return response 43 44 if not is_valid: 45 return jsonify({'error': 'Session expired. Please sign in again.'}), 401 46 47 # Token is valid, proceed to the protected view function 48 return f(*args, **kwargs) 49 50 except Exception: 51 return jsonify({'error': 'Authentication failed'}), 401 52 53 return decorated_function ``` * Go middleware/auth.go ```go 1 import ( 2 "net/http" 3 "os" 4 "github.com/gin-gonic/gin" 5 ) 6 func VerifyToken() gin.HandlerFunc { 7 return func(c *gin.Context) { 8 // Extract encrypted tokens from request cookies 9 accessToken, err := c.Cookie("accessToken") 10 if err != nil || accessToken == "" { 11 c.JSON(http.StatusUnauthorized, gin.H{"error": "Authentication required"}) 12 c.Abort() 13 return 14 } 15 16 // Decrypt the access token before validation 17 decryptedAccessToken := decrypt(accessToken) 18 19 // Verify token validity using Scalekit's validation method 20 isValid, err := scalekitClient.ValidateAccessToken(c.Request.Context(), decryptedAccessToken) 21 22 if (err != nil || !isValid) { 23 // Token expired - attempt transparent refresh 24 refreshToken, err := c.Cookie("refreshToken") 25 if err == nil && refreshToken != "" { 26 decryptedRefreshToken := decrypt(refreshToken) 27 authResult, err := scalekitClient.RefreshAccessToken(c.Request.Context(), decryptedRefreshToken) 28 29 if err == nil { 30 // Encrypt and store new tokens 31 c.SetSameSite(http.SameSiteStrictMode) 32 c.SetCookie( 33 "accessToken", 34 encrypt(authResult.AccessToken), 35 authResult.ExpiresIn-60, 36 "/", 37 "", 38 os.Getenv("GIN_MODE") == "release", 39 true, 40 ) 41 c.SetCookie( 42 "refreshToken", 43 encrypt(authResult.RefreshToken), 44 0, 45 "/", 46 "", 47 os.Getenv("GIN_MODE") == "release", 48 true, 49 ) 50 c.Next() 51 return 52 } 53 } 54 55 c.JSON(http.StatusUnauthorized, gin.H{"error": "Session expired. Please sign in again."}) 56 c.Abort() 57 return 58 } 59 60 // Token is valid, proceed to the next handler in the chain 61 c.Next() 62 } 63 } ``` * Java middleware/AuthInterceptor.java ```java 1 import javax.servlet.http.HttpServletRequest; 2 import javax.servlet.http.HttpServletResponse; 3 import javax.servlet.http.Cookie; 4 import org.springframework.web.servlet.HandlerInterceptor; 5 import org.springframework.core.env.Environment; 6 7 /** 8 * Intercepts HTTP requests to verify authentication tokens. 9 * Transparently refreshes expired tokens to maintain user sessions. 10 */ 11 @Component 12 public class AuthInterceptor implements HandlerInterceptor { 13 @Autowired 14 private Environment env; 15 16 @Override 17 public boolean preHandle( 18 HttpServletRequest request, 19 HttpServletResponse response, 20 Object handler 21 ) throws Exception { 22 // Extract encrypted tokens from cookies 23 String accessToken = getCookieValue(request, "accessToken"); 24 String refreshToken = getCookieValue(request, "refreshToken"); 25 26 if (accessToken == null) { 27 response.setStatus(HttpServletResponse.SC_UNAUTHORIZED); 28 response.getWriter().write("{\"error\": \"Authentication required\"}"); 29 return false; 30 } 31 32 try { 33 // Decrypt the access token before validation 34 String decryptedAccessToken = decrypt(accessToken); 35 36 // Verify token validity using Scalekit's validation method 37 boolean isValid = scalekitClient.validateAccessToken(decryptedAccessToken); 38 39 if (!isValid && refreshToken != null) { 40 // Token expired - refresh it transparently 41 String decryptedRefreshToken = decrypt(refreshToken); 42 AuthResult authResult = scalekitClient.authentication().refreshToken(decryptedRefreshToken); 43 44 // Encrypt and store new tokens 45 Cookie accessTokenCookie = new Cookie("accessToken", encrypt(authResult.getAccessToken())); 46 accessTokenCookie.setMaxAge(authResult.getExpiresIn() - 60); 47 accessTokenCookie.setHttpOnly(true); 48 accessTokenCookie.setSecure("production".equals(env.getActiveProfiles()[0])); 49 accessTokenCookie.setPath("/"); 50 response.addCookie(accessTokenCookie); 51 52 Cookie refreshTokenCookie = new Cookie("refreshToken", encrypt(authResult.getRefreshToken())); 53 refreshTokenCookie.setHttpOnly(true); 54 refreshTokenCookie.setSecure("production".equals(env.getActiveProfiles()[0])); 55 refreshTokenCookie.setPath("/"); 56 response.addCookie(refreshTokenCookie); 57 response.setHeader("Set-Cookie", response.getHeader("Set-Cookie") + "; SameSite=Strict"); 58 59 return true; 60 } 61 62 if (!isValid) { 63 response.setStatus(HttpServletResponse.SC_UNAUTHORIZED); 64 response.getWriter().write("{\"error\": \"Session expired. Please sign in again.\"}"); 65 return false; 66 } 67 68 // Token is valid, allow request to proceed 69 return true; 70 } catch (Exception e) { 71 response.setStatus(HttpServletResponse.SC_UNAUTHORIZED); 72 response.getWriter().write("{\"error\": \"Authentication failed\"}"); 73 return false; 74 } 75 } 76 77 private String getCookieValue(HttpServletRequest request, String cookieName) { 78 Cookie[] cookies = request.getCookies(); 79 if (cookies != null) { 80 for (Cookie cookie : cookies) { 81 if (cookieName.equals(cookie.getName())) { 82 return cookie.getValue(); 83 } 84 } 85 } 86 return null; 87 } 88 } ``` 3. ## Configure session security and duration [Section titled “Configure session security and duration”](#configure-session-security-and-duration) Manage user session behavior directly from your Scalekit dashboard without modifying application code. Configure session durations and authentication frequency to balance security and user experience for your application.  In your Scalekit dashboard, the **Session settings** page lets you set these options: * **Absolute session timeout**: This is the maximum time a user can stay signed in, no matter what. After this time, they must log in again. For example, if you set it to 30 minutes, users will be logged out after 30 minutes, even if they are still using your app. * **Idle session timeout**: This is the time your app waits before logging out a user who is not active. If you turn this on, the session will end if the user does nothing for the set time. For example, if you set it to 10 minutes, and the user does not click or type for 10 minutes, they will be logged out. * **Access token lifetime**: This is how long an access token is valid. When it expires, your app needs to get a new token (using the refresh token) so the user can keep using the app without logging in again. For example, if you set it to 5 minutes, your app will need to refresh the token every 5 minutes. Shorter timeouts provide better security, while longer timeouts reduce authentication interruptions. 4. ## Manage sessions remotely API [Section titled “Manage sessions remotely ”](#manage-sessions-remotely-) Beyond client-side session management, Scalekit provides powerful APIs to manage user sessions remotely from your backend application. This enables you to build features like active session management in user account settings, security incident response, or administrative session control. These APIs are particularly useful for: * Displaying all active sessions in user account settings * Allowing users to revoke specific sessions from unfamiliar devices * Security incident response and suspicious session termination - Node.js Session Management SDK ```javascript 1 // Get details for a specific session 2 const sessionDetails = await scalekit.session.getSession('ses_1234567890123456'); 3 4 // List all sessions for a user with optional filtering 5 const userSessions = await scalekit.session.getUserSessions('usr_1234567890123456', { 6 pageSize: 10, 7 filter: { 8 status: ['ACTIVE'], // Filter for active sessions only 9 startTime: new Date('2025-01-01T00:00:00Z'), 10 endTime: new Date('2025-12-31T23:59:59Z') 11 } 12 }); 13 14 // Revoke a specific session (useful for "Sign out this device" functionality) 15 const revokedSession = await scalekit.session.revokeSession('ses_1234567890123456'); 16 17 // Revoke all sessions for a user (useful for "Sign out all devices" functionality) 18 const revokedSessions = await scalekit.session.revokeAllUserSessions('usr_1234567890123456'); 19 console.log(`Revoked sessions for user`); ``` - Python Session Management SDK ```python 1 # Get details for a specific session 2 session_details = scalekit_client.session.get_session(session_id="ses_1234567890123456") 3 4 # List all sessions for a user with optional filtering 5 from google.protobuf.timestamp_pb2 import Timestamp 6 from datetime import datetime 7 8 start_time = Timestamp() 9 start_time.FromDatetime(datetime(2025, 1, 1)) 10 end_time = Timestamp() 11 end_time.FromDatetime(datetime(2025, 12, 31)) 12 13 filter_obj = scalekit_client.session.create_session_filter( 14 status=["ACTIVE"], start_time=start_time, end_time=end_time 15 ) 16 user_sessions = scalekit_client.session.get_user_sessions( 17 user_id="usr_1234567890123456", page_size=10, filter=filter_obj 18 ) 19 20 # Revoke a specific session (useful for "Sign out this device" functionality) 21 revoked_session = scalekit_client.session.revoke_session(session_id="ses_1234567890123456") 22 23 # Revoke all sessions for a user (useful for "Sign out all devices" functionality) 24 revoked_sessions = scalekit_client.session.revoke_all_user_sessions(user_id="usr_1234567890123456") 25 print(f"Revoked sessions for user") ``` - Go Session Management SDK ```go 1 // Get details for a specific session 2 sessionDetails, err := scalekitClient.Session().GetSession(ctx, "ses_1234567890123456") 3 if err != nil { 4 log.Fatal(err) 5 } 6 7 // List all sessions for a user with optional filtering 8 // import "time", sessionsv1 "...", "google.golang.org/protobuf/types/known/timestamppb" 9 startTime, _ := time.Parse(time.RFC3339, "2025-01-01T00:00:00Z") 10 endTime, _ := time.Parse(time.RFC3339, "2025-12-31T23:59:59Z") 11 filter := &sessionsv1.UserSessionFilter{ 12 Status: []string{"ACTIVE"}, // Filter for active sessions only 13 StartTime: timestamppb.New(startTime), 14 EndTime: timestamppb.New(endTime), 15 } 16 userSessions, err := scalekitClient.Session().GetUserSessions(ctx, "usr_1234567890123456", 10, "", filter) 17 if err != nil { 18 log.Fatal(err) 19 } 20 21 // Revoke a specific session (useful for "Sign out this device" functionality) 22 revokedSession, err := scalekitClient.Session().RevokeSession(ctx, "ses_1234567890123456") 23 if err != nil { 24 log.Fatal(err) 25 } 26 27 // Revoke all sessions for a user (useful for "Sign out all devices" functionality) 28 revokedSessions, err := scalekitClient.Session().RevokeAllUserSessions(ctx, "usr_1234567890123456") 29 if err != nil { 30 log.Fatal(err) 31 } 32 fmt.Printf("Revoked sessions for user") ``` - Java Session Management SDK ```java 1 // Get details for a specific session 2 SessionDetails sessionDetails = scalekitClient.sessions().getSession("ses_1234567890123456"); 3 4 // List all sessions for a user with optional filtering 5 // import UserSessionFilter, Timestamp, Instant 6 UserSessionFilter filter = UserSessionFilter.newBuilder() 7 .addStatus("ACTIVE") 8 .setStartTime(Timestamp.newBuilder().setSeconds(Instant.parse("2025-01-01T00:00:00Z").getEpochSecond()).build()) 9 .setEndTime(Timestamp.newBuilder().setSeconds(Instant.parse("2025-12-31T23:59:59Z").getEpochSecond()).build()) 10 .build(); 11 UserSessionDetails userSessions = scalekitClient.sessions().getUserSessions("usr_1234567890123456", 10, "", filter); 12 13 // Revoke a specific session (useful for "Sign out this device" functionality) 14 RevokeSessionResponse revokedSession = scalekitClient.sessions().revokeSession("ses_1234567890123456"); 15 16 // Revoke all sessions for a user (useful for "Sign out all devices" functionality) 17 RevokeAllUserSessionsResponse revokedSessions = scalekitClient.sessions().revokeAllUserSessions("usr_1234567890123456"); 18 System.out.println("Revoked sessions for user"); ``` Your application continuously validates the access token for each incoming request. When the token is valid, the user’s session remains active. If the access token expires, your middleware transparently refreshes it using the stored refresh token—users never notice this happening. If the refresh token itself expires or becomes invalid, users are prompted to sign in again. --- # DOCUMENT BOUNDARY --- # Manage applications > Register and manage applications in your shared authentication system Register and manage applications in Scalekit. Each application gets its own OAuth client and configuration while sharing the same underlying user session across your web, mobile, and desktop apps. 1. ## Navigate to Applications [Section titled “Navigate to Applications”](#navigate-to-applications) 1. Sign in to **** 2. From the left sidebar, go to **Developers > Applications** You will see a list of applications already created for the selected environment. 2. ## Create a new application [Section titled “Create a new application”](#create-a-new-application) Click **Create Application** to add a new app. You’ll be asked to provide: * **Application name** — A human-readable name for identifying the app * **Application type** — Determines how authentication and credentials work Available application types: * **Web Application** — Server-side applications that can securely store secrets * **Single Page Application (SPA)** — Browser-based applications; public clients with PKCE enforced * **Native Application** — Desktop or mobile apps; public clients with PKCE enforced  Once created, Scalekit generates a **Client ID**. Only Web Applications can generate **Client Secrets**. 3. ## Application configuration [Section titled “Application configuration”](#application-configuration) ### Application details [Section titled “Application details”](#application-details) Open an application to view and edit its configuration. * **Allow Scalekit Management API access** — Enables this application’s credentials to call Scalekit Management APIs. Applicable only to **Web Applications**. * **Enforce PKCE** — Requires PKCE for authorization requests. Always enabled and not editable for **SPA** and **Native** applications. * **Access token expiry time** — Overrides the environment default access token lifetime for this application. Access token expiry must be shorter than idle session timeout If tokens outlive the session, users may encounter inconsistent logout behavior across apps. When the session expires but the access token is still valid, subsequent token refresh attempts will fail because the underlying session no longer exists.  ### Client credentials [Section titled “Client credentials”](#client-credentials) Each application has a unique **Client ID**. When you generate a new client secret, Scalekit shows it **only once**. Copy and store it securely. Treat client secrets like passwords Anyone with access to your client secret can authenticate as your application and obtain tokens for any user. Never commit secrets to version control, expose them in client-side code, or share them in plain text. Use environment variables or a secrets manager. * **Web Applications** * Can generate a **Client Secret** * A maximum of **two active secrets** is allowed at a time * Generating a new secret always creates a **new value**, enabling safe rotation  * **SPA and Native Applications** * Do not have client secrets * Authenticate using Authorization Code with PKCE only  4. ## Configure redirect URLs [Section titled “Configure redirect URLs”](#configure-redirect-urls) Open the **Redirects** tab for an application to manage redirect endpoints. These URLs act as an allowlist and control where Scalekit can redirect users during authentication flows. ### Redirect URL types [Section titled “Redirect URL types”](#redirect-url-types) * **Post login URLs** — Allowed values for `redirect_uri` used with `/oauth/authorize` * **Initiate login URL** — Where Scalekit redirects users when authentication starts outside your app * **Post logout URLs** — Where users are redirected after a successful logout * **Back-channel logout URL** — A secure endpoint that Scalekit calls to notify your application that a user session has been revoked  For definitions, validation rules, custom URI schemes, and environment-specific behavior, see [Redirect URL configuration](/guides/dashboard/redirects/). 5. ## Delete an application [Section titled “Delete an application”](#delete-an-application) Delete applications from the bottom of the configuration page.  Deleting an application is permanent This action is **permanent and irreversible**. Existing refresh tokens associated with the application will no longer be valid, and users will need to re-authenticate. Ensure you have communicated this change to affected users before deleting. --- # DOCUMENT BOUNDARY --- # Mobile & desktop applications > Implement Multi-App Authentication for mobile and desktop apps using Authorization Code with PKCE Implement login, token management, and logout in your mobile or desktop application using Authorization Code with PKCE. Native apps are public OAuth clients that cannot securely store a `client_secret` in the application binary, so they use PKCE to protect the authorization flow. This guide covers initiating login through the system browser, handling deep link callbacks, managing tokens in secure storage, and implementing logout. ## Prerequisites [Section titled “Prerequisites”](#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 native application registered in Scalekit with a `client_id` ([Create one](/authenticate/fsa/multiapp/manage-apps)) * A callback URI configured: * **Mobile**: Custom URI scheme (e.g., `myapp://callback`) or universal/app links * **Desktop**: Custom URI scheme or loopback address (e.g., `http://127.0.0.1:PORT/callback`) ## High-level flow [Section titled “High-level flow”](#high-level-flow) ## Step-by-step implementation [Section titled “Step-by-step implementation”](#step-by-step-implementation) 1. ## Initiate login or signup [Section titled “Initiate login or signup”](#initiate-login-or-signup) Initiate login by opening the system browser with the authorization URL. Always use the system browser rather than an embedded WebView — this lets users leverage existing sessions and provides a familiar, secure authentication experience. ```sh 1 /oauth/authorize? 2 response_type=code& 3 client_id=& 4 redirect_uri=& 5 scope=openid+profile+email+offline_access& 6 state=& 7 code_challenge=& 8 code_challenge_method=S256 ``` Generate and store these values before opening the browser: * `state` — Validate this on callback to prevent CSRF attacks * `code_verifier` — A cryptographically random string you keep in the app * `code_challenge` — Derived from the verifier using S256 hashing; send this in the authorization URL For detailed parameter definitions, see [Initiate signup/login](/authenticate/fsa/implement-login). 2. ## Handle the callback and complete login [Section titled “Handle the callback and complete login”](#handle-the-callback-and-complete-login) After authentication, Scalekit redirects the user back to your application using the registered callback mechanism. Common callback patterns: * **Mobile apps** — Custom URI schemes (e.g., `myapp://callback`) or universal links (iOS) / app links (Android) * **Desktop apps** — Custom URI schemes or a temporary HTTP server on localhost Your callback handler must: * Validate the returned `state` matches what you stored — this confirms the response is for your original request * Handle any error parameters before processing * Exchange the authorization code for tokens by including the `code_verifier` ```sh 1 POST /oauth/token 2 Content-Type: application/x-www-form-urlencoded 3 4 grant_type=authorization_code& 5 client_id=& 6 code=& 7 redirect_uri=& 8 code_verifier= ``` ```json 1 { 2 "access_token": "...", 3 "refresh_token": "...", 4 "id_token": "...", 5 "expires_in": 299 6 } ``` 3. ## Manage sessions and token refresh [Section titled “Manage sessions and token refresh”](#manage-sessions-and-token-refresh) Store tokens in platform-specific secure storage and validate them on each request. When access tokens expire, use the refresh token to obtain new ones without requiring the user to re-authenticate. **Token roles** * **Access token** — Short-lived token (default 5 minutes) for authenticated API requests * **Refresh token** — Long-lived token to obtain new access tokens * **ID token** — JWT containing user identity claims; required for logout Store tokens using secure, OS-backed storage appropriate for each platform. See [Token storage security](#token-storage-security) for platform-specific recommendations. When an access token expires, request new tokens: ```sh 1 POST /oauth/token 2 Content-Type: application/x-www-form-urlencoded 3 4 grant_type=refresh_token& 5 client_id=& 6 refresh_token= ``` Validate access tokens by verifying: * Token signature using Scalekit’s public keys (JWKS endpoint) * `iss` matches your Scalekit environment URL * `aud` includes your `client_id` * `exp` and `iat` are valid timestamps Public keys for signature verification: ```sh 1 /keys ``` 4. ## Implement logout [Section titled “Implement logout”](#implement-logout) Clear your local session and redirect the system browser to Scalekit’s logout endpoint to invalidate the shared session. Your logout action must: * Extract the ID token before clearing local storage * Clear tokens from secure storage * Open the system browser to Scalekit’s logout endpoint ```sh 1 /oidc/logout? 2 id_token_hint=& 3 post_logout_redirect_uri= ``` ## Handle errors [Section titled “Handle errors”](#handle-errors) When authentication fails, Scalekit redirects to your callback URI with error parameters instead of an authorization code: ```plaintext 1 myapp://callback?error=access_denied&error_description=User+denied+access&state= ``` Check for errors before processing the authorization code: * Check if the `error` parameter exists in the callback URI * Log the `error` and `error_description` for debugging * Display a user-friendly message in your app * Provide an option to retry login Common error codes: | Error | Description | | ----------------- | ------------------------------------------------------------ | | `access_denied` | User denied the authorization request | | `invalid_request` | Missing or invalid parameters (e.g., invalid PKCE challenge) | | `server_error` | Scalekit encountered an unexpected error | ## Token storage security [Section titled “Token storage security”](#token-storage-security) Native apps have access to platform-specific secure storage mechanisms that encrypt tokens at rest and protect them from other applications. Unlike browser storage, these mechanisms provide strong protection against token theft from device compromise or malware. Use platform-specific secure storage for each platform: | Platform | Recommended Storage | | -------- | -------------------------------------- | | iOS | Keychain Services | | Android | EncryptedSharedPreferences or Keystore | | macOS | Keychain | | Windows | Windows Credential Manager or DPAPI | | Linux | Secret Service API (libsecret) | **Recommendations:** * Never store tokens in plain text files, shared preferences, or unencrypted databases — these can be read by any application with storage access * Use biometric or device PIN protection for sensitive token access when available — this adds a second factor for token access * Clear tokens from secure storage on logout — this ensures a clean state for the next authentication Never embed secrets in your application binary Credentials embedded in application code or configuration files can be extracted through reverse engineering. Always use PKCE for native apps instead of relying on a `client_secret`. If you need to make authenticated API calls from your backend, use a separate web application with proper secret management. ## What’s next [Section titled “What’s next”](#whats-next) * [Set up a custom domain](/guides/custom-domain) for your authentication pages * [Add enterprise SSO](/authenticate/auth-methods/enterprise-sso/) to support SAML and OIDC with your customers’ identity providers --- # DOCUMENT BOUNDARY --- # Single page application > Implement Multi-App Authentication for single page apps using Authorization Code with PKCE Implement login, token management, and logout in your single page application (SPA) using Authorization Code with PKCE. SPAs run entirely in the browser and cannot securely store a `client_secret`, so they use PKCE (Proof Key for Code Exchange) to protect the authorization flow. This guide covers initiating login from your SPA, exchanging authorization codes for tokens, managing sessions, and implementing logout. ## Prerequisites [Section titled “Prerequisites”](#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 SPA registered in Scalekit with a `client_id` ([Create one](/authenticate/fsa/multiapp/manage-apps)) * At least one redirect URL configured in **Dashboard > Developers > Applications > \[Your App] > Redirects** ## High-level flow [Section titled “High-level flow”](#high-level-flow) ## Step-by-step implementation [Section titled “Step-by-step implementation”](#step-by-step-implementation) 1. ## Initiate login or signup [Section titled “Initiate login or signup”](#initiate-login-or-signup) Initiate login by redirecting the user to Scalekit’s hosted login page. Include the PKCE code challenge in the authorization request to protect against authorization code interception attacks. ```sh 1 /oauth/authorize? 2 response_type=code& 3 client_id=& 4 redirect_uri=& 5 scope=openid+profile+email+offline_access& 6 state=& 7 code_challenge=& 8 code_challenge_method=S256 ``` Generate and store these values before redirecting: * `state` — Validate this on callback to prevent CSRF attacks * `code_verifier` — A cryptographically random string you keep locally * `code_challenge` — Derived from the verifier using S256 hashing; send this in the authorization URL For detailed parameter definitions, see [Initiate signup/login](/authenticate/fsa/implement-login). 2. ## Handle the callback and complete login [Section titled “Handle the callback and complete login”](#handle-the-callback-and-complete-login) After authentication, Scalekit redirects the user back to your callback URL with an authorization `code` and the `state` you sent. Your callback handler must: * Validate the returned `state` matches what you stored — this confirms the response is for your original request * Handle any error parameters before processing * Exchange the authorization code for tokens by including the `code_verifier` ```sh 1 POST /oauth/token 2 Content-Type: application/x-www-form-urlencoded 3 4 grant_type=authorization_code& 5 client_id=& 6 code=& 7 redirect_uri=& 8 code_verifier= ``` ```json 1 { 2 "access_token": "...", 3 "refresh_token": "...", 4 "id_token": "...", 5 "expires_in": 299 6 } ``` 3. ## Manage sessions and token refresh [Section titled “Manage sessions and token refresh”](#manage-sessions-and-token-refresh) Store tokens and validate them on each request. When access tokens expire, use the refresh token to obtain new ones without requiring the user to authenticate again. **Token roles** * **Access token** — Short-lived token (default 5 minutes) for authenticated API requests * **Refresh token** — Long-lived token to obtain new access tokens * **ID token** — JWT containing user identity claims; required for logout Store tokens client-side based on your security requirements. See [Token storage security](#token-storage-security) for guidance on choosing the right storage mechanism. When an access token expires, request new tokens: ```sh 1 POST /oauth/token 2 Content-Type: application/x-www-form-urlencoded 3 4 grant_type=refresh_token& 5 client_id=& 6 refresh_token= ``` Validate access tokens by verifying: * Token signature using Scalekit’s public keys (JWKS endpoint) * `iss` matches your Scalekit environment URL * `aud` includes your `client_id` * `exp` and `iat` are valid timestamps Public keys for signature verification: ```sh 1 /keys ``` 4. ## Implement logout [Section titled “Implement logout”](#implement-logout) Clear your local session and redirect to Scalekit’s logout endpoint to invalidate the shared session. Your logout action must: * Extract the ID token before clearing local storage * Clear locally stored tokens from memory or storage * Redirect the browser to Scalekit’s logout endpoint ```sh 1 /oidc/logout? 2 id_token_hint=& 3 post_logout_redirect_uri= ``` ## Handle errors [Section titled “Handle errors”](#handle-errors) When authentication fails, Scalekit redirects to your callback URL with error parameters instead of an authorization code: ```sh /callback?error=access_denied&error_description=User+denied+access&state= ``` Check for errors before processing the authorization code: * Check if the `error` parameter exists in the URL * 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 (e.g., invalid PKCE challenge) | | `server_error` | Scalekit encountered an unexpected error | ## Token storage security [Section titled “Token storage security”](#token-storage-security) SPAs run entirely in the browser where tokens are vulnerable to cross-site scripting (XSS) attacks. An attacker who successfully injects malicious JavaScript can read tokens from any accessible storage and use them to impersonate the user. Choose a storage strategy based on your security requirements: | Storage | Security | Trade-off | | ---------------------------- | --------------------------------------- | ---------------------------------------------------- | | Memory (JavaScript variable) | Most secure — not accessible to XSS | Tokens lost on page refresh; requires silent refresh | | Session storage | Moderate — cleared when tab closes | Accessible to XSS; persists during session | | Local storage | Least secure — persists across sessions | Accessible to XSS; long exposure window | **Recommendations:** * For high-security applications, store tokens in memory and use silent refresh (iframe-based token renewal) to maintain sessions across page loads * Always sanitize user inputs and use Content Security Policy (CSP) headers to mitigate XSS attacks * Never log tokens or include them in error messages Never store tokens in local storage for sensitive applications Local storage is accessible to any JavaScript running on your page. If an attacker exploits an XSS vulnerability, they can read all tokens from local storage and fully compromise user accounts. For applications handling sensitive data, prefer memory storage with silent refresh. ## What’s next [Section titled “What’s next”](#whats-next) * [Set up a custom domain](/guides/custom-domain) for your authentication pages * [Add enterprise SSO](/authenticate/auth-methods/enterprise-sso/) to support SAML and OIDC with your customers’ identity providers --- # DOCUMENT BOUNDARY --- # Web application > Implement Multi-App Authentication for web apps using Authorization Code flow with client_id and client_secret Implement login, token management, and logout in your web application using the Authorization Code flow. Web applications have a backend server that can securely store a `client_secret`, allowing them to authenticate directly with Scalekit’s token endpoint. This guide covers initiating login from your backend, exchanging authorization codes for tokens, managing sessions with secure cookies, and implementing logout. ## Prerequisites [Section titled “Prerequisites”](#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](/authenticate/fsa/multiapp/manage-apps)) * At least one redirect URL configured in **Dashboard > Developers > Applications > \[Your App] > Redirects** ## High-level flow [Section titled “High-level flow”](#high-level-flow) ## Step-by-step implementation [Section titled “Step-by-step implementation”](#step-by-step-implementation) 1. ## Initiate login or signup [Section titled “Initiate login or signup”](#initiate-login-or-signup) Initiate login by redirecting the user to Scalekit’s hosted login page from your backend. Generate and store a `state` parameter before redirecting to validate the callback. ```sh 1 /oauth/authorize? 2 response_type=code& 3 client_id=& 4 redirect_uri=& 5 scope=openid+profile+email+offline_access& 6 state= ``` For detailed parameter definitions, see [Initiate signup/login](/authenticate/fsa/implement-login). 2. ## Handle the callback and complete login [Section titled “Handle the callback and complete login”](#handle-the-callback-and-complete-login) After authentication, Scalekit redirects the user back to your callback endpoint with an authorization `code` and the `state` you sent. Your backend must: * Validate the returned `state` matches what you stored — this confirms the response is for your original request and prevents CSRF attacks * Handle any error parameters before processing * Exchange the authorization code for tokens using your `client_secret` ```sh 1 POST /oauth/token 2 Content-Type: application/x-www-form-urlencoded 3 4 grant_type=authorization_code& 5 client_id=& 6 client_secret=& 7 code=& 8 redirect_uri= ``` ```json 1 { 2 "access_token": "...", 3 "refresh_token": "...", 4 "id_token": "...", 5 "expires_in": 299 6 } ``` 3. ## Manage sessions and token refresh [Section titled “Manage sessions and token refresh”](#manage-sessions-and-token-refresh) Store tokens in secure cookies and validate the access token on each request. When access tokens expire, use the refresh token to obtain new ones without requiring the user to re-authenticate. **Token roles** * **Access token** — Short-lived token (default 5 minutes) for authenticated API requests * **Refresh token** — Long-lived token to obtain new access tokens * **ID token** — JWT containing user identity claims; required for logout Store tokens in secure, HttpOnly cookies with appropriate path scoping to limit exposure. When an access token expires, request new tokens: ```sh 1 POST /oauth/token 2 Content-Type: application/x-www-form-urlencoded 3 4 grant_type=refresh_token& 5 client_id=& 6 client_secret=& 7 refresh_token= ``` Validate access tokens by verifying: * Token signature using Scalekit’s public keys (JWKS endpoint) * `iss` matches your Scalekit environment URL * `aud` includes your `client_id` * `exp` and `iat` are valid timestamps Public keys for signature verification: ```sh 1 /keys ``` 4. ## Implement logout [Section titled “Implement logout”](#implement-logout) Clear your application session and redirect to Scalekit’s logout endpoint to invalidate the shared session. Your logout endpoint must: * Extract the ID token before clearing cookies * Clear application session cookies * Redirect the browser to Scalekit’s logout endpoint ```sh 1 /oidc/logout? 2 id_token_hint=& 3 post_logout_redirect_uri= ``` Configure [backchannel logout](/guides/dashboard/redirects/#back-channel-logout-url) URLs to receive notifications when a logout is performed from another application sharing the same user session. ## Handle errors [Section titled “Handle errors”](#handle-errors) When authentication fails, Scalekit redirects to your callback URL with error parameters instead of an authorization code: ```sh /callback?error=access_denied&error_description=User+denied+access&state= ``` Check for errors before processing the authorization code: * Check if the `error` parameter exists in the URL * 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 [Section titled “(Optional) Use Scalekit Management APIs”](#optional-use-scalekit-management-apis) In addition to handling user authentication, web applications can 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 intended for server-side use only. Enable Management API access in your application: 1. Go to **app.scalekit.com** 2. Navigate to **Developers > Applications** 3. Select your **Web Application** 4. Enable **Allow Scalekit Management API Access** ## What’s next [Section titled “What’s next”](#whats-next) * [Configure backchannel logout](/guides/dashboard/redirects/#back-channel-logout-url) to receive notifications when a user logs out from another app * [Set up a custom domain](/guides/custom-domain) for your authentication pages * [Add enterprise SSO](/authenticate/auth-methods/enterprise-sso/) to support SAML and OIDC with your customers’ identity providers --- # DOCUMENT BOUNDARY --- # User management settings > Configure user management settings, including user attributes and configuration options from to Scalekit dashboard. User management settings allow you to configure how user data is handled in the environment and what attributes are available for users in your application. These settings are accessible from the **User Management** section in the Scalekit dashboard. The Configuration tab provides several important settings that control user registration, organization limits, and branding. ![](/.netlify/images?url=_astro%2F2-configuration.BBcHzaot.png\&w=2786\&h=1746\&dpl=6a01bf5aba8408000850fe26) ### Sign-up for your application [Section titled “Sign-up for your application”](#sign-up-for-your-application) Control whether users can sign up and create new organizations. When enabled, users can register for your application and automatically create a new organization. ### Organization creation limit per user [Section titled “Organization creation limit per user”](#organization-creation-limit-per-user) Define the maximum number of organizations a single user can create. This helps prevent abuse and manage resource usage across your application. ### Limit user sign-ups in an organization [Section titled “Limit user sign-ups in an organization”](#limit-user-sign-ups-in-an-organization) Use this when you need seat caps per organization—for example, when organizations map to departments or when plans include per‑org seat limits. To set a limit from the dashboard: ![](/.netlify/images?url=_astro%2Flimit-org-users.F8VX5klf.png\&w=2454\&h=618\&dpl=6a01bf5aba8408000850fe26) 1. Go to Organizations → Select an Organization → User management 2. Find Organization limits and set max users per organization. Save changes. New users provisioning to this organizations are blocked until limits are increased. Configure them by updating the organization settings. ### Invitation expiry [Section titled “Invitation expiry”](#invitation-expiry) Configure how long user invitation links remain valid. The default setting of **15 days** ensures that invitations don’t remain active indefinitely, improving security while giving invitees reasonable time to accept. ### Organization meta name [Section titled “Organization meta name”](#organization-meta-name) Customize what you call an “Organization” in your application. This meta name appears throughout all Scalekit-hosted pages. For example, you might call it: * “Company” for B2B applications * “Team” for collaboration tools * “Workspace” for productivity apps * “Account” for multi-tenant systems ## User attributes [Section titled “User attributes”](#user-attributes) The User Attributes tab allows you to define custom fields that will be available for user profiles. These attributes help you collect and store additional information about your users beyond the standard profile fields. ![](/.netlify/images?url=_astro%2F1-user-profile.CQCsGgPh.png\&w=2786\&h=1746\&dpl=6a01bf5aba8408000850fe26) When you define custom user attributes, they become part of the user’s profile data that your application can access. This allows you to: * Collect additional information during user registration * Store application-specific user data * Personalize user experiences based on these attributes * Use the data for application logic and user management --- # DOCUMENT BOUNDARY --- # Create organizations > Ways the organizations are created in Scalekit An Organization enables shared data access and enforces consistent authentication methods, session policies, and access control policies for all its members. Scalekit supports two main approaches to organization creation: 1. **Sign up creates organizations automatically**: When users successfully authenticate with your app, Scalekit automatically creates an organization for them. 2. **User creates organizations themselves**: When your application provides users with the option to create new organizations themselves. For instance, Jira enables users to create their own workspaces. ## Sign up creates organizations automatically [Section titled “Sign up creates organizations automatically”](#sign-up-creates-organizations-automatically) Existing [Scalekit integration](/authenticate/fsa/quickstart/) to authenticate users and handle the login flow automatically generates an organization for each user. The organization ID associated with the user will be included in both the ID token and access token. * Decoded ID token ID token decoded ```json 1 { 2 "at_hash": "ec_jU2ZKpFelCKLTRWiRsg", // Access token hash for validation 3 "aud": [ 4 "skc_58327482062864390" // Audience (your client ID) 5 ], 6 "azp": "skc_58327482062864390", // Authorized party (your client ID) 7 "c_hash": "6wMreK9kWQQY6O5R0CiiYg", // Authorization code hash 8 "client_id": "skc_58327482062864390", // Your application's client ID 9 "email": "john.doe@example.com", // User's email address 10 "email_verified": true, // Whether the user's email is verified 11 "exp": 1742975822, // Expiration time (Unix timestamp) 12 "family_name": "Doe", // User's last name 13 "given_name": "John", // User's first name 14 "iat": 1742974022, // Issued at time (Unix timestamp) 15 "iss": "https://scalekit-z44iroqaaada-dev.scalekit.cloud", // Issuer (Scalekit environment URL) 16 "name": "John Doe", // User's full name 17 "oid": "org_59615193906282635", // Organization ID 18 "sid": "ses_65274187031249433", // Session ID 19 "sub": "usr_63261014140912135" // Subject (user's unique ID) 20 } ``` * Decoded access token Decoded access token ```json 1 { 2 "aud": [ 3 "prd_skc_7848964512134X699" // Audience (API or resource server) 4 ], 5 "client_id": "prd_skc_7848964512134X699", // Your application's client ID 6 "oid": "org_89678001X21929734", // Organization ID 7 "exp": 1758265247, // Expiration time (Unix timestamp) 8 "iat": 1758264947, // Issued at time (Unix timestamp) 9 "iss": "https://login.devramp.ai", // Issuer (Scalekit environment URL) 10 "jti": "tkn_90928731115292X63", // JWT ID (unique token identifier) 11 "nbf": 1758264947, // Not before time (Unix timestamp) 12 "permissions": [ // Scopes or permissions granted 13 "workspace_data:write", 14 "workspace_data:read" 15 ], 16 "roles": [ // User roles within the organization 17 "admin" 18 ], 19 "sid": "ses_90928729571723X24", // Session ID 20 "sub": "usr_8967800122X995270", // Subject (user's unique ID) 21 } ``` ## Allow users to create organizations API [Section titled “Allow users to create organizations ”](#allow-users-to-create-organizations--) Applications often provide options for users to create their own organizations. For example, show an option for users such “Create new workspace” within their app. Use the Scalekit SDK to power such options: * Node.js Create and manage organizations ```javascript 1 const { organization } = await scalekit.organization.createOrganization( 2 'Orion Analytics' 3 ); 4 5 // Use case: Sync organization profile to downstream systems 6 const { organization: fetched } = await scalekit.organization.getOrganization(organization.id); ``` * Python Create and manage organizations ```python 1 from scalekit.v1.organizations.organizations_pb2 import CreateOrganization 2 3 response = scalekit_client.organization.create_organization( 4 CreateOrganization( 5 display_name="Orion Analytics", 6 ) 7 ) 8 9 # Use case: Sync organization profile to downstream systems 10 fetched = scalekit_client.organization.get_organization(response[0].organization.id) ``` * Go Create and manage organizations ```go 1 created, err := scalekitClient.Organization().CreateOrganization( 2 ctx, 3 "Orion Analytics", 4 scalekit.CreateOrganizationOptions{}, 5 ) 6 if err != nil { 7 log.Fatalf("create organization: %v", err) 8 } 9 10 // Use case: Sync organization profile to downstream systems 11 fetched, err := scalekitClient.Organization().GetOrganization(ctx, created.Organization.Id) 12 if err != nil { 13 log.Fatalf("get organization: %v", err) 14 } ``` * Java Create and manage organizations ```java 1 // Use case: Provision a workspace after a sales-assisted onboarding 2 CreateOrganization createOrganization = CreateOrganization.newBuilder() 3 .setDisplayName("Orion Analytics") 4 .build(); 5 6 Organization organization = scalekitClient.organizations().create(createOrganization); 7 8 // Use case: Sync organization profile to downstream systems 9 Organization fetched = scalekitClient.organizations().getById(organization.getId()); ``` Next, let’s look at how users can be added to organizations. --- # DOCUMENT BOUNDARY --- # Customize user profiles > Tailor user profiles to your business needs by creating and managing user profile attributes in Scalekit User profiles in Scalekit provide essential identity information through standard attributes like email, name, and phone number. However, when your application requires business-specific data such as employee IDs, department codes, or access levels, you need more flexibility. T This guide shows how to extend user profiles with custom attributes that can be created through the dashboard, managed programmatically via API, and synchronized with enterprise identity providers. #### Standard user profile attributes [Section titled “Standard user profile attributes”](#standard-user-profile-attributes) Let’s start by looking at the existing standard attributes in a `user_profile` from the Scalekit’s [Get User API](https://docs.scalekit.com/apis/#tag/users/get/api/v1/users/%7Bid%7D) response. ```json 1 { 2 "id": "usp_96194455173923084", // Unique user identifier 3 "first_name": "John", // User's given name 4 "last_name": "Doe", // User's family name 5 "name": "John Doe", // Full name for UI display 6 "locale": "en-US", // User's language and region preference 7 "email_verified": true, // Whether the email address has been confirmed 8 "phone_number": "+14155552671", // Contact phone number 9 "metadata": { }, // Additional, non-structured user data 10 "custom_attributes": {} // Business-specific user data 11 } ``` These attributes are also listed in your Scalekit dashboard. Navigate to **Dashboard** > **User Attributes** to see them. Let’s see how we can create a custom attribute. ## Create custom attributes [Section titled “Create custom attributes”](#create-custom-attributes) To add a custom attribute 1. Navigate to **Dashboard** > **User Attributes** and click **Add Attribute**. 2. Configure the new attribute fields: * **Display name** - Human-readable label shown in the dashboard (e.g., “Employee Number”) * **Attribute key** - Internal field name for API and SDK access (e.g., `employee_id`) 3. The new attribute can be used to attach the new information about the user to their user profile. ```diff 1 { 2 "id": "usp_96194455173923084", // Unique user identifier 3 "first_name": "John", // User's given name 4 "last_name": "Doe", // User's family name 5 "name": "John Doe", // Full name for UI display 6 "locale": "en-US", // User's language and region preference 7 "email_verified": true, // Whether the email address has been confirmed 8 "phone_number": "+14155552671", // Contact phone number 9 "metadata": { }, // Additional, non-structured user data 10 "custom_attributes": { 11 "pin_number": "123456" 12 } 13 } ``` Custom attributes are user profile extensions that can be precisely configured to meet your application’s unique needs. For example, as a logistics platform, you might define custom attributes to capture critical operational details like delivery ZIP codes, service zones, or fleet vehicle specifications that apply all your users. ## Map profile attributes to identity providers [Section titled “Map profile attributes to identity providers”](#map-profile-attributes-to-identity-providers) When users authenticate through Single Sign-On (SSO) or join an organization, Scalekit can retrieve and transfer user profile information from the identity provider directly to your application via the ID token during the [login completion](/authenticate/fsa/complete-login/) process. Administrators can configure attribute mapping from their identity provider by selecting specific user profile attributes. This mapping supports both standard and custom attributes seamlessly. ## Modify user profile attributes API [Section titled “Modify user profile attributes ”](#modify-user-profile-attributes-) If your application provides a user interface for users to view and modify their profile details directly within the app, the Scalekit API enables seamless profile attribute updates. * cURL ```sh 1 curl -L -X PATCH '/api/v1/users/' \ 2 -H 'Content-Type: application/json' \ 3 -H 'Authorization: Bearer ...2QA' \ 4 -d '{ 5 "user_profile": { 6 "custom_attributes": { 7 "zip_code": "90210" 8 } 9 } 10 }' ``` * Node.js Update user profile with custom attributes ```javascript 1 // Use case: Update user profile with a custom zip code attribute 2 await scalekit.user.updateUser("", { 3 userProfile: { 4 customAttributes: { 5 zip_code: "11120", 6 }, 7 firstName: "John", 8 lastName: "Doe", 9 locale: "en-US", 10 name: "John Michael Doe", 11 phoneNumber: "+14155552671" 12 } 13 }); ``` * Python Update user profile with custom attributes ```python 1 # Use case: Update user profile with a custom zip code attribute 2 scalekit.user.update_user( 3 "", 4 user_profile={ 5 "custom_attributes": { 6 "zip_code": "11120" 7 }, 8 "first_name": "John", 9 "last_name": "Doe", 10 "locale": "en-US", 11 "name": "John Michael Doe", 12 "phone_number": "+14155552671" 13 } 14 ) ``` * Go Update user profile with custom attributes ```go 1 // Use case: Update user profile with a custom zip code attribute 2 updateUser := &usersv1.UpdateUser{ 3 UserProfile: &usersv1.UpdateUserProfile{ 4 CustomAttributes: map[string]string{ 5 "zip_code": "11120", 6 }, 7 FirstName: "John", 8 LastName: "Doe", 9 Locale: "en-US", 10 Name: "John Michael Doe", 11 PhoneNumber: "+14155552671", 12 }, 13 } 14 15 updatedUser, err := scalekitClient.User().UpdateUser(ctx, "", updateUser) ``` * Java Update user profile with custom attributes ```java 1 // Use case: Update user profile with a custom zip code attribute 2 UpdateUser updateUser = UpdateUser.newBuilder() 3 .setUserProfile( 4 UpdateUserProfile.newBuilder() 5 .putCustomAttributes("zip_code", "11120") 6 .setFirstName("John") 7 .setLastName("Doe") 8 .setLocale("en-US") 9 .setName("John Michael Doe") 10 .setPhoneNumber("+14155552671") 11 .build()) 12 .build(); 13 14 UpdateUserRequest updateReq = UpdateUserRequest.newBuilder() 15 .setUser(updateUser) 16 .build(); 17 18 User updatedUser = scalekitClient.users().updateUser("", updateReq); ``` ## Link your system identifiers & metadata [Section titled “Link your system identifiers & metadata”](#link-your-system-identifiers--metadata) Beyond user profile attributes, you can link your systems with Scalekit to easily map, identify and store more context about organizations and users. This may be helpful when: * You are migrating from an existing system and need to keep your existing identifiers * You are integrating with multiple platforms and need to maintain data consistency * You need to simplify integration by avoiding complex ID mapping between your systems and Scalekit ## Organization external IDs for system integration [Section titled “Organization external IDs for system integration”](#organization-external-ids-for-system-integration) External IDs let you identify organizations using your own identifiers instead of Scalekit’s generated IDs. This is essential when migrating from existing systems or integrating with multiple platforms. 1. #### Set external IDs during organization creation [Section titled “Set external IDs during organization creation”](#set-external-ids-during-organization-creation) Include your system’s identifier when creating organizations to maintain consistent references across your infrastructure. * Node.js Create organization with external ID ```javascript 1 // During user signup or organization creation 2 const organization = await scalekit.organization.create({ 3 display_name: 'Acme Corporation', 4 external_id: 'CUST-12345-ACME' // Your customer ID in your database 5 }); 6 7 console.log('Organization created:', organization.id); 8 console.log('Your ID:', organization.external_id); ``` * Python Create organization with external ID ```python 1 # During user signup or organization creation 2 organization = scalekit.organization.create({ 3 'display_name': 'Acme Corporation', 4 'external_id': 'CUST-12345-ACME' # Your customer ID in your database 5 }) 6 7 print(f'Organization created: {organization.id}') 8 print(f'Your ID: {organization.external_id}') ``` * Go Create organization with external ID ```go 1 // During user signup or organization creation 2 org, err := scalekit.Organization.Create(OrganizationCreateOptions{ 3 DisplayName: "Acme Corporation", 4 ExternalId: "CUST-12345-ACME", // Your customer ID in your database 5 }) 6 7 if err != nil { 8 log.Fatal(err) 9 } 10 11 fmt.Printf("Organization created: %s\n", org.Id) 12 fmt.Printf("Your ID: %s\n", org.ExternalId) ``` * Java Create organization with external ID ```java 1 // During user signup or organization creation 2 Organization organization = scalekit.organization().create( 3 "Acme Corporation", 4 "CUST-12345-ACME" // Your customer ID in your database 5 ); 6 7 System.out.println("Organization created: " + organization.getId()); 8 System.out.println("Your ID: " + organization.getExternalId()); ``` 2. ### Find organizations using your IDs [Section titled “Find organizations using your IDs”](#find-organizations-using-your-ids) Use external IDs to quickly locate organizations when processing webhooks, handling customer support requests, or syncing data between systems. * Node.js Find organization by external ID ```javascript 1 // When processing a webhook or customer update 2 const customerId = 'CUST-12345-ACME'; // From your webhook payload 3 4 const organization = await scalekit.organization.getByExternalId(customerId); 5 6 if (organization) { 7 console.log('Found organization:', organization.display_name); 8 // Process organization updates, sync data, etc. 9 } ``` * Python Find organization by external ID ```python 1 # When processing a webhook or customer update 2 customer_id = 'CUST-12345-ACME' # From your webhook payload 3 4 organization = scalekit.organization.get_by_external_id(customer_id) 5 6 if organization: 7 print(f'Found organization: {organization.display_name}') 8 # Process organization updates, sync data, etc. ``` * Go Find organization by external ID ```go 1 // When processing a webhook or customer update 2 customerId := "CUST-12345-ACME" // From your webhook payload 3 4 org, err := scalekit.Organization.GetByExternalId(customerId) 5 if err != nil { 6 log.Printf("Error finding organization: %v", err) 7 return 8 } 9 10 if org != nil { 11 fmt.Printf("Found organization: %s\n", org.DisplayName) 12 // Process organization updates, sync data, etc. 13 } ``` * Java Find organization by external ID ```java 1 // When processing a webhook or customer update 2 String customerId = "CUST-12345-ACME"; // From your webhook payload 3 4 Organization organization = scalekit.organization().getByExternalId(customerId); 5 6 if (organization != null) { 7 System.out.println("Found organization: " + organization.getDisplayName()); 8 // Process organization updates, sync data, etc. 9 } ``` 3. ### Update external IDs when needed [Section titled “Update external IDs when needed”](#update-external-ids-when-needed) If your customer IDs change or you need to migrate identifier formats, you can update external IDs for existing organizations. * Node.js Update external ID ```javascript 1 const updatedOrg = await scalekit.organization.update(organizationId, { 2 external_id: 'NEW-CUST-12345-ACME' 3 }); 4 5 console.log('External ID updated:', updatedOrg.external_id); ``` * Python Update external ID ```python 1 updated_org = scalekit.organization.update(organization_id, { 2 'external_id': 'NEW-CUST-12345-ACME' 3 }) 4 5 print(f'External ID updated: {updated_org.external_id}') ``` * Go Update external ID ```go 1 updatedOrg, err := scalekit.Organization.Update(organizationId, OrganizationUpdateOptions{ 2 ExternalId: "NEW-CUST-12345-ACME", 3 }) 4 5 fmt.Printf("External ID updated: %s\n", updatedOrg.ExternalId) ``` * Java Update external ID ```java 1 Organization updatedOrg = scalekit.organization().update(organizationId, Map.of( 2 "external_id", "NEW-CUST-12345-ACME" 3 )); 4 5 System.out.println("External ID updated: " + updatedOrg.getExternalId()); ``` ## User external IDs and metadata [Section titled “User external IDs and metadata”](#user-external-ids-and-metadata) Just as organizations need external identifiers, users often require integration with existing systems. User external IDs and metadata work similarly to organization identifiers, enabling you to link Scalekit users with your CRM, HR systems, and other business applications. ### When to use user external IDs and metadata [Section titled “When to use user external IDs and metadata”](#when-to-use-user-external-ids-and-metadata) **External IDs** link Scalekit users to your existing systems: * Reference users in your database, CRM, or billing system * Maintain consistent user identification across multiple platforms * Enable easy data synchronization and lookups **Metadata** stores additional user attributes: * Organizational information (department, location, role level) * Business context (territory, quota, access permissions) * Integration data (external system IDs, custom properties) ### Set user external IDs and metadata during user creation [Section titled “Set user external IDs and metadata during user creation”](#set-user-external-ids-and-metadata-during-user-creation) * Node.js Create user with external ID and metadata ```diff 1 // Use case: Create user during system migration or bulk import with existing system references 2 const { user } = await scalekit.user.createUserAndMembership("", { 3 email: "john.doe@company.com", 4 externalId: "SALESFORCE-003921", 5 metadata: { 6 department: "Sales", 7 employeeId: "EMP-002", 8 territory: "West Coast", 9 quota: 150000, 10 crmAccountId: "ACC-789", 11 hubspotContactId: "12345", 12 + }, 13 userProfile: { 14 firstName: "John", 15 lastName: "Doe", 16 }, 17 sendInvitationEmail: true, 18 }); ``` * Python Create user with external ID and metadata ```diff 1 # Use case: Create user during system migration or bulk import with existing system references 2 user_response = scalekit.user.create_user_and_membership( 3 "", 4 +email="john.doe@company.com", 5 +external_id="SALESFORCE-003921", 6 +metadata={ 7 "department": "Sales", 8 "employee_id": "EMP-002", 9 "territory": "West Coast", 10 "quota": 150000, 11 "crm_account_id": "ACC-789", 12 "hubspot_contact_id": "12345" 13 }, 14 user_profile={ 15 "first_name": "John", 16 "last_name": "Doe" 17 }, 18 send_invitation_email=True 19 ) ``` * Go Create user with external ID and metadata ```diff 1 // Use case: Create user during system migration or bulk import with existing system references 2 newUser := &usersv1.CreateUser{ 3 Email: "john.doe@company.com", 4 +ExternalId: "SALESFORCE-003921", 5 +Metadata: map[string]string{ 6 "department": "Sales", 7 "employee_id": "EMP-002", 8 "territory": "West Coast", 9 "quota": "150000", 10 "crm_account_id": "ACC-789", 11 "hubspot_contact_id": "12345", 12 + }, 13 UserProfile: &usersv1.CreateUserProfile{ 14 FirstName: "John", 15 LastName: "Doe", 16 }, 17 } 18 userResp, err := scalekitClient.User().CreateUserAndMembership( 19 ctx, 20 "", 21 newUser, 22 true, // sendInvitationEmail 23 ) ``` * Java Create user with external ID and metadata ```diff 1 // Use case: Create user during system migration or bulk import with existing system references 2 CreateUser createUser = CreateUser.newBuilder() 3 .setEmail("john.doe@company.com") 4 + .setExternalId("SALESFORCE-003921") 5 + .putMetadata("department", "Sales") 6 + .putMetadata("employee_id", "EMP-002") 7 + .putMetadata("territory", "West Coast") 8 + .putMetadata("quota", "150000") 9 + .putMetadata("crm_account_id", "ACC-789") 10 + .putMetadata("hubspot_contact_id", "12345") 11 + .setUserProfile( 12 +CreateUserProfile.newBuilder() 13 .setFirstName("John") 14 .setLastName("Doe") 15 .build()) 16 .build(); 17 18 CreateUserAndMembershipRequest createUserReq = CreateUserAndMembershipRequest.newBuilder() 19 .setUser(createUser) 20 .setSendInvitationEmail(true) 21 .build(); 22 23 CreateUserAndMembershipResponse userResp = scalekitClient.users() 24 .createUserAndMembership("", createUserReq); ``` ### Update user external IDs and metadata for existing users [Section titled “Update user external IDs and metadata for existing users”](#update-user-external-ids-and-metadata-for-existing-users) * Node.js Update user external ID and metadata ```diff 1 // Use case: Link user with external systems (CRM, HR) and track custom attributes in a single call 2 const updatedUser = await scalekit.user.updateUser("", { 3 externalId: "SALESFORCE-003921", 4 metadata: { 5 department: "Sales", 6 employeeId: "EMP-002", 7 territory: "West Coast", 8 quota: 150000, 9 crmAccountId: "ACC-789", 10 hubspotContactId: "12345", 11 + }, 12 }); ``` * Python Update user external ID and metadata ```diff 1 # Use case: Link user with external systems (CRM, HR) and track custom attributes in a single call 2 updated_user = scalekit.user.update_user( 3 "", 4 +external_id="SALESFORCE-003921", 5 +metadata={ 6 "department": "Sales", 7 "employee_id": "EMP-002", 8 "territory": "West Coast", 9 "quota": 150000, 10 "crm_account_id": "ACC-789", 11 "hubspot_contact_id": "12345" 12 } 13 ) ``` * Go Update user external ID and metadata ```go 1 // Use case: Link user with external systems (CRM, HR) and track custom attributes in a single call 2 updateUser := &usersv1.UpdateUser{ 3 ExternalId: "SALESFORCE-003921", 4 Metadata: map[string]string{ 5 "department": "Sales", 6 "employee_id": "EMP-002", 7 "territory": "West Coast", 8 "quota": "150000", 9 "crm_account_id": "ACC-789", 10 "hubspot_contact_id": "12345", 11 }, 12 } 13 updatedUser, err := scalekitClient.User().UpdateUser( 14 ctx, 15 "", 16 updateUser, 17 ) ``` * Java Update user external ID and metadata ```java 1 // Use case: Link user with external systems (CRM, HR) and track custom attributes in a single call 2 UpdateUser updateUser = UpdateUser.newBuilder() 3 .setExternalId("SALESFORCE-003921") 4 .putMetadata("department", "Sales") 5 .putMetadata("employee_id", "EMP-002") 6 .putMetadata("territory", "West Coast") 7 .putMetadata("quota", "150000") 8 .putMetadata("crm_account_id", "ACC-789") 9 .putMetadata("hubspot_contact_id", "12345") 10 .build(); 11 12 UpdateUserRequest updateReq = UpdateUserRequest.newBuilder() 13 .setUser(updateUser) 14 .build(); 15 16 User updatedUser = scalekitClient.users().updateUser("", updateReq); ``` ### Find users by external ID [Section titled “Find users by external ID”](#find-users-by-external-id) * Node.js Find user by external ID ```javascript 1 // Use case: Look up Scalekit user when you have your system's user ID 2 const user = await scalekit.user.getUserByExternalId("", "SALESFORCE-003921"); 3 console.log(`Found user: ${user.email} with ID: ${user.id}`); ``` * Python Find user by external ID ```python 1 # Use case: Look up Scalekit user when you have your system's user ID 2 user = scalekit.user.get_user_by_external_id("", "SALESFORCE-003921") 3 print(f"Found user: {user['email']} with ID: {user['id']}") ``` * Go Find user by external ID ```go 1 // Use case: Look up Scalekit user when you have your system's user ID 2 user, err := scalekitClient.User().GetUserByExternalId( 3 ctx, 4 "", 5 "SALESFORCE-003921", 6 ) 7 if err != nil { 8 log.Printf("User not found: %v", err) 9 } else { 10 fmt.Printf("Found user: %s with ID: %s\n", user.Email, user.Id) 11 } ``` * Java Find user by external ID ```java 1 // Use case: Look up Scalekit user when you have your system's user ID 2 try { 3 GetUserByExternalIdResponse response = scalekitClient.users() 4 .getUserByExternalId("", "SALESFORCE-003921"); 5 6 User user = response.getUser(); 7 System.out.printf("Found user: %s with ID: %s%n", user.getEmail(), user.getId()); 8 } catch (Exception e) { 9 System.err.println("User not found: " + e.getMessage()); 10 } ``` This integration approach maintains consistent user identity across your system architecture while letting you choose the source of truth for authentication and authorization. Both user and organization external IDs work together to provide complete system integration capabilities. --- # DOCUMENT BOUNDARY --- # Delete users and organizations > Trigger deletions and let Scalekit handle sessions, memberships, and cleanup automatically Properly deleting users and organizations is essential for security and regulatory compliance. Whether a user departs or an entire organization must be removed, it’s important to have reliable deletion processes in place. This guide shows you how to implement deletion for both users and organizations. Provide a feature for administrators to permanently delete a user account. This is useful for handling user account closures, GDPR deletion requests, or cleaning up test accounts. 1. ## Delete a user [Section titled “Delete a user”](#delete-a-user) Call the `deleteUser` method with the user’s ID: * Node.js Delete a user permanently ```javascript 1 // Use case: User account closure, GDPR deletion requests, or cleaning up test accounts 2 await scalekit.user.deleteUser("usr_123"); ``` * Python Delete a user permanently ```python 1 # Use case: User account closure, GDPR deletion requests, or cleaning up test accounts 2 scalekit_client.users.delete_user( 3 user_id="usr_123" 4 ) ``` * Go Delete a user permanently ```go 1 // Use case: User account closure, GDPR deletion requests, or cleaning up test accounts 2 if err := scalekitClient.User().DeleteUser(ctx, "usr_123"); err != nil { 3 panic(err) 4 } ``` * Java Delete a user permanently ```java 1 // Use case: User account closure, GDPR deletion requests, or cleaning up test accounts 2 scalekitClient.users().deleteUser("usr_123"); ``` When you delete a user, Scalekit performs the following actions: * Terminates all of the user’s active sessions. * Removes all of the user’s organization memberships. * Permanently deletes the user account. 2. ## Delete an organization [Section titled “Delete an organization”](#delete-an-organization) Provide a feature for users to delete organizations they own. This is useful for company closures, account restructuring, or removing test organizations. Call the `deleteOrganization` method with the organization’s ID: * Node.js Delete an organization permanently ```javascript 1 // Use case: Company closure, account restructuring, or removing test organizations 2 await scalekit.organization.deleteOrganization(organizationId); ``` * Python Delete an organization permanently ```python 1 # Use case: Company closure, account restructuring, or removing test organizations 2 scalekit_client.organization.delete_organization(organization_id) ``` * Go Delete an organization permanently ```go 1 // Use case: Company closure, account restructuring, or removing test organizations 2 err := scalekitClient.Organization().DeleteOrganization( 3 ctx, 4 organizationId 5 ) 6 if err != nil { 7 panic(err) 8 } ``` * Java Delete an organization permanently ```java 1 // Use case: Company closure, account restructuring, or removing test organizations 2 scalekitClient.organizations().deleteById(organizationId); ``` When you delete an organization, Scalekit performs the following actions: * Terminates active sessions for all organization members. * Removes all user memberships from the organization. * Permanently removes all organization data and settings. * **Cascading deletion**: If a user is a member of only this organization, their account is also permanently deleted. * Users who are members of other organizations retain their accounts and access. Permanent deletion cannot be undone * Ensure you have appropriate backups and audit trails in your system before deleting a user. * If your organization has data retention policies, consider implementing a soft delete. Schedule the permanent deletion for a future date (e.g., 30-60 days) to allow for data backup and user notifications. --- # DOCUMENT BOUNDARY --- # Configure email domain rules > Set up allowed domains for organization auto-join and configure restrictions for generic and disposable email sign-ups Email domain rules control how users join your application in two ways: by restricting who can sign up and by enabling automatic organization membership for trusted domains. These rules help maintain data quality, prevent abuse, and streamline onboarding for enterprise customers. Sign-up restrictions block registrations and invitations from generic email providers (like Gmail or Outlook) and disposable email services, ensuring your user base consists of verified business contacts. Allowed email domains enable users with matching email addresses to automatically join organizations through the organization switcher, reducing manual invitation overhead. Together, these features give you fine-grained control over user addition—blocking unwanted sign-ups while facilitating seamless access for legitimate users from trusted domains. ## Set up sign-up restrictions [Section titled “Set up sign-up restrictions”](#set-up-sign-up-restrictions) Sign-up restrictions help you maintain data quality and prevent abuse by controlling who can create accounts in your application. This is particularly important for B2B applications where you need to ensure users have legitimate business email addresses rather than personal or temporary accounts. These restrictions automatically block registrations and invitations from two types of email addresses: * **Generic email domains** - Public email providers like `@gmail.com`, `@outlook.com`, or `@yahoo.com` that anyone can use * **Disposable email addresses** - Temporary email services often used for spam, trial abuse, or avoiding accountability When enabled, these restrictions apply to both direct signups and organization invitations, ensuring consistent policy enforcement across your application. This prevents users from creating multiple trial accounts, maintains clean analytics, and ensures your user base consists of verified business contacts. The following diagram illustrates how sign-up restrictions work: ### How restrictions affect invitations [Section titled “How restrictions affect invitations”](#how-restrictions-affect-invitations) * Any user with a disposable email domain cannot sign up to create a new organization and cannot be invited to any existing organization. * Any user with a public email domain cannot sign up to create a new organization and cannot be invited to any existing organization. ### Set sign-up restrictions [Section titled “Set sign-up restrictions”](#set-sign-up-restrictions) 1. ### Navigate to sign-up restrictions settings [Section titled “Navigate to sign-up restrictions settings”](#navigate-to-sign-up-restrictions-settings) Go to **Dashboard > Authentication > General** and locate the sign-up restrictions section. 2. ### Configure restriction options [Section titled “Configure restriction options”](#configure-restriction-options) Toggle the following options based on what suits your application: * **Block disposable email domains**: Prevents temporary/disposable email addresses from signing up or being invited * **Block public email domains**: Prevents generic email providers like Gmail, Outlook, Yahoo from creating organizations ![](/.netlify/images?url=_astro%2Fui.D6G2x64L.png\&w=2858\&h=1611\&dpl=6a01bf5aba8408000850fe26) 3. ### Save your settings [Section titled “Save your settings”](#save-your-settings) Click **Save** to apply the restrictions. Changes take effect immediately for all new signups and invitations. ## Configure allowed email domains [Section titled “Configure allowed email domains”](#configure-allowed-email-domains) Allowed email domains lets organization admins define trusted domains for their organization. When a user signs in or signs up with a matching email domain, Scalekit suggests the user to join that organization in the **organization switcher** so the user can join the organization with one click. This feature is authentication-method agnostic: regardless of whether a user authenticates via SSO, social login, or passwordless authentication, organization options are suggested based on their email domain. When a user signs up or signs in, Scalekit will automatically: 1. **Match email domains** - Check if the user’s email domain matches configured allowed domains for any organization. 2. **Suggest organization options** - Show the user available organizations they can join through an organization switcher. 3. **Enable user choice** - Allow users to decide which of the suggested organizations they want to join. 4. **Create organization membership** - Automatically add the user to their selected organization. ### Manage allowed email domains in Scalekit Dashboard [Section titled “Manage allowed email domains in Scalekit Dashboard”](#manage-allowed-email-domains-in-scalekit-dashboard) Allowed email domains can be configured for an organization through the Scalekit Dashboard. ![](/.netlify/images?url=_astro%2Fdashboard.Cf5i9h8I.png\&w=2938\&h=1588\&dpl=6a01bf5aba8408000850fe26) 1. Navigate to **Organizations** and **select an organization**. 2. Navigate to **Overview** > **User Management** > **Allowed email domains**. 3. Add or edit allowed email domains for automatic suggestions/provisioning. ### Manage allowed email domains API [Section titled “Manage allowed email domains ”](#manage-allowed-email-domains-) Configure allowed email domains for an organization programmatically through the Scalekit API. Before proceeding, complete the steps in the [installation guide](/authenticate/set-up-scalekit/). * cURL Register, list, get, and delete allowed email domains ```sh # 1. Register an allowed email domain # Use case: Restrict user registration to specific company domains for B2B applications curl 'https:///api/v1/organizations/{organization_id}/domains' \ --request POST \ --header 'Content-Type: application/json' \ --data '{ "domain": "customerdomain.com", "domain_type": "ALLOWED_EMAIL_DOMAIN" }' # 2. List all registered allowed email domains # Use case: Display domain restrictions in admin dashboard or verify current settings curl 'https:///api/v1/organizations/{organization_id}/domains' # 3. Get details of a specific domain # Use case: Verify domain configuration or retrieve domain metadata curl 'https:///api/v1/organizations/{organization_id}/domains/{domain_id}' # 4. Delete an allowed email domain # Use case: Remove domain restrictions or clean up unused configurations curl 'https:///api/v1/organizations/{organization_id}/domains/{domain_id}' \ --request DELETE ``` * Nodejs Register, list, get, and delete allowed email domains ```js 1 // 1. Register an allowed email domain 2 // Use case: Restrict user registration to specific company domains for B2B applications 3 const newDomain = await scalekit.createDomain("org-123", "customerdomain.com", { 4 domainType: "ALLOWED_EMAIL_DOMAIN", 5 }); 6 7 // 2. List all registered allowed email domains 8 // Use case: Display domain restrictions in admin dashboard or verify current settings 9 const domains = await client.domain.listDomains(organizationId); 10 11 // 3. Get details of a specific domain 12 // Use case: Verify domain configuration or retrieve domain metadata 13 const domain = await client.domain.getDomain(organizationId, domainId); 14 15 // 4. Delete an allowed email domain 16 // Use case: Remove domain restrictions or clean up unused configurations 17 // Caution: Deletion is permanent and may affect user access 18 await client.domain.deleteDomain(organizationId, domainId); ``` --- # DOCUMENT BOUNDARY --- # UI widgets - Sign up, login, user profiles > Customers manage organizations and users for their workspace through hosted widgets Your customers, especially workspace administrators, want to manage organizations and users for their members. Scalekit provides a hosted widgets portal that lets your customers view and manage organizations, users, and settings for their workspace on their own—without you building custom UI. To integrate hosted widgets, redirect your organization members to the Hosted Widgets URL: Hosted widgets URL ```sh /ui/ # https://your-app-env.scalekit.com/ui/ ``` Scalekit verifies the organization member’s access permissions and automatically controls what they can access in the widgets. The widgets inherit your application’s [branding](/fsa/guides/login-page-branding/) and support your [custom domain](/guides/custom-domain/). ## Signup/login widgets [Section titled “Signup/login widgets”](#signuplogin-widgets) Signup and login widgets give users an entry point to authentication before they access the rest of Hosted Widgets. Use these pages as managed, branded auth screens without building custom UI. 1. ### Redirect your customers to Scalekit’s auth endpoint [Section titled “Redirect your customers to Scalekit’s auth endpoint”](#redirect-your-customers-to-scalekits-auth-endpoint) Pass `prompt` in the authorization URL to decide which hosted auth screen appears for your customers. * Login Authorization URL (login) ```sh /oauth/authorize? response_type=code& client_id=& redirect_uri=& scope=openid+profile+email+offline_access& state=& prompt=login ``` Pass `prompt=login` to show the login page. Your customers will land on `/a/auth/login`. ![Login page of coffee desk app](/.netlify/images?url=_astro%2Flogin.CbTjQzvz.png\&w=3024\&h=1898\&dpl=6a01bf5aba8408000850fe26) * Signup Authorization URL (signup) ```sh /oauth/authorize? response_type=code& client_id=& redirect_uri=& scope=openid+profile+email+offline_access& state=& prompt=create ``` Pass `prompt=create` to show the signup page. Your customers will land on `/a/auth/signup`. ![Coffee desk signup page](/.netlify/images?url=_astro%2Fsignup.CTadE9O-.png\&w=3024\&h=1898\&dpl=6a01bf5aba8408000850fe26) For complete URL parameters and SDK examples, see [Initiate user signup or login](/authenticate/fsa/implement-login/). ## Organization widgets [Section titled “Organization widgets”](#organization-widgets) Organization widgets let your customers manage their organization’s settings, members, and configurations. These widgets are access-controlled using Scalekit permissions and feature entitlements. A widget appears only if the user has the required permissions and the organization has the corresponding feature enabled. 1. ### Manage organization settings [Section titled “Manage organization settings”](#manage-organization-settings) Your customers can view and manage their organization profile, including allowed email domains. Navigate to **Organization settings** to update organization details. ![](/.netlify/images?url=_astro%2Forg_settings.XshZN6sS.png\&w=2936\&h=1592\&dpl=6a01bf5aba8408000850fe26) 2. ### Manage organization members [Section titled “Manage organization members”](#manage-organization-members) Your customers can view organization members, invite new members, manage roles, and remove members from the organization. The **Member management** widget provides a complete view of their team. ![](/.netlify/images?url=_astro%2Forg_member.pe4fgTMu.png\&w=2936\&h=1592\&dpl=6a01bf5aba8408000850fe26) 3. ### Configure SSO for the organization [Section titled “Configure SSO for the organization”](#configure-sso-for-the-organization) Your customers can set up and manage Single Sign-On for their organization. The widget includes a setup guide tailored to their identity provider, making it easy to connect their SSO connection. ![](/.netlify/images?url=_astro%2Forg_sso.IHoRc3E6.png\&w=2936\&h=1592\&dpl=6a01bf5aba8408000850fe26) 4. ### Configure SCIM for the organization [Section titled “Configure SCIM for the organization”](#configure-scim-for-the-organization) Your customers can set up and manage SCIM provisioning for their organization. The widget includes a setup guide tailored to their identity provider to automate user and group provisioning. ![](/.netlify/images?url=_astro%2Forg_scim.CBDzga3B.png\&w=2936\&h=1592\&dpl=6a01bf5aba8408000850fe26) ## User widgets [Section titled “User widgets”](#user-widgets) User widgets let your customers manage their personal profile and security settings. These widgets are accessible to all authenticated users and are not controlled by organization-level feature entitlements or Scalekit permissions. 1. ### Manage profile [Section titled “Manage profile”](#manage-profile) Your customers can view and manage their personal profile information, including their name, email, and other account details. ![](/.netlify/images?url=_astro%2Fuser_profile.DF85cQEC.png\&w=2936\&h=1592\&dpl=6a01bf5aba8408000850fe26) 2. ### Manage security [Section titled “Manage security”](#manage-security) Your customers can register and manage passkeys, view active sessions, and revoke sessions. The **User security** widget helps them maintain account security. ![](/.netlify/images?url=_astro%2Fuser_security.B5SWg3po.png\&w=2936\&h=1592\&dpl=6a01bf5aba8408000850fe26) ## Access management [Section titled “Access management”](#access-management) Hosted Widgets enforce access using **Scalekit permissions**. You can map these permissions to any application roles assigned to the end user. When a user accesses Hosted Widgets, Scalekit checks their permissions and shows the available widgets. | Permission | Purpose | | -------------------------- | ------------------------------------------------------ | | `sk_org_settings_read` | View organization profile and settings | | `sk_org_settings_manage` | View and modify organization profile and settings | | `sk_org_users_read` | View users in an organization | | `sk_org_users_invite` | Invite new users to an organization | | `sk_org_users_delete` | Remove users from an organization | | `sk_org_users_role_change` | Change roles of users in an organization | | `sk_org_sso_read` | View SSO configuration for an organization | | `sk_org_sso_manage` | View and modify SSO configuration for an organization | | `sk_org_scim_read` | View SCIM configuration for an organization | | `sk_org_scim_manage` | View and modify SCIM configuration for an organization | *** ## Branding & customization [Section titled “Branding & customization”](#branding--customization) Hosted Widgets can be customized to match your application’s [branding](/fsa/guides/login-page-branding/). Hosted Widgets use your application logo, favicon, primary color, and more to look like an extension of your app. You can also change the Hosted Widgets URL to match your application URL by setting up a [custom domain](/guides/custom-domain/). ## Common Hosted Widgets scenarios [Section titled “Common Hosted Widgets scenarios”](#common-hosted-widgets-scenarios) --- # DOCUMENT BOUNDARY --- # Provision user accounts Just-In-Time (JIT) > Turn first-time SSO logins into instant, secure access Organizations where the SSO connection is set up, the enterprise users maybe yet to sign up on your application before they can access your application. Scalekit can automatically provision the user accounts as they sign in through SSO for the first time and creates a membership with an organization instantly. Your app will receive the user’s profile and organization membership details. This is called Just-in-time (JIT) provisioning. This eliminates the need for manual invitations and allows users to access your application immediately after authenticating with their identity provider. JIT is enabled by default once you [integrated](/authenticate/fsa/quickstart/) and enabled [the SSO connection](/authenticate/auth-methods/enterprise-sso/). ## Manage JIT provisioning [Section titled “Manage JIT provisioning”](#manage-jit-provisioning) Manage JIT provisioning settings for each organization through the Scalekit Dashboard. Register organization domains to enable automatic user creation, and configure whether Scalekit should sync user attributes every time users sign in through SSO. 1. ### Register organization owned domains [Section titled “Register organization owned domains”](#register-organization-owned-domains) Register email domains for your organization to enable JIT provisioning. JIT provisioning only works for users whose email domain matches one of the organization’s registered [Organization domains](/authenticate/auth-methods/enterprise-sso/). This ensures that only verified members of the organization can be automatically provisioned. **Contractors and external users** with non-matching domains (for eg, `joe@ext.yourapp.com`) cannot be automatically provisioned. These users must be [manually invited](/fsa/guides/user-invitations/) to join the organization. This ensures that unauthorized users cannot obtain access automatically. 2. ### Toggle JIT provisioning on or off [Section titled “Toggle JIT provisioning on or off”](#toggle-jit-provisioning-on-or-off) **JIT provisioning is enabled by default** once you [integrated](/authenticate/fsa/quickstart/) and enabled [the SSO connection](/authenticate/auth-methods/enterprise-sso/). You can toggle JIT provisioning on or off from the Scalekit Dashboard. Go to **Organizations** and select the target organization > **Single Sign On** → **Settings** → **Just-in-time provisioning** section. ![](/.netlify/images?url=_astro%2Fjit-provisioning.CWBROiBA.png\&w=2934\&h=1588\&dpl=6a01bf5aba8408000850fe26) 3. ### Keep the user profile in sync with the identity provider [Section titled “Keep the user profile in sync with the identity provider”](#keep-the-user-profile-in-sync-with-the-identity-provider) Enable **Sync user attributes during login** to keep user profiles updated. When enabled, Scalekit updates the user’s profile using attributes from the identity provider each time they authenticate. This keeps the user’s profile in Scalekit aligned with the external Identity Provider. ![](/.netlify/images?url=_astro%2Fsync-user-profile.DW9qgfGm.png\&w=2932\&h=1580\&dpl=6a01bf5aba8408000850fe26) 4. ### Using self-service Admin Portal for organization admins [Section titled “Using self-service Admin Portal for organization admins”](#using-self-service-admin-portal-for-organization-admins) Your customers (organization admins) can manage JIT provisioning settings through the Admin Portal, including registering organization-owned domains, toggling JIT provisioning on or off, and keeping user profiles in sync with the identity provider. [Generate and share Admin Portal](/guides/admin-portal/) with your customers to set up SSO for their organization. Your end customer can manage the JIT configuration in **Admin portal** > **Single Sign On** > **Settings** > **Just-in-time provisioning** section. ## Common JIT provisioning scenarios [Section titled “Common JIT provisioning scenarios”](#common-jit-provisioning-scenarios) --- # DOCUMENT BOUNDARY --- # Merge user identities > Scalekit automatically merges user identities from different authentication methods, ensuring a single user profile and preventing duplicate accounts Users can sign into your application using different authentication methods. A user might authenticate with a passwordless method today and LinkedIn OAuth tomorrow. Scalekit automatically merges these identities into a single user profile. This prevents duplicate accounts and ensures a unified experience. Identity linking is how Scalekit safely deduplicates authentication methods across identity providers. Scalekit uses the **email address** as the unique identifier and access to the email inbox as the source of truth. When users prove access to their email inbox through any authentication method, Scalekit treats this as an identity. Scalekit automatically links multiple identities together using the user’s email address as the source of truth. All authentication methods for the same email address are associated with a single User object. ## Domain verification [Section titled “Domain verification”](#domain-verification) When an organization administrator verifies a domain for their organization through [allowed email domains](/authenticate/manage-users-orgs/email-domain-rules/), they prove they have access to create email inboxes. A **verified domain implies the ability to verify all users with that email domain**. When a domain is verified and an SSO connection is configured, users who sign in through an organization’s identity provider are automatically considered email verified if the domain matches. This reduces friction for your end users while maintaining security. Users who sign in through SSO with an email address that is not a verified domain are not considered verified. These users must go through the email verification process. ## Merge SSO identities [Section titled “Merge SSO identities”](#merge-sso-identities) Users can have multiple authentication methods. Users can also have multiple SSO credentials. This happens when a user works with multiple organizations that each require SSO authentication for all members. There is still only one User object. Users choose which organization’s SSO identity provider to use when authenticating. When users sign in through an SSO identity provider for the first time, Scalekit checks if their email domain is verified. If verified, Scalekit automatically links the SSO credential to the user’s existing account. Email verification safety still applies. When a user signs in for the first time through an SSO identity provider where the user’s email address is not a verified domain, Scalekit asks the user to verify their email before linking the SSO credential to their account. --- # DOCUMENT BOUNDARY --- # Implement organization switcher > Let users switch across workspaces using prompt-based selection or direct org routing via organization ID Organization switching lets users access multiple organizations or workspaces within your application. This guide shows you how to implement organization switching using Scalekit’s built-in switcher or by building your own organization switcher in your application. This feature is essential for B2B applications where users may belong to several organizations simultaneously. Common scenarios include: * **Personal workspace to corporate workspace**: Users sign up with their organization’s email address, creating their personal workspace. Later, when their organization subscribes to your app, a new corporate workspace is created (for example, “AcmeCorp workspace”). * **Multi-organization contractors**: External consultants or contractors who belong to multiple organizations, each with their own SSO authentication policies. These users need to switch between different client organizations while maintaining secure access to each workspace. ![](/.netlify/images?url=_astro%2F1-switcher.BmXDeGKX.png\&w=2940\&h=1662\&dpl=6a01bf5aba8408000850fe26) ## Default organization switching behavior [Section titled “Default organization switching behavior”](#default-organization-switching-behavior) When users belong to multiple organizations, Scalekit automatically handles organization switching during the authentication flow: 1. Users click **Sign In** on your application. 2. Your application redirects users to Scalekit’s sign-in page. 3. Users authenticate using one of the available sign-in methods. 4. Scalekit displays a list of organizations that users belong to. 5. Users select the organization they want to sign in to. 6. Users are redirected to the organization’s workspace and signed in. Scalekit provides built-in support for organization switching through automatic organization detection, a hosted organization switcher UI, and secure session management. Each organization maintains its own authentication context and policies. ## Control organization switching behavior [Section titled “Control organization switching behavior”](#control-organization-switching-behavior) You can customize the organization switcher’s behavior by adding query parameters when generating the authorization URL. These parameters give you precise control over how users navigate between organizations. ### Display organization switcher [Section titled “Display organization switcher”](#display-organization-switcher) Add the `prompt: 'select_account'` parameter when generating the authorization URL. This forces Scalekit to display a list of organizations the user belongs to, even if they’re already signed in. * Node.js Express.js ```diff 1 // Use case: Show organization switcher after user authentication 2 const redirectUri = 'http://localhost:3000/api/callback'; 3 const options = { 4 scopes: ['openid', 'profile', 'email', 'offline_access'], 5 prompt: 'select_account' 6 }; 7 8 const authorizationUrl = scalekit.getAuthorizationUrl(redirectUri, options); 9 10 res.redirect(authorizationUrl); ``` * Python Flask ```diff 1 # Use case: Show organization switcher after user authentication 2 from scalekit import AuthorizationUrlOptions 3 4 redirect_uri = 'http://localhost:3000/api/callback' 5 options = AuthorizationUrlOptions() 6 options.scopes = ['openid', 'profile', 'email', 'offline_access'] 7 options.prompt = 'select_account' 8 9 authorization_url = scalekit.get_authorization_url(redirect_uri, options) 10 return redirect(authorization_url) ``` * Go Gin ```diff 1 // Use case: Show organization switcher after user authentication 2 redirectUri := "http://localhost:3000/api/callback" 3 options := scalekit.AuthorizationUrlOptions{ 4 Scopes: []string{"openid", "profile", "email", "offline_access"}, 5 +Prompt: "select_account", 6 } 7 8 authorizationUrl, err := scalekitClient.GetAuthorizationUrl(redirectUri, options) 9 if err != nil { 10 // handle error appropriately 11 panic(err) 12 } 13 14 c.Redirect(http.StatusFound, authorizationUrl.String()) ``` * Java Spring ```diff 1 // Use case: Show organization switcher after user authentication 2 import com.scalekit.internal.http.AuthorizationUrlOptions; 3 import java.net.URL; 4 import java.util.Arrays; 5 6 String redirectUri = "http://localhost:3000/api/callback"; 7 AuthorizationUrlOptions options = new AuthorizationUrlOptions(); 8 +options.setScopes(Arrays.asList("openid", "profile", "email", "offline_access")); 9 options.setPrompt("select_account"); 10 11 URL authorizationUrl = scalekit.authentication().getAuthorizationUrl(redirectUri, options); ``` This displays the organization switcher UI where users can choose which organization to access. ### Switch users directly to a specific organization [Section titled “Switch users directly to a specific organization”](#switch-users-directly-to-a-specific-organization) To bypass the organization switcher and directly authenticate users into a specific organization, include both the `prompt: 'select_account'` parameter and the `organizationId` parameter: * Node.js Express.js ```diff 1 // Use case: Directly route users to a specific organization 2 const redirectUri = 'http://localhost:3000/api/callback'; 3 const options = { 4 scopes: ['openid', 'profile', 'email', 'offline_access'], 5 prompt: 'select_account', 6 organizationId: 'org_1233434' 7 }; 8 9 const authorizationUrl = scalekit.getAuthorizationUrl(redirectUri, options); 10 11 res.redirect(authorizationUrl); ``` * Python Flask ```diff 1 # Use case: Directly route users to a specific organization 2 from scalekit import AuthorizationUrlOptions 3 4 redirect_uri = 'http://localhost:3000/api/callback' 5 options = AuthorizationUrlOptions() 6 options.scopes = ['openid', 'profile', 'email', 'offline_access'] 7 options.prompt = 'select_account' 8 options.organization_id = 'org_1233434' 9 10 authorization_url = scalekit.get_authorization_url(redirect_uri, options) 11 return redirect(authorization_url) ``` * Go Gin ```diff 1 // Use case: Directly route users to a specific organization 2 redirectUri := "http://localhost:3000/api/callback" 3 options := scalekit.AuthorizationUrlOptions{ 4 +Scopes: []string{"openid", "profile", "email", "offline_access"}, 5 +Prompt: "select_account", 6 OrganizationId: "org_1233434", 7 } 8 9 authorizationUrl, err := scalekitClient.GetAuthorizationUrl(redirectUri, options) 10 if err != nil { 11 // handle error appropriately 12 panic(err) 13 } 14 15 c.Redirect(http.StatusFound, authorizationUrl.String()) ``` * Java Spring ```diff 1 // Use case: Directly route users to a specific organization 2 import com.scalekit.internal.http.AuthorizationUrlOptions; 3 import java.net.URL; 4 import java.util.Arrays; 5 6 String redirectUri = "http://localhost:3000/api/callback"; 7 AuthorizationUrlOptions options = new AuthorizationUrlOptions(); 8 +options.setScopes(Arrays.asList("openid", "profile", "email", "offline_access")); 9 +options.setPrompt("select_account"); 10 options.setOrganizationId("org_1233434"); 11 12 URL authorizationUrl = scalekit.authentication().getAuthorizationUrl(redirectUri, options); ``` When you include both parameters, Scalekit will: * **If the user is already authenticated**: Directly sign them into the specified organization * **If the user needs to authenticate**: First authenticate the user, then sign them into the specified organization ## Organization switching parameters [Section titled “Organization switching parameters”](#organization-switching-parameters) Use these parameters to control the organization switching behavior: | Parameter | Description | Example | | ---------------------------------------------- | ---------------------------------- | ---------------------------------------------------------------------------- | | `prompt=select_account` | Shows the organization switcher UI | Forces organization selection even for authenticated users | | `prompt=select_account&organizationId=org_123` | Direct organization access | Bypasses switcher and authenticates directly into the specified organization | --- # DOCUMENT BOUNDARY --- # Provision users and groups with SCIM > Automate user and group lifecycle management using SCIM provisioning Scalekit supports user and group provisioning using the [SCIM protocol](/directory/guides/user-provisioning-basics/), allowing your customers to manage access to their organization in your app directly from their directory provider. With SCIM, the directory becomes the source of truth for organization membership, user profile attributes, and access — eliminating manual invites, role drift, and delayed deprovisioning. SCIM ensures that access to your application always reflects the organization’s directory state, from onboarding to offboarding. Using SCIM, your customers can: * Add users to their organization * Keep user attributes (like name, email or role) in sync * Remove users from their organization * Control application roles through directory group membership SCIM provisioning enables end-to-end lifecycle management, ensuring access is granted, updated, and revoked automatically as users move through the organization. *** ### Who should use SCIM provisioning? [Section titled “Who should use SCIM provisioning?”](#who-should-use-scim-provisioning) SCIM provisioning is recommended for: * Enterprise customers that require **centralized identity management** * Teams already using a directory provider like Okta, Azure AD (Entra ID), or Google Workspace * Customers that need **group-based access control** and automated deprovisioning *** ### Manage SCIM provisioning [Section titled “Manage SCIM provisioning”](#manage-scim-provisioning) 1. ## Register organization-owned domains [Section titled “Register organization-owned domains”](#register-organization-owned-domains) Register the email domains owned by the organization. SCIM provisioning only works for users whose email domain matches one of the organization’s registered **Organization domains**. This ensures that only verified members of the organization can be automatically provisioned. **Contractors and external users** with non-matching domains (e.g., `joe@ext.yourapp.com`) cannot be automatically provisioned via SCIM. These users must be [manually invited](/fsa/guides/user-invitations/) to join the organization. This ensures that unauthorized users cannot obtain access automatically. Navigate to **Dashboard** > **Organizations** and select the target organization > **Overview** > **Organization Domains** section to register organization domains. 2. ## Enable SCIM provisioning for the organization [Section titled “Enable SCIM provisioning for the organization”](#enable-scim-provisioning-for-the-organization) SCIM provisioning should be enabled for the target organization either through the Scalekit Dashboard or the self-service [Admin Portal](/guides/admin-portal/). Follow the detailed setup instructions [here](/guides/user-management/scim-provisioning/). 3. ## Provision users and groups from the directory [Section titled “Provision users and groups from the directory”](#provision-users-and-groups-from-the-directory) Once SCIM provisioning is enabled for the organization, the directory becomes the system of record for that organization in your app. Organization administrators can manage access directly from their IdP by: * Assigning users or groups to your application * Updating user profile attributes * Removing users or groups to revoke access 4. ## Group-based role assignment [Section titled “Group-based role assignment”](#group-based-role-assignment) Scalekit supports assigning roles to users in your app based on directory group membership. This enables consistent, policy-driven access control managed entirely from the directory provider. * Map directory groups to application roles in Scalekit * Users receive roles automatically when added to mapped groups * Roles are revoked when users are removed from those groups 5. ## User attribute mapping [Section titled “User attribute mapping”](#user-attribute-mapping) Scalekit automatically maps the following user attributes from the directory to the Scalekit user profile: * `email` * `preferred_username` * `name` * `given_name` * `family_name` * `picture` * `phone_number` * `locale` * `custom_attributes` When attributes change in the directory, Scalekit updates the user profile automatically during SCIM synchronization. *** ### Supported directory providers [Section titled “Supported directory providers”](#supported-directory-providers) Scalekit supports SCIM provisioning with common enterprise directory providers including Okta, Entra ID (Azure AD), and Google Workspace. See the full list of supported providers [here](/guides/integrations/scim-integrations/). *** ### Common SCIM provisioning scenarios [Section titled “Common SCIM provisioning scenarios”](#common-scim-provisioning-scenarios) --- # DOCUMENT BOUNDARY --- # Add Modular SSO > Enable enterprise SSO for any customer in minutes with built-in SAML and OIDC integrations Enterprise customers often require Single Sign-On (SSO) support for their applications. Rather than building custom integrations for every identity provider—such as Okta, Entra ID, or JumpCloud—and managing the detailed configuration of OIDC and SAML protocols, there are more scalable approaches available. Modular SSO is designed for applications that maintain their own user database and session management. This lightweight integration focuses solely on identity verification, giving you complete control over user data and authentication flows. Choose Modular SSO when you: * Want to manage user records in your own database * Prefer to implement custom session management logic * Need to integrate SSO without changing your existing authentication architecture * Already have existing user management infrastructure ### Build with a coding agent * Claude Code ```bash /plugin marketplace add scalekit-inc/claude-code-authstack ``` ```bash /plugin install modular-sso@scalekit-auth-stack ``` * Codex ```bash curl -fsSL https://raw.githubusercontent.com/scalekit-inc/codex-authstack/main/install.sh | bash ``` ```bash # Restart Codex # Plugin Directory -> Scalekit Auth Stack -> install modular-sso ``` * GitHub Copilot CLI ```bash copilot plugin marketplace add scalekit-inc/github-copilot-authstack ``` ```bash copilot plugin install modular-sso@scalekit-auth-stack ``` * 40+ agents ```bash npx skills add scalekit-inc/skills --skill modular-sso ``` [Continue building with AI →](/dev-kit/build-with-ai/sso/) 1. ## Configure “Modular Auth” mode [Section titled “Configure “Modular Auth” mode”](#configure-modular-auth-mode) Ensure your environment is configured in Modular Auth mode. 1. Go to Dashboard > Settings > Authentication Mode 2. Select “Modular Auth” and save Now you’re ready to start integrating SSO into your app! Next, we’ll cover how to use the SDK to authenticate users. 2. ## Set up Scalekit [Section titled “Set up Scalekit”](#set-up-scalekit) Use the following instructions to install the SDK for your technology stack. * Node.js ```bash npm install @scalekit-sdk/node ``` * Python ```sh pip install scalekit-sdk-python ``` * Go ```sh go get -u github.com/scalekit-inc/scalekit-sdk-go ``` * Java ```groovy /* Gradle users - add the following to your dependencies in build file */ implementation "com.scalekit:scalekit-sdk-java:2.0.11" ``` ```xml com.scalekit scalekit-sdk-java 2.0.11 ``` Configure your environment with API credentials. Navigate to **Dashboard > Developers > Settings > API credentials** and copy these values to your `.env` file: .env ```sh SCALEKIT_ENVIRONMENT_URL= # Example: https://acme.scalekit.dev or https://auth.acme.com (if custom domain is set) SCALEKIT_CLIENT_ID= # Example: skc_1234567890abcdef SCALEKIT_CLIENT_SECRET= # Example: test_abcdef1234567890 ``` ### Register redirect URL for your app [Section titled “Register redirect URL for your app”](#register-redirect-url-for-your-app) You need to register redirect URL 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 user starts sign-in directly from their identity provider (IdP-initiated SSO). [Learn more](/guides/dashboard/redirects/#initiate-login-url) 3. ## Redirect the users to their enterprise identity provider login page [Section titled “Redirect the users to their enterprise identity provider login page”](#redirect-the-users-to-their-enterprise-identity-provider-login-page) Create an authorization URL to redirect users to Scalekit’s sign-in page. Use the Scalekit SDK to construct this URL with your redirect URI and required scopes. * Node.js authorization-url.js ```javascript 1 import { Scalekit } from '@scalekit-sdk/node'; 2 3 const scalekit = new ScalekitClient( 4 '', // Your Scalekit environment URL 5 '', // Unique identifier for your app 6 '', 7 ); 8 9 const options = {}; 10 11 // Specify which SSO connection to use (choose one based on your use case) 12 // These identifiers are evaluated in order of precedence: 13 14 // 1. connectionId (highest precedence) - Use when you know the exact SSO connection 15 options['connectionId'] = 'conn_15696105471768821'; 16 17 // 2. organizationId - Routes to organization's SSO (useful for multi-tenant apps) 18 // If org has multiple connections, the first active one is selected 19 options['organizationId'] = 'org_15421144869927830'; 20 21 // 3. loginHint (lowest precedence) - Extracts domain from email to find connection 22 // Domain must be registered to the organization (manually via Dashboard or through admin portal during enterprise onboarding) 23 options['loginHint'] = 'user@example.com'; 24 25 // redirect_uri: Your callback endpoint that receives the authorization code 26 // Must match the URL registered in your Scalekit dashboard 27 const redirectUrl = 'https://your-app.com/auth/callback'; 28 29 const authorizationURL = scalekit.getAuthorizationUrl(redirectUrl, options); 30 // Redirect user to this URL to begin SSO authentication ``` * Python authorization\_url.py ```python 1 from scalekit import ScalekitClient, AuthorizationUrlOptions 2 3 scalekit = ScalekitClient( 4 '', # Your Scalekit environment URL 5 '', # Unique identifier for your app 6 '' 7 ) 8 9 options = AuthorizationUrlOptions() 10 11 # Specify which SSO connection to use (choose one based on your use case) 12 # These identifiers are evaluated in order of precedence: 13 14 # 1. connection_id (highest precedence) - Use when you know the exact SSO connection 15 options.connection_id = 'conn_15696105471768821' 16 17 # 2. organization_id - Routes to organization's SSO (useful for multi-tenant apps) 18 # If org has multiple connections, the first active one is selected 19 options.organization_id = 'org_15421144869927830' 20 21 # 3. login_hint (lowest precedence) - Extracts domain from email to find connection 22 # Domain must be registered to the organization (manually via Dashboard or through admin portal during enterprise onboarding) 23 options.login_hint = 'user@example.com' 24 25 # redirect_uri: Your callback endpoint that receives the authorization code 26 # Must match the URL registered in your Scalekit dashboard 27 redirect_uri = 'https://your-app.com/auth/callback' 28 29 authorization_url = scalekit_client.get_authorization_url( 30 redirect_uri=redirect_uri, 31 options=options 32 ) 33 # Redirect user to this URL to begin SSO authentication ``` * Go authorization\_url.go ```go 1 import ( 2 "github.com/scalekit-inc/scalekit-sdk-go" 3 ) 4 5 func main() { 6 scalekitClient := scalekit.NewScalekitClient( 7 "", // Your Scalekit environment URL 8 "", // Unique identifier for your app 9 "" 10 ) 11 12 options := scalekitClient.AuthorizationUrlOptions{} 13 14 // Specify which SSO connection to use (choose one based on your use case) 15 // These identifiers are evaluated in order of precedence: 16 17 // 1. ConnectionId (highest precedence) - Use when you know the exact SSO connection 18 options.ConnectionId = "conn_15696105471768821" 19 20 // 2. OrganizationId - Routes to organization's SSO (useful for multi-tenant apps) 21 // If org has multiple connections, the first active one is selected 22 options.OrganizationId = "org_15421144869927830" 23 24 // 3. LoginHint (lowest precedence) - Extracts domain from email to find connection 25 // Domain must be registered to the organization (manually via Dashboard or through admin portal during enterprise onboarding) 26 options.LoginHint = "user@example.com" 27 28 // redirectUrl: Your callback endpoint that receives the authorization code 29 // Must match the URL registered in your Scalekit dashboard 30 redirectUrl := "https://your-app.com/auth/callback" 31 32 authorizationURL := scalekitClient.GetAuthorizationUrl( 33 redirectUrl, 34 options, 35 ) 36 // Redirect user to this URL to begin SSO authentication 37 } ``` * Java AuthorizationUrl.java ```java 1 package com.scalekit; 2 3 import com.scalekit.ScalekitClient; 4 import com.scalekit.internal.http.AuthorizationUrlOptions; 5 6 public class Main { 7 8 public static void main(String[] args) { 9 ScalekitClient scalekitClient = new ScalekitClient( 10 "", // Your Scalekit environment URL 11 "", // Unique identifier for your app 12 "" 13 ); 14 15 AuthorizationUrlOptions options = new AuthorizationUrlOptions(); 16 17 // Specify which SSO connection to use (choose one based on your use case) 18 // These identifiers are evaluated in order of precedence: 19 20 // 1. connectionId (highest precedence) - Use when you know the exact SSO connection 21 options.setConnectionId("con_13388706786312310"); 22 23 // 2. organizationId - Routes to organization's SSO (useful for multi-tenant apps) 24 // If org has multiple connections, the first active one is selected 25 options.setOrganizationId("org_13388706786312310"); 26 27 // 3. loginHint (lowest precedence) - Extracts domain from email to find connection 28 // Domain must be registered to the organization (manually via Dashboard or through admin portal during enterprise onboarding) 29 options.setLoginHint("user@example.com"); 30 31 // redirectUrl: Your callback endpoint that receives the authorization code 32 // Must match the URL registered in your Scalekit dashboard 33 String redirectUrl = "https://your-app.com/auth/callback"; 34 35 try { 36 String url = scalekitClient 37 .authentication() 38 .getAuthorizationUrl(redirectUrl, options) 39 .toString(); 40 // Redirect user to this URL to begin SSO authentication 41 } catch (Exception e) { 42 System.out.println(e.getMessage()); 43 } 44 } 45 } ``` * Direct URL (No SDK) OAuth2 authorization URL ```sh /oauth/authorize? response_type=code& # OAuth2 authorization code flow client_id=& # Your Scalekit client ID redirect_uri=& # URL-encoded callback URL scope=openid profile email& # Note: "offline_access" scope is not supported in Modular SSO organization_id=org_15421144869927830& # (Optional) Route by organization connection_id=conn_15696105471768821& # (Optional) Specific SSO connection login_hint=user@example.com # (Optional) Extract domain from email ``` **SSO identifiers** (choose one or more, evaluated in order of precedence): * `connection_id` - Direct to specific SSO connection (highest precedence) * `organization_id` - Route to organization’s SSO * `domain_hint` - Lookup connection by domain * `login_hint` - Extract domain from email (lowest precedence). Domain must be registered to the organization (manually via Dashboard or through admin portal when [onboarding an enterprise customer](/sso/guides/onboard-enterprise-customers/)) Example with actual values ```http https://tinotat-dev.scalekit.dev/oauth/authorize? response_type=code& client_id=skc_88036702639096097& redirect_uri=http%3A%2F%2Flocalhost%3A3000%2Fauth%2Fcallback& scope=openid%20profile%20email& organization_id=org_15421144869927830 ``` Enterprise users see their identity provider’s login page. Users verify their identity through the authentication policies set by their organization’s administrator. Post successful verification, the user profile is [normalized](/sso/guides/user-profile-details/) and sent to your app. For details on how Scalekit determines which SSO connection to use, refer to the [SSO identifier precedence rules](/sso/guides/authorization-url/#parameter-precedence). 4. ## Handle IdP-initiated SSO Recommended [Section titled “Handle IdP-initiated SSO ”](#handle-idp-initiated-sso-) When users start the login process from their identity provider’s portal (rather than your application), this is called IdP-initiated SSO. Scalekit converts these requests to secure SP-initiated flows automatically. Your initiate login endpoint receives an `idp_initiated_login` JWT parameter containing the user’s organization and connection details. Decode this token and generate a new authorization URL to complete the authentication flow securely. ```sh https://yourapp.com/login?idp_initiated_login= ``` Configure your initiate login endpoint in [Dashboard > Authentication > Redirects](/guides/dashboard/redirects/#initiate-login-url) * Node.js handle-idp-initiated.js ```javascript 1 // Your initiate login endpoint receives the IdP-initiated login token 2 const { idp_initiated_login, error, error_description } = req.query; 3 4 if (error) { 5 return res.status(400).json({ message: error_description }); 6 } 7 8 // When users start login from their IdP portal, convert to SP-initiated flow 9 if (idp_initiated_login) { 10 // Decode the JWT to extract organization and connection information 11 const claims = await scalekit.getIdpInitiatedLoginClaims(idp_initiated_login); 12 13 const options = { 14 connectionId: claims.connection_id, // Specific SSO connection 15 organizationId: claims.organization_id, // User's organization 16 loginHint: claims.login_hint, // User's email for context 17 state: claims.relay_state // Preserve state from IdP 18 }; 19 20 // Generate authorization URL and redirect to complete authentication 21 const authorizationURL = scalekit.getAuthorizationUrl( 22 'https://your-app.com/auth/callback', 23 options 24 ); 25 26 return res.redirect(authorizationURL); 27 } ``` * Python handle\_idp\_initiated.py ```python 1 # Your initiate login endpoint receives the IdP-initiated login token 2 idp_initiated_login = request.args.get('idp_initiated_login') 3 error = request.args.get('error') 4 error_description = request.args.get('error_description') 5 6 if error: 7 raise Exception(error_description) 8 9 # When users start login from their IdP portal, convert to SP-initiated flow 10 if idp_initiated_login: 11 # Decode the JWT to extract organization and connection information 12 claims = await scalekit.get_idp_initiated_login_claims(idp_initiated_login) 13 14 options = AuthorizationUrlOptions() 15 options.connection_id = claims.get('connection_id') # Specific SSO connection 16 options.organization_id = claims.get('organization_id') # User's organization 17 options.login_hint = claims.get('login_hint') # User's email for context 18 options.state = claims.get('relay_state') # Preserve state from IdP 19 20 # Generate authorization URL and redirect to complete authentication 21 authorization_url = scalekit.get_authorization_url( 22 redirect_uri='https://your-app.com/auth/callback', 23 options=options 24 ) 25 26 return redirect(authorization_url) ``` * Go handle\_idp\_initiated.go ```go 1 // Your initiate login endpoint receives the IdP-initiated login token 2 idpInitiatedLogin := r.URL.Query().Get("idp_initiated_login") 3 errorDesc := r.URL.Query().Get("error_description") 4 5 if errorDesc != "" { 6 http.Error(w, errorDesc, http.StatusBadRequest) 7 return 8 } 9 10 // When users start login from their IdP portal, convert to SP-initiated flow 11 if idpInitiatedLogin != "" { 12 // Decode the JWT to extract organization and connection information 13 claims, err := scalekitClient.GetIdpInitiatedLoginClaims(r.Context(), idpInitiatedLogin) 14 if err != nil { 15 http.Error(w, err.Error(), http.StatusInternalServerError) 16 return 17 } 18 19 options := scalekit.AuthorizationUrlOptions{ 20 ConnectionId: claims.ConnectionID, // Specific SSO connection 21 OrganizationId: claims.OrganizationID, // User's organization 22 LoginHint: claims.LoginHint, // User's email for context 23 } 24 25 // Generate authorization URL and redirect to complete authentication 26 authUrl, err := scalekitClient.GetAuthorizationUrl( 27 "https://your-app.com/auth/callback", 28 options 29 ) 30 31 if err != nil { 32 http.Error(w, err.Error(), http.StatusInternalServerError) 33 return 34 } 35 36 http.Redirect(w, r, authUrl.String(), http.StatusFound) 37 } ``` * Java HandleIdpInitiated.java ```java 1 // Your initiate login endpoint receives the IdP-initiated login token 2 @GetMapping("/login") 3 public RedirectView handleInitiateLogin( 4 @RequestParam(required = false, name = "idp_initiated_login") String idpInitiatedLoginToken, 5 @RequestParam(required = false) String error, 6 @RequestParam(required = false, name = "error_description") String errorDescription, 7 HttpServletResponse response) throws IOException { 8 9 if (error != null) { 10 response.sendError(HttpStatus.BAD_REQUEST.value(), errorDescription); 11 return null; 12 } 13 14 // When users start login from their IdP portal, convert to SP-initiated flow 15 if (idpInitiatedLoginToken != null) { 16 // Decode the JWT to extract organization and connection information 17 IdpInitiatedLoginClaims claims = scalekit 18 .authentication() 19 .getIdpInitiatedLoginClaims(idpInitiatedLoginToken); 20 21 if (claims == null) { 22 response.sendError(HttpStatus.BAD_REQUEST.value(), "Invalid token"); 23 return null; 24 } 25 26 AuthorizationUrlOptions options = new AuthorizationUrlOptions(); 27 options.setConnectionId(claims.getConnectionID()); // Specific SSO connection 28 options.setOrganizationId(claims.getOrganizationID()); // User's organization 29 options.setLoginHint(claims.getLoginHint()); // User's email for context 30 31 // Generate authorization URL and redirect to complete authentication 32 String authUrl = scalekit 33 .authentication() 34 .getAuthorizationUrl("https://your-app.com/auth/callback", options) 35 .toString(); 36 37 response.sendRedirect(authUrl); 38 return null; 39 } 40 41 return null; 42 } ``` This approach provides enhanced security by converting IdP-initiated requests to standard SP-initiated flows, protecting against SAML assertion theft and replay attacks. Learn more: [IdP-initiated SSO implementation guide](/sso/guides/idp-init-sso/) 5. ## Get user details from the callback [Section titled “Get user details from the callback”](#get-user-details-from-the-callback) After successful authentication, Scalekit redirects to your callback URL with an authorization code. Your application exchanges this code for the user’s profile information and session tokens. 1. Add a callback endpoint in your application (typically `https://your-app.com/auth/callback`) 2. [Register](/guides/dashboard/redirects/#allowed-callback-urls) it in your Scalekit dashboard > Authentication > Redirect URLS > Allowed Callback URLs In authentication flow, Scalekit redirects to your callback URL with an authorization code. Your application exchanges this code for the user’s profile information. * Node.js Fetch user profile ```javascript 1 // Extract authentication parameters from the callback request 2 const { 3 code, 4 error, 5 error_description, 6 idp_initiated_login, 7 connection_id, 8 relay_state 9 } = req.query; 10 11 if (error) { 12 // Handle authentication errors returned from the identity provider 13 } 14 15 // Recommended: Process IdP-initiated login flows (when users start from their SSO portal) 16 17 const result = await scalekit.authenticateWithCode(code, redirectUri); 18 const userEmail = result.user.email; 19 20 // Create a session for the authenticated user and grant appropriate access permissions ``` * Python Fetch user profile ```py 1 # Extract authentication parameters from the callback request 2 code = request.args.get('code') 3 error = request.args.get('error') 4 error_description = request.args.get('error_description') 5 idp_initiated_login = request.args.get('idp_initiated_login') 6 connection_id = request.args.get('connection_id') 7 relay_state = request.args.get('relay_state') 8 9 if error: 10 raise Exception(error_description) 11 12 # Recommended: Process IdP-initiated login flows (when users start from their SSO portal) 13 14 result = scalekit.authenticate_with_code(code, '') 15 16 # Access normalized user profile information 17 user_email = result.user.email 18 19 # Create a session for the authenticated user and grant appropriate access permissions ``` * Go Fetch user profile ```go 1 // Extract authentication parameters from the callback request 2 code := r.URL.Query().Get("code") 3 error := r.URL.Query().Get("error") 4 errorDescription := r.URL.Query().Get("error_description") 5 idpInitiatedLogin := r.URL.Query().Get("idp_initiated_login") 6 connectionID := r.URL.Query().Get("connection_id") 7 relayState := r.URL.Query().Get("relay_state") 8 9 if error != "" { 10 // Handle authentication errors returned from the identity provider 11 } 12 13 // Recommended: Process IdP-initiated login flows (when users start from their SSO portal) 14 15 result, err := scalekitClient.AuthenticateWithCode(r.Context(), code, redirectUrl) 16 17 if err != nil { 18 // Handle token exchange or validation errors 19 } 20 21 // Access normalized user profile information 22 userEmail := result.User.Email 23 24 // Create a session for the authenticated user and grant appropriate access permissions ``` * Java Fetch user profile ```java 1 // Extract authentication parameters from the callback request 2 String code = request.getParameter("code"); 3 String error = request.getParameter("error"); 4 String errorDescription = request.getParameter("error_description"); 5 String idpInitiatedLogin = request.getParameter("idp_initiated_login"); 6 String connectionID = request.getParameter("connection_id"); 7 String relayState = request.getParameter("relay_state"); 8 9 if (error != null && !error.isEmpty()) { 10 // Handle authentication errors returned from the identity provider 11 return; 12 } 13 14 // Recommended: Process IdP-initiated login flows (when users start from their SSO portal) 15 16 try { 17 AuthenticationResponse result = scalekit.authentication().authenticateWithCode(code, redirectUrl); 18 String userEmail = result.getIdTokenClaims().getEmail(); 19 20 // Create a session for the authenticated user and grant appropriate access permissions 21 } catch (Exception e) { 22 // Handle token exchange or validation errors 23 } ``` The `result` object * Node.js Validate tokens ```js 1 // Validate and decode the ID token from the authentication result 2 const idTokenClaims = await scalekit.validateToken(result.idToken); 3 4 // Validate and decode the access token 5 const accessTokenClaims = await scalekit.validateToken(result.accessToken); ``` * Python Validate tokens ```py 1 # Validate and decode the ID token from the authentication result 2 id_token_claims = scalekit_client.validate_token(result["id_token"]) 3 4 # Validate and decode the access token 5 access_token_claims = scalekit_client.validate_token(result["access_token"]) ``` * Go Validate tokens ```go 1 // Validate and decode the access token (uses JWKS from the client) 2 accessTokenClaims, err := scalekitClient.GetAccessTokenClaims(ctx, result.AccessToken) 3 if err != nil { 4 // handle error 5 } ``` * Java Validate tokens ```java 1 // Validate and decode the ID token 2 Map idTokenClaims = scalekitClient.validateToken(result.getIdToken()); 3 4 // Validate and decode the access token 5 Map accessTokenClaims = scalekitClient.validateToken(result.getAccessToken()); ``` - Auth result ```js 1 { 2 user: { 3 email: 'john@example.com', 4 familyName: 'Doe', 5 givenName: 'John', 6 username: 'john@example.com', 7 id: 'conn_70087756662964366;dcc62570-6a5a-4819-b11b-d33d110c7716' 8 }, 9 idToken: 'eyJhbGciOiJSU..bcLQ', 10 accessToken: 'eyJhbGciO..', 11 expiresIn: 899 12 } ``` - ID token (decoded) ```js 1 { 2 amr: [ 'conn_70087756662964366' ], // SSO connection ID 3 at_hash: 'yMGIBg7BkmIGgD6_dZPEGQ', 4 aud: [ 'skc_70087756327420046' ], 5 azp: 'skc_70087756327420046', 6 c_hash: '4x7qsXnlRw6dRC6twnuENw', 7 client_id: 'skc_70087756327420046', 8 email: 'john@example.com', 9 exp: 1758952038, 10 family_name: 'Doe', 11 given_name: 'John', 12 iat: 1758692838, 13 iss: '', 14 oid: 'org_70087756646187150', 15 preferred_username: 'john@example.com', 16 sid: 'ses_91646612652163629', 17 sub: 'conn_70087756662964366;e964d135-35c7-4a13-a3b4-2579a1cdf4e6' 18 } ``` - Access token (decoded) ```js 1 { 2 "iss": "", 3 "sub": "conn_70087756662964366;dcc62570-6a5a-4819-b11b-d33d110c7716", 4 "aud": [ 5 "skc_70087756327420046" 6 ], 7 "exp": 1758693916, 8 "iat": 1758693016, 9 "nbf": 1758693016, 10 "client_id": "skc_70087756327420046", 11 "jti": "tkn_91646913048216109" 12 } ``` 6. ## Test your SSO integration [Section titled “Test your SSO integration”](#test-your-sso-integration) Validate your implementation using the **IdP Simulator** and **Test Organization** included in your development environment. Test all three scenarios before deploying to production. Your environment includes a pre-configured test organization (found in **Dashboard > Organizations**) with domains like `@example.com` and `@example.org` for testing. Pass one of the following connection selectors in your authorization URL: * Email address with `@example.com` or `@example.org` domain * Test organization’s connection ID * Organization ID This opens the SSO login page (IdP Simulator) that simulates your customer’s identity provider login experience. ![IdP Simulator](/.netlify/images?url=_astro%2F2.1.BEM1Vo-J.png\&w=2646\&h=1652\&dpl=6a01bf5aba8408000850fe26) For detailed testing instructions and scenarios, see our [Complete SSO testing guide](/sso/guides/test-sso/) 7. ## Set up SSO with your existing authentication system [Section titled “Set up SSO with your existing authentication system”](#set-up-sso-with-your-existing-authentication-system) Many applications already use an authentication provider such as Auth0, Firebase, or AWS Cognito. To enable single sign-on (SSO) using Scalekit, configure Scalekit to work with your current authentication provider. ### Auth0 Integrate Scalekit with Auth0 for enterprise SSO [Know more →](/guides/integrations/auth-systems/auth0) ### Firebase Auth Add enterprise authentication to Firebase projects [Know more →](/guides/integrations/auth-systems/firebase) ### AWS Cognito Configure Scalekit with AWS Cognito user pools [Know more →](/guides/integrations/auth-systems/aws-cognito) 8. ## Onboard enterprise customers [Section titled “Onboard enterprise customers”](#onboard-enterprise-customers) Enable SSO for your enterprise customers by creating an organization in Scalekit and providing them access to the Admin Portal. Your customers configure their identity provider settings themselves through a self-service portal. **Create an organization** for your customer in [Dashboard > Organizations](https://app.scalekit.com/organizations), then provide Admin Portal access using one of these methods: * Shareable link Generate a secure link your customer can use to access the Admin Portal: generate-portal-link.js ```javascript // Generate a one-time Admin Portal link for your customer const portalLink = await scalekit.organization.generatePortalLink( 'org_32656XXXXXX0438' // Your customer's organization ID ); // Share this link with your customer's IT admin via email or messaging // Example: '/magicLink/8930509d-68cf-4e2c-8c6d-94d2b5e2db43 console.log('Admin Portal URL:', portalLink.location); ``` Send this link to your customer’s IT administrator through email, Slack, or your preferred communication channel. They can configure their SSO connection without any developer involvement. * Embedded portal Embed the Admin Portal directly in your application using an iframe: embed-portal.js ```javascript // Generate a secure portal link at runtime const portalLink = await scalekit.organization.generatePortalLink(orgId); // Return the link to your frontend to embed in an iframe res.json({ portalUrl: portalLink.location }); ``` admin-settings.html ```html ``` Customers configure SSO without leaving your application, maintaining a consistent user experience. Listen for UI events from the embedded portal to respond to configuration changes, such as when SSO is enabled or the session expires. See the [Admin portal UI events reference](/reference/admin-portal/ui-events/) for details on handling these events. Learn more: [Embedded Admin Portal guide](/guides/admin-portal/#embed-the-admin-portal) **Enable domain verification** for seamless user experience. Once your customer verifies their domain (e.g., `@megacorp.org`), users can sign in without selecting their organization. Scalekit automatically routes them to the correct identity provider based on their email domain. **Pre-check SSO availability** before redirecting users. This prevents failed redirects when a user’s domain doesn’t have SSO configured: * Node.js check-sso-availability.js ```javascript 1 // Extract domain from user's email address 2 const domain = email.split('@')[1].toLowerCase(); // e.g., "megacorp.org" 3 4 // Check if domain has an active SSO connection 5 const connections = await scalekit.connections.listConnectionsByDomain({ 6 domain 7 }); 8 9 if (connections.length > 0) { 10 // Domain has SSO configured - redirect to identity provider 11 const authUrl = scalekit.getAuthorizationUrl(redirectUri, { 12 domainHint: domain // Automatically routes to correct IdP 13 }); 14 return res.redirect(authUrl); 15 } else { 16 // No SSO for this domain - show alternative login methods 17 return showPasswordlessLogin(); 18 } ``` * Python check\_sso\_availability.py ```python 1 # Extract domain from user's email address 2 domain = email.split('@')[1].lower() # e.g., "megacorp.org" 3 4 # Check if domain has an active SSO connection 5 connections = scalekit_client.connections.list_connections_by_domain( 6 domain=domain 7 ) 8 9 if len(connections) > 0: 10 # Domain has SSO configured - redirect to identity provider 11 options = AuthorizationUrlOptions() 12 options.domain_hint = domain # Automatically routes to correct IdP 13 14 auth_url = scalekit_client.get_authorization_url( 15 redirect_uri=redirect_uri, 16 options=options 17 ) 18 return redirect(auth_url) 19 else: 20 # No SSO for this domain - show alternative login methods 21 return show_passwordless_login() ``` * Go check\_sso\_availability.go ```go 1 // Extract domain from user's email address 2 parts := strings.Split(email, "@") 3 domain := strings.ToLower(parts[1]) // e.g., "megacorp.org" 4 5 // Check if domain has an active SSO connection 6 connections, err := scalekitClient.Connections.ListConnectionsByDomain(domain) 7 if err != nil { 8 // Handle error 9 return err 10 } 11 12 if len(connections) > 0 { 13 // Domain has SSO configured - redirect to identity provider 14 options := scalekit.AuthorizationUrlOptions{ 15 DomainHint: domain, // Automatically routes to correct IdP 16 } 17 18 authUrl, err := scalekitClient.GetAuthorizationUrl(redirectUri, options) 19 if err != nil { 20 return err 21 } 22 23 c.Redirect(http.StatusFound, authUrl.String()) 24 } else { 25 // No SSO for this domain - show alternative login methods 26 return showPasswordlessLogin() 27 } ``` * Java CheckSsoAvailability.java ```java 1 // Extract domain from user's email address 2 String[] parts = email.split("@"); 3 String domain = parts[1].toLowerCase(); // e.g., "megacorp.org" 4 5 // Check if domain has an active SSO connection 6 List connections = scalekitClient 7 .connections() 8 .listConnectionsByDomain(domain); 9 10 if (connections.size() > 0) { 11 // Domain has SSO configured - redirect to identity provider 12 AuthorizationUrlOptions options = new AuthorizationUrlOptions(); 13 options.setDomainHint(domain); // Automatically routes to correct IdP 14 15 String authUrl = scalekitClient 16 .authentication() 17 .getAuthorizationUrl(redirectUri, options) 18 .toString(); 19 20 return new RedirectView(authUrl); 21 } else { 22 // No SSO for this domain - show alternative login methods 23 return showPasswordlessLogin(); 24 } ``` This check ensures users only see SSO options when available, improving the login experience and reducing confusion. --- # DOCUMENT BOUNDARY --- # Admin portal > Implement Scalekit's self-serve admin portal to let customers configure SSO via a shareable link or embedded iframe The admin portal provides a self-serve interface for customers to configure single sign-on (SSO) and directory sync (SCIM) connections. Scalekit hosts the portal and provides two integration methods: generate a shareable link through the dashboard or programmatically embed the portal in your application using an iframe. This guide shows you how to implement both integration methods. For the broader customer onboarding workflow, see [Onboard enterprise customers](/sso/guides/onboard-enterprise-customers/). ## Generate shareable portal link No-code Generate a shareable link through the Scalekit dashboard to give customers access to the admin portal. This method requires no code and is ideal for quick setup. ### Create the portal link 1. Log in to the [Scalekit dashboard](https://app.scalekit.com) 2. Navigate to **Dashboard > Organizations** 3. Select the target organization 4. Click **Generate link** to create a shareable admin portal link The generated link follows this format: Portal link example ```http https://your-app.scalekit.dev/magicLink/2cbe56de-eec4-41d2-abed-90a5b82286c4_p ``` ### Link properties | Property | Details | | -------------- | ------------------------------------------------------------------------------- | | **Expiration** | Links expire after 7 days | | **Revocation** | Revoke links anytime from the dashboard | | **Sharing** | Share via email, Slack, or any preferred channel | | **Security** | Anyone with the link can view and update the organization’s connection settings | Security consideration Treat portal links as sensitive credentials. Anyone with the link can view and modify the organization’s SSO and SCIM configuration. ## Embed the admin portal Programmatic Embed the admin portal directly in your application using an iframe. This allows customers to configure SSO and SCIM without leaving your app, creating a seamless experience within your settings or admin interface. The portal link must be generated programmatically on each page load for security. Each generated link is single-use and expires after 1 minute, though once loaded, the session remains active for up to 6 hours. * Node.js ```bash npm install @scalekit-sdk/node ``` * Python ```sh pip install scalekit-sdk-python ``` * Go ```sh go get -u github.com/scalekit-inc/scalekit-sdk-go ``` * Java ```groovy /* Gradle users - add the following to your dependencies in build file */ implementation "com.scalekit:scalekit-sdk-java:2.0.11" ``` ```xml com.scalekit scalekit-sdk-java 2.0.11 ``` ### Generate portal link Use the Scalekit SDK to generate a unique, embeddable admin portal link for an organization. Call this API endpoint each time you render the page containing the iframe. * Node.js Express.js ```javascript 1 import { Scalekit } from '@scalekit-sdk/node'; 2 3 const scalekit = new Scalekit( 4 process.env.SCALEKIT_ENVIRONMENT_URL, 5 process.env.SCALEKIT_CLIENT_ID, 6 process.env.SCALEKIT_CLIENT_SECRET, 7 ); 8 9 async function generatePortalLink(organizationId) { 10 const link = await scalekit.organization.generatePortalLink(organizationId); 11 return link.location; // Use as iframe src 12 } ``` * Python Flask ```python 1 from scalekit import Scalekit 2 import os 3 4 scalekit_client = Scalekit( 5 environment_url=os.environ.get("SCALEKIT_ENVIRONMENT_URL"), 6 client_id=os.environ.get("SCALEKIT_CLIENT_ID"), 7 client_secret=os.environ.get("SCALEKIT_CLIENT_SECRET") 8 ) 9 10 def generate_portal_link(organization_id): 11 link = scalekit_client.organization.generate_portal_link(organization_id) 12 return link.location # Use as iframe src ``` * Go Gin ```go 1 import ( 2 "context" 3 "os" 4 5 "github.com/scalekit/sdk-go" 6 ) 7 8 scalekitClient := scalekit.New( 9 os.Getenv("SCALEKIT_ENVIRONMENT_URL"), 10 os.Getenv("SCALEKIT_CLIENT_ID"), 11 os.Getenv("SCALEKIT_CLIENT_SECRET"), 12 ) 13 14 func generatePortalLink(organizationID string) (string, error) { 15 ctx := context.Background() 16 link, err := scalekitClient.Organization().GeneratePortalLink(ctx, organizationID) 17 if err != nil { 18 return "", err 19 } 20 return link.Location, nil // Use as iframe src 21 } ``` * Java Spring Boot ```java 1 import com.scalekit.client.Scalekit; 2 import com.scalekit.client.models.Link; 3 import com.scalekit.client.models.Feature; 4 import java.util.Arrays; 5 6 Scalekit scalekitClient = new Scalekit( 7 System.getenv("SCALEKIT_ENVIRONMENT_URL"), 8 System.getenv("SCALEKIT_CLIENT_ID"), 9 System.getenv("SCALEKIT_CLIENT_SECRET") 10 ); 11 12 public String generatePortalLink(String organizationId) { 13 Link portalLink = scalekitClient.organizations() 14 .generatePortalLink(organizationId, Arrays.asList(Feature.sso, Feature.dir_sync)); 15 return portalLink.getLocation(); // Use as iframe src 16 } ``` The API returns a JSON object with the portal link. Use the `location` property as the iframe `src`: API response ```json { "id": "8930509d-68cf-4e2c-8c6d-94d2b5e2db43", "location": "https://random-subdomain.scalekit.dev/magicLink/8930509d-68cf-4e2c-8c6d-94d2b5e2db43", "expireTime": "2024-10-03T13:35:50.563013Z" } ``` Embed portal in iframe ```html ``` Embed the portal in your application’s settings or admin section where customers manage authentication configuration. ### Configuration and session | Setting | Requirement | | --------------------- | ----------------------------------------------------------------------------- | | **Redirect URI** | Add your application domain at **Dashboard > Developers > API Configuration** | | **iframe attributes** | Include `allow="clipboard-write"` for copy-paste functionality | | **Dimensions** | Minimum recommended height: 600px | | **Link expiration** | Generated links expire after 1 minute if not loaded | | **Session duration** | Portal session remains active for up to 6 hours once loaded | | **Single-use** | Each generated link can only be used once to initialize a session | ## Customize the admin portal Match the admin portal to your brand identity. Configure branding at **Dashboard > Settings > Branding**: | Option | Description | | ---------------- | --------------------------------------------------------- | | **Logo** | Upload your company logo (displayed in the portal header) | | **Accent color** | Set the primary color to match your brand palette | | **Favicon** | Provide a custom favicon for browser tabs | For additional customization options including custom domains, see the [Custom domain guide](/guides/custom-domain/). [SSO integrations ](/guides/integrations/sso-integrations/)Administrator guides to set up SSO integrations [Portal events ](/reference/admin-portal/ui-events/)Listen to the browser events emitted from the embedded admin portal --- # DOCUMENT BOUNDARY --- # Code samples > Code samples demonstrating Single Sign-On implementations with Express.js, .NET Core, Firebase, AWS Cognito, and Next.js ### [Add SSO to Express.js apps](https://github.com/scalekit-inc/nodejs-example-apps/tree/main/sso-express-example) [Implement Scalekit SSO in a Node.js Express application. Includes middleware setup for secure session handling](https://github.com/scalekit-inc/nodejs-example-apps/tree/main/sso-express-example) ### [Add SSO to .NET Core apps](https://github.com/scalekit-inc/dotnet-example-apps) [Secure .NET Core applications with Scalekit SSO. Demonstrates authentication pipelines and user claims management](https://github.com/scalekit-inc/dotnet-example-apps) ### [Add SSO to Spring Boot apps](https://github.com/scalekit-developers/scalekit-springboot-example) [Integrate Scalekit SSO with Spring Security. Shows how to configure security filters and protect Java endpoints](https://github.com/scalekit-developers/scalekit-springboot-example) ### [Add SSO to Python FastAPI](https://github.com/scalekit-developers/scalekit-fastapi-example) [Add enterprise SSO to FastAPI services using Scalekit. Includes async route protection and user session validation](https://github.com/scalekit-developers/scalekit-fastapi-example) ### [Add SSO to Go applications](https://github.com/scalekit-developers/scalekit-go-example) [Implement Scalekit SSO in Go. Features idiomatically written middleware for securing HTTP handlers](https://github.com/scalekit-developers/scalekit-go-example) ### [Add SSO to Next.js apps](https://github.com/scalekit-developers/scalekit-nextjs-demo) [Secure Next.js applications with Scalekit. Covers both App Router and Pages Router authentication patterns](https://github.com/scalekit-developers/scalekit-nextjs-demo) ### Scalekit SSO + Your own auth system ### [Connect Firebase Auth with SSO](https://github.com/scalekit-inc/scalekit-firebase-sso) [Enable Enterprise SSO for Firebase apps using Scalekit. Learn to link Scalekit identities with Firebase Authentication](https://github.com/scalekit-inc/scalekit-firebase-sso) ### [Connect AWS Cognito with SSO](https://github.com/scalekit-inc/scalekit-cognito-sso) [Add Enterprise SSO to Cognito user pools via Scalekit. Step-by-step guide to federating identity providers](https://github.com/scalekit-inc/scalekit-cognito-sso) ### [Cognito + Scalekit for Next.js](https://github.com/scalekit-inc/nextjs-example-apps/tree/main/cognito-scalekit) [Integrate Cognito and Scalekit SSO in Next.js. Uses OIDC protocols to secure your full-stack React application](https://github.com/scalekit-inc/nextjs-example-apps/tree/main/cognito-scalekit) ## Admin portal ### [Embed admin portal](https://github.com/scalekit-inc/nodejs-example-apps/tree/main/embed-admin-portal-sample) [Embed the Scalekit Admin Portal into your app via **iframe**. Node.js example for generating secure admin sessions](https://github.com/scalekit-inc/nodejs-example-apps/tree/main/embed-admin-portal-sample) --- # DOCUMENT BOUNDARY --- # Pre-check SSO by domain > Validate that a user's email domain has an active SSO connection before redirecting to prevent dead-end redirects and improve user experience. When using discovery through `loginHint`, validate that the user’s email domain has an active SSO connection before redirecting. This prevents dead-end redirects and improves user experience by routing users to the correct authentication path. ## When to use domain pre-checking [Section titled “When to use domain pre-checking”](#when-to-use-domain-pre-checking) Use domain pre-checking when: * You implement identifier-driven or SSO button flows that collect email first * You infer SSO availability from the user’s email domain * You want to show helpful error messages for domains without SSO Skip this check when: * You already pass `organizationId` explicitly (you know the organization) * You implement organization-specific pages where SSO is always available ## Implementation workflow [Section titled “Implementation workflow”](#implementation-workflow) 1. ## Capture the user’s email and extract the domain [Section titled “Capture the user’s email and extract the domain”](#capture-the-users-email-and-extract-the-domain) First, collect the user’s email address through your login form. Login form handler ```javascript 1 // Extract domain from user's email 2 const email = req.body.email; 3 const domain = email.split('@')[1]; // e.g., "acmecorp.com" ``` 2. ## Query for SSO connections by domain [Section titled “Query for SSO connections by domain”](#query-for-sso-connections-by-domain) Use the Scalekit API to check if the domain has an active SSO connection configured. * Node.js Express.js ```javascript 1 // Use case: Check if user's domain has SSO before redirecting 2 app.post('/auth/check-sso', async (req, res) => { 3 const { email } = req.body; 4 const domain = email.split('@')[1]; 5 6 try { 7 // Query Scalekit for connections matching this domain 8 const connections = await scalekit.connection.listConnections({ 9 domain: domain 10 }); 11 12 if (connections.length > 0) { 13 // Domain has active SSO - redirect to SSO login 14 const authorizationURL = scalekit.getAuthorizationUrl( 15 process.env.REDIRECT_URI, 16 { loginHint: email } 17 ); 18 res.json({ ssoAvailable: true, redirectUrl: authorizationURL }); 19 } else { 20 // No SSO configured - route to password or social login 21 res.json({ ssoAvailable: false, message: 'Please use password login' }); 22 } 23 } catch (error) { 24 console.error('Failed to check SSO availability:', error); 25 res.status(500).json({ error: 'sso_check_failed' }); 26 } 27 }); ``` * Python Flask ```python 1 # Use case: Check if user's domain has SSO before redirecting 2 @app.route('/auth/check-sso', methods=['POST']) 3 def check_sso(): 4 data = request.get_json() 5 email = data.get('email') 6 domain = email.split('@')[1] 7 8 try: 9 # Query Scalekit for connections matching this domain 10 connections = scalekit_client.connection.list_connections( 11 domain=domain 12 ) 13 14 if len(connections) > 0: 15 # Domain has active SSO - redirect to SSO login 16 authorization_url = scalekit_client.get_authorization_url( 17 redirect_uri=os.getenv("REDIRECT_URI"), 18 options=AuthorizationUrlOptions(login_hint=email) 19 ) 20 return jsonify({ 21 'ssoAvailable': True, 22 'redirectUrl': authorization_url 23 }) 24 else: 25 # No SSO configured - route to password or social login 26 return jsonify({ 27 'ssoAvailable': False, 28 'message': 'Please use password login' 29 }) 30 except Exception as error: 31 print(f"Failed to check SSO availability: {error}") 32 return jsonify({'error': 'sso_check_failed'}), 500 ``` * Go Gin ```go 1 // Use case: Check if user's domain has SSO before redirecting 2 func checkSSOHandler(c *gin.Context) { 3 var body struct { 4 Email string `json:"email"` 5 } 6 c.BindJSON(&body) 7 8 domain := strings.Split(body.Email, "@")[1] 9 10 // Query Scalekit for connections matching this domain 11 connections, err := scalekitClient.Connection.ListConnections( 12 &scalekit.ListConnectionsOptions{ 13 Domain: domain, 14 }, 15 ) 16 17 if err != nil { 18 log.Printf("Failed to check SSO availability: %v", err) 19 c.JSON(http.StatusInternalServerError, gin.H{"error": "sso_check_failed"}) 20 return 21 } 22 23 if len(connections) > 0 { 24 // Domain has active SSO - redirect to SSO login 25 authorizationURL, _ := scalekitClient.GetAuthorizationUrl( 26 os.Getenv("REDIRECT_URI"), 27 scalekit.AuthorizationUrlOptions{ 28 LoginHint: body.Email, 29 }, 30 ) 31 c.JSON(http.StatusOK, gin.H{ 32 "ssoAvailable": true, 33 "redirectUrl": authorizationURL, 34 }) 35 } else { 36 // No SSO configured - route to password or social login 37 c.JSON(http.StatusOK, gin.H{ 38 "ssoAvailable": false, 39 "message": "Please use password login", 40 }) 41 } 42 } ``` * Java Spring Boot ```java 1 // Use case: Check if user's domain has SSO before redirecting 2 @PostMapping(path = "/auth/check-sso") 3 public ResponseEntity> checkSSOHandler(@RequestBody CheckSSORequest body) { 4 String email = body.getEmail(); 5 String domain = email.split("@")[1]; 6 7 try { 8 // Query Scalekit for connections matching this domain 9 ListConnectionsResponse connections = scalekitClient 10 .connection() 11 .listConnections( 12 new ListConnectionsOptions().setDomain(domain) 13 ); 14 15 if (!connections.getConnections().isEmpty()) { 16 // Domain has active SSO - redirect to SSO login 17 String authorizationURL = scalekitClient 18 .authentication() 19 .getAuthorizationUrl( 20 System.getenv("REDIRECT_URI"), 21 new AuthorizationUrlOptions().setLoginHint(email) 22 ) 23 .toString(); 24 25 Map response = new HashMap<>(); 26 response.put("ssoAvailable", true); 27 response.put("redirectUrl", authorizationURL); 28 return ResponseEntity.ok(response); 29 } else { 30 // No SSO configured - route to password or social login 31 Map response = new HashMap<>(); 32 response.put("ssoAvailable", false); 33 response.put("message", "Please use password login"); 34 return ResponseEntity.ok(response); 35 } 36 } catch (Exception error) { 37 System.err.println("Failed to check SSO availability: " + error.getMessage()); 38 return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR) 39 .body(Collections.singletonMap("error", "sso_check_failed")); 40 } 41 } ``` 3. ## Route users based on SSO availability [Section titled “Route users based on SSO availability”](#route-users-based-on-sso-availability) Based on the API response, either redirect to SSO or show alternative authentication options. Client-side routing ```javascript 1 // Handle the response from your backend 2 const response = await fetch('/auth/check-sso', { 3 method: 'POST', 4 headers: { 'Content-Type': 'application/json' }, 5 body: JSON.stringify({ email: userEmail }) 6 }); 7 8 const data = await response.json(); 9 10 if (data.ssoAvailable) { 11 // Redirect to SSO login 12 window.location.href = data.redirectUrl; 13 } else { 14 // Show password login or social authentication options 15 showPasswordLoginForm(); 16 } ``` --- # DOCUMENT BOUNDARY --- # Link to billing, CRM & HR systems > Production-ready patterns for linking Scalekit organizations and users to Stripe, Salesforce, Workday and other enterprise systems using external identifiers External identifiers enable seamless integration between Scalekit and your existing business systems. This guide provides practical patterns for implementing these integrations across common enterprise scenarios including billing platforms, CRM systems, HR systems, and multi-system workflows. ## Integration patterns overview [Section titled “Integration patterns overview”](#integration-patterns-overview) External IDs serve as the bridge between Scalekit’s authentication system and your business infrastructure. Common integration scenarios include: * **Billing and subscription management** - Link customers to payment platforms like Stripe, Chargebee * **Customer relationship management** - Sync with Salesforce, HubSpot, Pipedrive * **Human resources systems** - Connect with Workday, BambooHR, ADP * **Internal tools and databases** - Maintain consistency across custom applications * **Multi-system orchestration** - Coordinate data across multiple platforms ## Billing system integration [Section titled “Billing system integration”](#billing-system-integration) Connect organizations and users with your billing platform to track subscriptions, handle payment events, and maintain customer lifecycle data. ### Stripe integration example [Section titled “Stripe integration example”](#stripe-integration-example) This example shows how to handle subscription updates by finding organizations using external IDs and updating their metadata accordingly. * Node.js Stripe webhook handler ```javascript 1 // When a customer subscribes via Stripe 2 app.post('/stripe/webhook', async (req, res) => { 3 const event = req.body; 4 5 if (event.type === 'customer.subscription.updated') { 6 const customerId = event.data.object.customer; 7 8 // Find organization by external ID (Stripe customer ID) 9 const org = await scalekit.organization.getByExternalId(customerId); 10 11 if (org) { 12 // Update subscription metadata 13 await scalekit.organization.update(org.id, { 14 metadata: { 15 ...org.metadata, 16 subscription_status: event.data.object.status, 17 plan_type: event.data.object.items.data[0].price.lookup_key, 18 last_billing_update: new Date().toISOString(), 19 subscription_current_period_end: new Date(event.data.object.current_period_end * 1000).toISOString() 20 } 21 }); 22 23 // Use case: Automatically provision/deprovision features based on subscription status 24 if (event.data.object.status === 'active') { 25 await enablePremiumFeatures(org.id); 26 } else if (event.data.object.status === 'canceled') { 27 await disablePremiumFeatures(org.id); 28 } 29 } 30 } 31 32 // Handle customer deletion 33 if (event.type === 'customer.deleted') { 34 const customerId = event.data.object.id; 35 const org = await scalekit.organization.getByExternalId(customerId); 36 37 if (org) { 38 await scalekit.organization.update(org.id, { 39 metadata: { 40 ...org.metadata, 41 billing_status: 'deleted', 42 deletion_date: new Date().toISOString() 43 } 44 }); 45 } 46 } 47 48 res.status(200).send('OK'); 49 }); ``` * Python Stripe webhook handler ```python 1 # When a customer subscribes via Stripe 2 @app.route('/stripe/webhook', methods=['POST']) 3 def stripe_webhook(): 4 event = request.json 5 6 if event['type'] == 'customer.subscription.updated': 7 customer_id = event['data']['object']['customer'] 8 9 # Find organization by external ID (Stripe customer ID) 10 org = scalekit.organization.get_by_external_id(customer_id) 11 12 if org: 13 # Update subscription metadata 14 updated_metadata = { 15 **org.metadata, 16 'subscription_status': event['data']['object']['status'], 17 'plan_type': event['data']['object']['items']['data'][0]['price']['lookup_key'], 18 'last_billing_update': datetime.utcnow().isoformat(), 19 'subscription_current_period_end': datetime.fromtimestamp( 20 event['data']['object']['current_period_end'] 21 ).isoformat() 22 } 23 24 scalekit.organization.update(org.id, {'metadata': updated_metadata}) 25 26 # Use case: Automatically provision/deprovision features based on subscription status 27 if event['data']['object']['status'] == 'active': 28 enable_premium_features(org.id) 29 elif event['data']['object']['status'] == 'canceled': 30 disable_premium_features(org.id) 31 32 # Handle customer deletion 33 elif event['type'] == 'customer.deleted': 34 customer_id = event['data']['object']['id'] 35 org = scalekit.organization.get_by_external_id(customer_id) 36 37 if org: 38 updated_metadata = { 39 **org.metadata, 40 'billing_status': 'deleted', 41 'deletion_date': datetime.utcnow().isoformat() 42 } 43 scalekit.organization.update(org.id, {'metadata': updated_metadata}) 44 45 return 'OK', 200 ``` ### Best practices for billing integration [Section titled “Best practices for billing integration”](#best-practices-for-billing-integration) * **Use Stripe customer IDs as external IDs** for organizations to enable quick lookups during webhook processing * **Store subscription metadata** in organization records for immediate access in your application * **Handle subscription lifecycle events** (trial start, subscription active, canceled, past due) * **Implement idempotency** in webhook handlers to prevent duplicate processing * **Use external IDs for user-level billing** when implementing per-seat pricing models ## CRM synchronization [Section titled “CRM synchronization”](#crm-synchronization) Keep organization and user data synchronized between Scalekit and your CRM system to maintain consistent customer records and enable sales team workflows. ### Salesforce integration example [Section titled “Salesforce integration example”](#salesforce-integration-example) * Node.js Salesforce sync integration ```javascript 1 // Sync organization data with Salesforce 2 async function syncOrganizationWithCRM(organizationId, salesforceAccountId) { 3 try { 4 // Fetch account data from Salesforce 5 const crmData = await salesforce.getAccount(salesforceAccountId); 6 7 // Update Scalekit organization with CRM data 8 await scalekit.organization.update(organizationId, { 9 metadata: { 10 salesforce_account_id: salesforceAccountId, 11 industry: crmData.Industry, 12 annual_revenue: crmData.AnnualRevenue, 13 account_owner: crmData.Owner.Name, 14 account_type: crmData.Type, 15 company_size: crmData.NumberOfEmployees, 16 last_crm_sync: new Date().toISOString(), 17 crm_last_modified: crmData.LastModifiedDate 18 } 19 }); 20 21 // Use case: Update user permissions based on account type 22 if (crmData.Type === 'Enterprise') { 23 await enableEnterpriseFeatures(organizationId); 24 } 25 26 } catch (error) { 27 console.error('CRM sync failed:', error); 28 // Log sync failure for monitoring 29 await logSyncFailure('salesforce', organizationId, error); 30 } 31 } 32 33 // Sync user data with Salesforce contacts 34 async function syncUserWithCRM(userId, organizationId, salesforceContactId) { 35 try { 36 const contactData = await salesforce.getContact(salesforceContactId); 37 38 await scalekit.user.updateUser(userId, { 39 metadata: { 40 salesforce_contact_id: salesforceContactId, 41 job_title: contactData.Title, 42 department: contactData.Department, 43 territory: contactData.Sales_Territory__c, 44 last_crm_contact_sync: new Date().toISOString() 45 } 46 }); 47 48 } catch (error) { 49 console.error('User CRM sync failed:', error); 50 } 51 } 52 53 // Bidirectional sync: Update Salesforce when Scalekit data changes 54 async function updateCRMFromScalekit(organizationId) { 55 const org = await scalekit.organization.getById(organizationId); 56 57 if (org.metadata.salesforce_account_id) { 58 await salesforce.updateAccount(org.metadata.salesforce_account_id, { 59 Last_Login_Date__c: new Date().toISOString(), 60 Active_Users__c: await getUserCount(organizationId), 61 Subscription_Status__c: org.metadata.plan_type 62 }); 63 } 64 } ``` * Python Salesforce sync integration ```python 1 # Sync organization data with Salesforce 2 async def sync_organization_with_crm(organization_id, salesforce_account_id): 3 try: 4 # Fetch account data from Salesforce 5 crm_data = await salesforce.get_account(salesforce_account_id) 6 7 # Update Scalekit organization with CRM data 8 metadata = { 9 'salesforce_account_id': salesforce_account_id, 10 'industry': crm_data.get('Industry'), 11 'annual_revenue': crm_data.get('AnnualRevenue'), 12 'account_owner': crm_data.get('Owner', {}).get('Name'), 13 'account_type': crm_data.get('Type'), 14 'company_size': crm_data.get('NumberOfEmployees'), 15 'last_crm_sync': datetime.utcnow().isoformat(), 16 'crm_last_modified': crm_data.get('LastModifiedDate') 17 } 18 19 scalekit.organization.update(organization_id, {'metadata': metadata}) 20 21 # Use case: Update user permissions based on account type 22 if crm_data.get('Type') == 'Enterprise': 23 await enable_enterprise_features(organization_id) 24 25 except Exception as error: 26 print(f'CRM sync failed: {error}') 27 # Log sync failure for monitoring 28 await log_sync_failure('salesforce', organization_id, str(error)) 29 30 # Sync user data with Salesforce contacts 31 async def sync_user_with_crm(user_id, organization_id, salesforce_contact_id): 32 try: 33 contact_data = await salesforce.get_contact(salesforce_contact_id) 34 35 metadata = { 36 'salesforce_contact_id': salesforce_contact_id, 37 'job_title': contact_data.get('Title'), 38 'department': contact_data.get('Department'), 39 'territory': contact_data.get('Sales_Territory__c'), 40 'last_crm_contact_sync': datetime.utcnow().isoformat() 41 } 42 43 scalekit.user.update_user(user_id, {'metadata': metadata}) 44 45 except Exception as error: 46 print(f'User CRM sync failed: {error}') 47 48 # Bidirectional sync: Update Salesforce when Scalekit data changes 49 async def update_crm_from_scalekit(organization_id): 50 org = scalekit.organization.get_by_id(organization_id) 51 52 if org.metadata.get('salesforce_account_id'): 53 await salesforce.update_account(org.metadata['salesforce_account_id'], { 54 'Last_Login_Date__c': datetime.utcnow().isoformat(), 55 'Active_Users__c': await get_user_count(organization_id), 56 'Subscription_Status__c': org.metadata.get('plan_type') 57 }) ``` ### CRM integration best practices [Section titled “CRM integration best practices”](#crm-integration-best-practices) * **Use CRM record IDs as external IDs** to enable quick bidirectional lookups * **Implement scheduled sync jobs** to keep data fresh without overloading APIs * **Handle API rate limits** with exponential backoff and queuing * **Store sync timestamps** to enable incremental updates * **Log sync failures** for monitoring and debugging * **Implement conflict resolution** for bidirectional sync scenarios ## HR system integration [Section titled “HR system integration”](#hr-system-integration) Connect user records with HR systems to automate provisioning, maintain employee data, and handle organizational changes. ### Workday integration pattern [Section titled “Workday integration pattern”](#workday-integration-pattern) HR system integration example ```javascript 1 // Sync user data with HR system during onboarding 2 async function syncNewEmployeeWithScalekit(employeeData) { 3 const { employee_id, email, first_name, last_name, department, start_date, manager_email } = employeeData; 4 5 // Find organization by domain or external ID 6 const domain = email.split('@')[1]; 7 const organization = await scalekit.organization.getByDomain(domain); 8 9 if (organization) { 10 // Create user with HR system external ID 11 const { user } = await scalekit.user.createUserAndMembership(organization.id, { 12 email: email, 13 externalId: employee_id, // HR system employee ID 14 metadata: { 15 hr_employee_id: employee_id, 16 department: department, 17 start_date: start_date, 18 manager_email: manager_email, 19 employee_status: 'active', 20 hr_last_sync: new Date().toISOString() 21 }, 22 userProfile: { 23 firstName: first_name, 24 lastName: last_name 25 }, 26 sendInvitationEmail: true 27 }); 28 29 // Use case: Assign department-based roles 30 await assignDepartmentRoles(user.id, department); 31 32 return user; 33 } 34 } 35 36 // Handle employee status changes 37 async function handleEmployeeStatusChange(employee_id, status) { 38 try { 39 // Find user by HR system external ID 40 const user = await scalekit.user.getUserByExternalId(organization.id, employee_id); 41 42 if (user) { 43 if (status === 'terminated') { 44 // Disable user access 45 await scalekit.user.updateUser(user.id, { 46 metadata: { 47 ...user.metadata, 48 employee_status: 'terminated', 49 termination_date: new Date().toISOString() 50 } 51 }); 52 53 // Remove from organization 54 await scalekit.user.removeMembership(user.id, organization.id); 55 56 } else if (status === 'on_leave') { 57 // Temporarily suspend access 58 await scalekit.user.updateUser(user.id, { 59 metadata: { 60 ...user.metadata, 61 employee_status: 'on_leave', 62 leave_start_date: new Date().toISOString() 63 } 64 }); 65 } 66 } 67 } catch (error) { 68 console.error('HR status sync failed:', error); 69 } 70 } ``` ## Multi-system integration workflows [Section titled “Multi-system integration workflows”](#multi-system-integration-workflows) Orchestrate data across multiple systems using external IDs as the common identifier thread. ### Customer lifecycle automation [Section titled “Customer lifecycle automation”](#customer-lifecycle-automation) Multi-system workflow example ```javascript 1 // Complete customer onboarding workflow 2 async function onboardNewCustomer(customerData) { 3 const { company_name, admin_email, plan_type, salesforce_account_id, stripe_customer_id } = customerData; 4 5 try { 6 // 1. Create organization in Scalekit 7 const organization = await scalekit.organization.create({ 8 display_name: company_name, 9 external_id: stripe_customer_id, // Use billing system ID as primary external ID 10 metadata: { 11 plan_type: plan_type, 12 salesforce_account_id: salesforce_account_id, 13 stripe_customer_id: stripe_customer_id, 14 onboarding_status: 'pending', 15 created_date: new Date().toISOString() 16 } 17 }); 18 19 // 2. Create admin user 20 const { user } = await scalekit.user.createUserAndMembership(organization.id, { 21 email: admin_email, 22 externalId: `${stripe_customer_id}_admin`, // Composite external ID 23 metadata: { 24 role_type: 'admin', 25 onboarding_step: 'account_created' 26 }, 27 sendInvitationEmail: true 28 }); 29 30 // 3. Update CRM with Scalekit IDs 31 await salesforce.updateAccount(salesforce_account_id, { 32 Scalekit_Organization_ID__c: organization.id, 33 Scalekit_Admin_User_ID__c: user.id, 34 Onboarding_Status__c: 'In Progress' 35 }); 36 37 // 4. Configure billing in Stripe 38 await stripe.customers.update(stripe_customer_id, { 39 metadata: { 40 scalekit_org_id: organization.id, 41 scalekit_admin_user_id: user.id 42 } 43 }); 44 45 // 5. Send onboarding notifications 46 await sendOnboardingEmail(admin_email, organization.id); 47 await notifySalesTeam(salesforce_account_id, 'customer_onboarded'); 48 49 return { organization, user }; 50 51 } catch (error) { 52 console.error('Customer onboarding failed:', error); 53 // Rollback logic here 54 throw error; 55 } 56 } ``` ## Error handling and retry patterns [Section titled “Error handling and retry patterns”](#error-handling-and-retry-patterns) Implement robust error handling for external system integrations to ensure data consistency and reliability. ### Retry with exponential backoff [Section titled “Retry with exponential backoff”](#retry-with-exponential-backoff) Robust integration error handling ```javascript 1 // Utility function for retrying API calls with exponential backoff 2 async function retryWithBackoff(fn, maxRetries = 3, baseDelay = 1000) { 3 for (let attempt = 1; attempt <= maxRetries; attempt++) { 4 try { 5 return await fn(); 6 } catch (error) { 7 if (attempt === maxRetries) { 8 throw error; 9 } 10 11 // Exponential backoff with jitter 12 const delay = baseDelay * Math.pow(2, attempt - 1) + Math.random() * 1000; 13 await new Promise(resolve => setTimeout(resolve, delay)); 14 } 15 } 16 } 17 18 // Resilient external ID lookup 19 async function findOrganizationWithRetry(externalId) { 20 return retryWithBackoff(async () => { 21 const org = await scalekit.organization.getByExternalId(externalId); 22 if (!org) { 23 throw new Error(`Organization not found for external ID: ${externalId}`); 24 } 25 return org; 26 }); 27 } 28 29 // Webhook processing with error handling 30 app.post('/webhook', async (req, res) => { 31 try { 32 const { external_id, event_type, data } = req.body; 33 34 // Find organization with retry logic 35 const organization = await findOrganizationWithRetry(external_id); 36 37 // Process the webhook data 38 await processWebhookEvent(organization, event_type, data); 39 40 res.status(200).json({ status: 'success' }); 41 42 } catch (error) { 43 console.error('Webhook processing failed:', error); 44 45 // Queue for retry if it's a temporary failure 46 if (isRetryableError(error)) { 47 await queueWebhookForRetry(req.body); 48 res.status(202).json({ status: 'queued_for_retry' }); 49 } else { 50 res.status(400).json({ status: 'error', message: error.message }); 51 } 52 } 53 }); 54 55 function isRetryableError(error) { 56 return error.code === 'NETWORK_ERROR' || 57 error.code === 'RATE_LIMITED' || 58 error.status >= 500; 59 } ``` ## Security considerations [Section titled “Security considerations”](#security-considerations) When implementing external ID integrations, follow these security best practices: ### Webhook security [Section titled “Webhook security”](#webhook-security) Secure webhook handling ```javascript 1 // Verify webhook signatures 2 function verifyWebhookSignature(payload, signature, secret) { 3 const expectedSignature = crypto 4 .createHmac('sha256', secret) 5 .update(payload) 6 .digest('hex'); 7 8 return crypto.timingSafeEqual( 9 Buffer.from(signature, 'hex'), 10 Buffer.from(expectedSignature, 'hex') 11 ); 12 } 13 14 // Rate limiting for webhook endpoints 15 const webhookLimiter = rateLimit({ 16 windowMs: 1 * 60 * 1000, // 1 minute 17 max: 100, // limit each IP to 100 requests per windowMs 18 message: 'Too many webhook requests from this IP' 19 }); 20 21 app.post('/webhook', webhookLimiter, (req, res) => { 22 // Verify signature before processing 23 if (!verifyWebhookSignature(req.body, req.headers['x-signature'], process.env.WEBHOOK_SECRET)) { 24 return res.status(401).json({ error: 'Invalid signature' }); 25 } 26 27 // Process webhook... 28 }); ``` ### Data validation and sanitization [Section titled “Data validation and sanitization”](#data-validation-and-sanitization) * **Validate external IDs** before using them in database queries * **Sanitize metadata** to prevent injection attacks * **Use prepared statements** for database operations * **Implement input validation** for all external data * **Log security events** for monitoring and auditing ## Monitoring and observability [Section titled “Monitoring and observability”](#monitoring-and-observability) Implement comprehensive monitoring for external ID integrations to ensure system health and quick issue resolution. ### Integration health monitoring [Section titled “Integration health monitoring”](#integration-health-monitoring) Integration monitoring example ```javascript 1 // Track integration health metrics 2 class IntegrationMonitor { 3 constructor() { 4 this.metrics = { 5 successful_syncs: 0, 6 failed_syncs: 0, 7 average_sync_time: 0, 8 last_successful_sync: null 9 }; 10 } 11 12 async recordSyncAttempt(system, success, duration) { 13 if (success) { 14 this.metrics.successful_syncs++; 15 this.metrics.last_successful_sync = new Date(); 16 } else { 17 this.metrics.failed_syncs++; 18 } 19 20 // Update average sync time 21 this.updateAverageSyncTime(duration); 22 23 // Send metrics to monitoring system 24 await this.sendMetrics(system, this.metrics); 25 } 26 27 updateAverageSyncTime(duration) { 28 const totalSyncs = this.metrics.successful_syncs + this.metrics.failed_syncs; 29 this.metrics.average_sync_time = 30 (this.metrics.average_sync_time * (totalSyncs - 1) + duration) / totalSyncs; 31 } 32 } 33 34 // Usage in integration functions 35 const monitor = new IntegrationMonitor(); 36 37 async function syncWithExternalSystem(externalId, data) { 38 const startTime = Date.now(); 39 let success = false; 40 41 try { 42 await performSync(externalId, data); 43 success = true; 44 } catch (error) { 45 console.error('Sync failed:', error); 46 throw error; 47 } finally { 48 const duration = Date.now() - startTime; 49 await monitor.recordSyncAttempt('external_system', success, duration); 50 } 51 } ``` ## Best practices summary [Section titled “Best practices summary”](#best-practices-summary) ### External ID management [Section titled “External ID management”](#external-id-management) * **Use meaningful, stable identifiers** from your primary business system * **Implement consistent naming conventions** across all external IDs * **Handle ID migration scenarios** when external systems change * **Validate external IDs** before using them in operations ### Integration reliability [Section titled “Integration reliability”](#integration-reliability) * **Implement retry logic** with exponential backoff for API calls * **Use webhooks for real-time sync** and scheduled jobs for periodic reconciliation * **Handle rate limits** gracefully with queuing and backoff strategies * **Monitor integration health** with comprehensive metrics and alerting ### Security and compliance [Section titled “Security and compliance”](#security-and-compliance) * **Verify webhook signatures** to ensure authenticity * **Implement rate limiting** on webhook endpoints * **Validate and sanitize** all external data * **Audit integration activities** for compliance requirements ### Performance optimization [Section titled “Performance optimization”](#performance-optimization) * **Cache frequently accessed external ID mappings** * **Batch operations** where possible to reduce API calls * **Use appropriate timeouts** for external API calls * **Implement circuit breakers** for unreliable external services This integration approach enables seamless data flow between Scalekit and your business systems while maintaining security, reliability, and performance standards. --- # DOCUMENT BOUNDARY --- # Modular social logins > Learn how to integrate modular social logins module with Scalekit Social login enables authentication through existing accounts from providers like Google, Microsoft, and GitHub. Users don’t need to create or remember new credentials, making the sign-in process faster and more convenient. This guide explains how to implement social login in your application with Scalekit’s OAuth 2.0 integration. ![How Scalekit works](/.netlify/images?url=_astro%2F0.CtcbvoxC.png\&w=5776\&h=1924\&dpl=6a01bf5aba8408000850fe26) 1. ## Set up Scalekit [Section titled “Set up Scalekit”](#set-up-scalekit) Use the following instructions to install the SDK for your technology stack. * Node.js ```bash npm install @scalekit-sdk/node ``` * Python ```sh pip install scalekit-sdk-python ``` * Go ```sh go get -u github.com/scalekit-inc/scalekit-sdk-go ``` * Java ```groovy /* Gradle users - add the following to your dependencies in build file */ implementation "com.scalekit:scalekit-sdk-java:2.0.11" ``` ```xml com.scalekit scalekit-sdk-java 2.0.11 ``` Follow the [installation guide](/authenticate/set-up-scalekit/) to configure Scalekit in your application. Go to Dashboard > Authentication > General to **turn off the Full-Stack Auth** since you’d use the modular social logins module. This disables user management and session management features and let’s to only use social login authentication. 2. ## Configure social login providers [Section titled “Configure social login providers”](#configure-social-login-providers) Google login is pre-configured in all development environments for simplified testing. You can integrate additional social login providers by setting up your own connection credentials with each provider. Navigate to **Authentication** > **Auth Methods** > **Social logins** in your dashboard to configure these settings ### Google Enable users to sign in with their Google accounts using OAuth 2.0 [Set up →](/guides/integrations/social-connections/google) ### GitHub Allow users to authenticate using their GitHub credentials [Set up →](/guides/integrations/social-connections/github) ### Microsoft Integrate Microsoft accounts for seamless user authentication [Set up →](/guides/integrations/social-connections/microsoft) ### GitLab Enable GitLab-based authentication for your application [Set up →](/guides/integrations/social-connections/gitlab) ### LinkedIn Let users sign in with their LinkedIn accounts using OAuth 2.0 [Set up →](/guides/integrations/social-connections/linkedin) ### Salesforce Enable Salesforce-based authentication for your application [Set up →](/guides/integrations/social-connections/salesforce) After configuration, Scalekit can interact with these providers to authenticate users and verify their identities. 3. ## From your application, redirect users to provider’s OAuth pages [Section titled “From your application, redirect users to provider’s OAuth pages”](#from-your-application-redirect-users-to-providers-oauth-pages) Create an authorization URL to redirect users to social provider’s sign-in page. Use the Scalekit SDK to construct this URL with your redirect URI and provider identifier. Supported `provider` values: `google`, `microsoft`, `github`, `salesforce`, `linkedin`, `gitlab` * Node.js ```javascript 1 // 2 const authorizationURL = scalekit.getAuthorizationUrl(redirectUri, { 3 provider: 'google', 4 state: state, // recommended 5 }); 6 7 /* 8 https://auth.scalekit.com/authorize? 9 client_id=skc_122056050118122349527& 10 redirect_uri=https://yourapp.com/auth/callback& 11 provider=google 12 */ ``` * Python ```python 1 options = AuthorizationUrlOptions() 2 3 options.provider = 'google' 4 5 authorization_url = scalekit_client.get_authorization_url( 6 redirect_uri=, 7 options=options 8 ) ``` * Go ```go 1 options := scalekitClient.AuthorizationUrlOptions{} 2 // Pass the social login provider details while constructing the authorization URL. 3 options.Provider = "google" 4 5 authorizationURL := scalekitClient.GetAuthorizationUrl( 6 redirectUrl, 7 options, 8 ) 9 // Next step is to redirect the user to this authorization URL 10 } ``` * Java ```java 1 package com.scalekit; 2 3 import com.scalekit.internal.http.AuthorizationUrlOptions; 4 5 public class Main { 6 7 public static void main(String[] args) { 8 ScalekitClient scalekitClient = new ScalekitClient( 9 "", 10 "", 11 "" 12 ); 13 AuthorizationUrlOptions options = new AuthorizationUrlOptions(); 14 options.setProvider("google"); 15 try { 16 // Pass the social login provider details while constructing the authorization URL. 17 String url = scalekitClient.authentication().getAuthorizationUrl(redirectUrl, options).toString(); 18 } catch (Exception e) { 19 System.out.println(e.getMessage()); 20 } 21 } 22 } ``` After the user successfully authenticates with the selected social login provider, they will be redirected back to your application. Scalekit passes an authorization `code` to your registered callback endpoint, which you’ll use in the next step to retrieve user information. 4. ## Get user details from the callback [Section titled “Get user details from the callback”](#get-user-details-from-the-callback) After successful authentication, Scalekit creates a user record and sends the user information to your callback endpoint. 1. Add a callback endpoint in your application (typically `https://your-app.com/auth/callback`) 2. [Register](/guides/dashboard/allowed-callback-url/) it in your Scalekit dashboard > Authentication > Redirect URLS > Allowed Callback URLs 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 proceed to creating session and logging in the user. * Node.js ```javascript 1 const { code, state, error, error_description } = req.query; 2 3 if (error) { 4 // Handle errors (use error_description if present) 5 } 6 7 const authResult = await scalekit.authenticateWithCode(code, redirectUri); 8 9 // authResult.user has the authenticated user's details 10 const userEmail = authResult.user.email; 11 12 // Next step: create a session for this user and allow access ``` * Python ```python 1 code = request.args.get('code') 2 error = request.args.get('error') 3 error_description = request.args.get('error_description') 4 5 if error: 6 raise Exception(error_description) 7 8 auth_result = scalekit_client.authenticate_with_code( 9 code, 10 11 ) 12 13 # result.user has the authenticated user's details 14 user_email = auth_result.user.email 15 16 # Next step: create a session for this user and allow access ``` * Go ```go 1 code := r.URL.Query().Get("code") 2 error := r.URL.Query().Get("error") 3 errorDescription := r.URL.Query().Get("error_description") 4 5 if error != "" { 6 // Handle errors and exit 7 } 8 9 authResult, err := scalekitClient.AuthenticateWithCode(r.Context(), code, redirectUrl) 10 if err != nil { 11 // Handle errors and exit 12 } 13 14 // authResult.User has the authenticated user's details 15 userEmail := authResult.User.Email 16 17 // Next step: create a session for this user and allow access ``` * Java ```java 1 String code = request.getParameter("code"); 2 String error = request.getParameter("error"); 3 String errorDescription = request.getParameter("error_description"); 4 if (error != null && !error.isEmpty()) { 5 // Handle errors 6 return; 7 } 8 try { 9 AuthenticationResponse res = scalekitClient.authentication().authenticateWithCode(code, redirectUrl); 10 // res.getIdTokenClaims() has the authenticated user's details 11 String userEmail = res.getIdTokenClaims().getEmail(); 12 13 } catch (Exception e) { 14 // Handle errors 15 } 16 17 // Next step: create a session for this user and allow access ``` The *auth result* object * Auth result ```js { user: { email: "john.doe@example.com" // User's email // any additional common fields }, idToken: "", // JWT with user profile claims accessToken: "", // JWT for API calls expiresIn: 899 // Seconds until expiration } ``` * Decoded ID token (JWT) ```json { "alg": "RS256", "kid": "snk_82937465019283746", "typ": "JWT" }.{ "amr": [ "conn_92847563920187364" ], "at_hash": "j8kqPm3nRt5Kx2Vy9wL_Zp", "aud": [ "skc_73645291837465928" ], "azp": "skc_73645291837465928", "c_hash": "Hy4k2M9pWnX7vqR8_Jt3bg", "client_id": "skc_73645291837465928", "email": "alice.smith@example.com", "email_verified": true, "exp": 1751697469, "iat": 1751438269, "iss": "https://demo-company-dev.scalekit.cloud", "sid": "ses_83746592018273645", "sub": "conn_92847563920187364;alice.smith@example.com" // A scalekit user ID is sent if user management is enabled }.[Signature] ``` * Decoded access token ```json { "alg": "RS256", "kid": "snk_794467716206433", "typ": "JWT" }.{ "iss": "https://acme-corp-dev.scalekit.cloud", "sub": "conn_794467724427269;robert.wilson@acme.com", "aud": [ "skc_794467724259497" ], "exp": 1751439169, "iat": 1751438269, "nbf": 1751438269, "client_id": "skc_794467724259497", "jti": "tkn_794754665320942", // External identifiers if updated on Scalekit "xoid": "ext_org_123", // Organization ID "xuid": "ext_usr_456" // User ID }.[Signature] ``` Your application now supports social login authentication. Users can sign in securely using their preferred social identity providers like Google, GitHub, Microsoft, and more. --- # DOCUMENT BOUNDARY --- # Preserve target route post-auth > Redirect users back to page they asked for after authentication using a signed return URL Users may bookmark specific pages of your app, but their session might be expired. They need to be redirected to the page they asked for after authentication. That means your app needs to preserve the user’s original destination. You will capture the user’s original destination, carry it through the OAuth flow safely, and redirect back after login. You will prevent open-redirect attacks by validating and signing the return URL. 1. ## Capture the intended destination [Section titled “Capture the intended destination”](#capture-the-intended-destination) When an unauthenticated user requests a protected route, capture its path. * Node.js Express.js ```javascript 1 app.get('/login', (req, res) => { 2 const nextPath = typeof req.query.next === 'string' ? req.query.next : '/' 3 // Only allow internal paths 4 const safe = nextPath.startsWith('/') && !nextPath.startsWith('//') ? nextPath : '/' 5 res.cookie('sk_return_to', safe, { httpOnly: true, secure: true, sameSite: 'lax', path: '/' }) 6 // build authorization URL next 7 }) ``` * Python Flask ```python 1 @app.route('/login') 2 def login(): 3 next_path = request.args.get('next', '/') 4 safe = next_path if next_path.startswith('/') and not next_path.startswith('//') else '/' 5 resp = make_response() 6 resp.set_cookie('sk_return_to', safe, httponly=True, secure=True, samesite='Lax', path='/') 7 return resp ``` * Go Gin ```go 1 func login(c *gin.Context) { 2 nextPath := c.Query("next") 3 if nextPath == "" || !strings.HasPrefix(nextPath, "/") || strings.HasPrefix(nextPath, "//") { 4 nextPath = "/" 5 } 6 cookie := &http.Cookie{Name: "sk_return_to", Value: nextPath, HttpOnly: true, Secure: true, Path: "/"} 7 http.SetCookie(c.Writer, cookie) 8 } ``` * Java Spring ```java 1 @GetMapping("/login") 2 public void login(HttpServletRequest request, HttpServletResponse response) { 3 String nextPath = Optional.ofNullable(request.getParameter("next")).orElse("/"); 4 boolean safe = nextPath.startsWith("/") && !nextPath.startsWith("//"); 5 Cookie cookie = new Cookie("sk_return_to", safe ? nextPath : "/"); 6 cookie.setHttpOnly(true); cookie.setSecure(true); cookie.setPath("/"); 7 response.addCookie(cookie); 8 } ``` 2. ## Build the authorization URL [Section titled “Build the authorization URL”](#build-the-authorization-url) Generate the authorization URL as in the quickstart. Optionally include a short hint in `state` like `"n=/billing"` after signing or encoding. * Node.js Express.js ```javascript 1 const redirectUri = 'https://your-app.com/auth/callback' 2 const options = { scopes: ['openid','profile','email','offline_access'] } 3 const authorizationUrl = scalekit.getAuthorizationUrl(redirectUri, options) 4 res.redirect(authorizationUrl) ``` * Python Flask ```python 1 redirect_uri = 'https://your-app.com/auth/callback' 2 options = AuthorizationUrlOptions(scopes=['openid','profile','email','offline_access']) 3 authorization_url = scalekit_client.get_authorization_url(redirect_uri, options) 4 return redirect(authorization_url) ``` * Go Gin ```go 1 redirectUri := "https://your-app.com/auth/callback" 2 options := scalekitClient.AuthorizationUrlOptions{Scopes: []string{"openid","profile","email","offline_access"}} 3 authorizationURL, _ := scalekitClient.GetAuthorizationUrl(redirectUri, options) 4 c.Redirect(http.StatusFound, authorizationURL.String()) ``` * Java Spring ```java 1 String redirectUri = "https://your-app.com/auth/callback"; 2 AuthorizationUrlOptions options = new AuthorizationUrlOptions(); 3 options.setScopes(Arrays.asList("openid","profile","email","offline_access")); 4 URL authorizationUrl = scalekitClient.authentication().getAuthorizationUrl(redirectUri, options); 5 return new RedirectView(authorizationUrl.toString()); ``` 3. ## After callback, redirect safely [Section titled “After callback, redirect safely”](#after-callback-redirect-safely) After exchanging the code and creating a session, read `sk_return_to`. Validate and normalize the path. Default to `/dashboard` or `/`. * Node.js Express.js ```javascript 1 app.get('/auth/callback', async (req, res) => { 2 // ... exchange code ... 3 const raw = req.cookies.sk_return_to || '/' 4 const safe = raw.startsWith('/') && !raw.startsWith('//') ? raw : '/' 5 res.clearCookie('sk_return_to', { path: '/' }) 6 res.redirect(safe || '/dashboard') 7 }) ``` * Python Flask ```python 1 def callback(): 2 # ... exchange code ... 3 raw = request.cookies.get('sk_return_to', '/') 4 safe = raw if raw.startswith('/') and not raw.startswith('//') else '/' 5 resp = redirect(safe or '/dashboard') 6 resp.delete_cookie('sk_return_to', path='/') 7 return resp ``` * Go Gin ```go 1 func callback(c *gin.Context) { 2 // ... exchange code ... 3 raw, _ := c.Cookie("sk_return_to") 4 if raw == "" || !strings.HasPrefix(raw, "/") || strings.HasPrefix(raw, "//") { 5 raw = "/" 6 } 7 http.SetCookie(c.Writer, &http.Cookie{Name: "sk_return_to", Value: "", MaxAge: -1, Path: "/"}) 8 c.Redirect(http.StatusFound, raw) 9 } ``` * Java Spring ```java 1 public RedirectView callback(HttpServletRequest request, HttpServletResponse response) { 2 // ... exchange code ... 3 String raw = getCookie(request, "sk_return_to").orElse("/"); 4 boolean ok = raw.startsWith("/") && !raw.startsWith("//"); 5 Cookie clear = new Cookie("sk_return_to", ""); clear.setPath("/"); clear.setMaxAge(0); 6 response.addCookie(clear); 7 return new RedirectView(ok ? raw : "/dashboard"); 8 } ``` 4. ## Sign return\_to values Optional [Section titled “Sign return\_to values ”](#sign-return_to-values-) If you pass `return_to` via query string or store longer values, compute an HMAC and verify it before redirecting. Reject unsigned or invalid pairs. * Node.js HMAC signing ```javascript 1 import crypto from 'crypto' 2 function sign(value, secret) { 3 const mac = crypto.createHmac('sha256', secret).update(value).digest('base64url') 4 return `${value}|${mac}` 5 } 6 function verify(signed, secret) { 7 const [v, mac] = signed.split('|') 8 const good = crypto.timingSafeEqual(Buffer.from(mac), Buffer.from(sign(v, secret).split('|')[1])) 9 return good ? v : null 10 } ``` * Python HMAC signing ```python 1 import hmac, hashlib, base64 2 def sign(value: str, secret: bytes) -> str: 3 mac = hmac.new(secret, value.encode(), hashlib.sha256).digest() 4 return f"{value}|{base64.urlsafe_b64encode(mac).decode().rstrip('=')}" 5 def verify(signed: str, secret: bytes) -> str | None: 6 try: 7 value, mac = signed.split('|', 1) 8 expected = sign(value, secret).split('|', 1)[1] 9 if hmac.compare_digest(mac, expected): 10 return value 11 except Exception: 12 pass 13 return None ``` * Go HMAC signing ```go 1 import ( 2 "crypto/hmac" 3 "crypto/sha256" 4 "encoding/base64" 5 ) 6 func sign(value string, secret []byte) string { 7 mac := hmac.New(sha256.New, secret) 8 mac.Write([]byte(value)) 9 sum := mac.Sum(nil) 10 return value + "|" + base64.RawURLEncoding.EncodeToString(sum) 11 } 12 func verify(signed string, secret []byte) *string { 13 parts := strings.SplitN(signed, "|", 2) 14 if len(parts) != 2 { return nil } 15 expected := strings.SplitN(sign(parts[0], secret), "|", 2)[1] 16 if hmac.Equal([]byte(parts[1]), []byte(expected)) { 17 return &parts[0] 18 } 19 return nil 20 } ``` * Java HMAC signing ```java 1 import javax.crypto.Mac; 2 import javax.crypto.spec.SecretKeySpec; 3 import java.util.Base64; 4 String sign(String value, byte[] secret) throws Exception { 5 Mac mac = Mac.getInstance("HmacSHA256"); 6 mac.init(new SecretKeySpec(secret, "HmacSHA256")); 7 byte[] raw = mac.doFinal(value.getBytes(StandardCharsets.UTF_8)); 8 String b64 = Base64.getUrlEncoder().withoutPadding().encodeToString(raw); 9 return value + "|" + b64; 10 } 11 String verify(String signed, byte[] secret) throws Exception { 12 String[] parts = signed.split("\\|", 2); 13 if (parts.length != 2) return null; 14 String expected = sign(parts[0], secret).split("\\|", 2)[1]; 15 return MessageDigest.isEqual(parts[1].getBytes(StandardCharsets.UTF_8), expected.getBytes(StandardCharsets.UTF_8)) ? parts[0] : null; 16 } ``` Limit scope and length Allowlist a small set of internal prefixes (for example, `/app`, `/billing`) and cap `return_to` length (for example, 512 chars). Reject anything else. Never redirect to external origins Allow only same-origin paths (e.g., `/billing`). Do not accept absolute URLs or protocol-relative URLs. This blocks open redirects. --- # DOCUMENT BOUNDARY --- # Set up SCIM connection > Set up a SCIM connection to your directory provider Scalekit supports user provisioning based on the [SCIM protocol](/directory/guides/user-provisioning-basics/). This allows your customers to manage their users automatically through directory providers, simplifying user access and revocation to your app when their employees join or leave an organization. By configuring their directory provider with your app via the Scalekit admin portal, customers can ensure seamless user management. 1. ## Enable SCIM provisioning for the organization [Section titled “Enable SCIM provisioning for the organization”](#enable-scim-provisioning-for-the-organization) The SCIM provisioning feature should be enabled for that particular organization. You can manually do this via the Scalekit dashboard > organization > overview. The other way, is to provide an option in your app so that organization admins (customers) can enable it within your app. Here’s how you can do that with Scalekit. Use the following SDK method to enable SCIM provisioning for the organization: * Node.js Enable SCIM ```javascript const settings = { features: [ { name: 'scim', enabled: true, } ], }; await scalekit.organization.updateOrganizationSettings( '', // Get this from the idToken or accessToken settings ); ``` * Python Enable SCIM ```python settings = [ { "name": "scim", "enabled": True } ] scalekit.organization.update_organization_settings( organization_id='', # Get this from the idToken or accessToken settings=settings ) ``` * Java Enable SCIM ```java OrganizationSettingsFeature featureSCIM = OrganizationSettingsFeature.newBuilder() .setName("scim") .setEnabled(true) .build(); updatedOrganization = scalekitClient.organizations() .updateOrganizationSettings(organizationId, List.of(featureSCIM)); ``` * Go Enable SCIM ```go settings := OrganizationSettings{ Features: []Feature{ { Name: "scim", Enabled: true, }, }, } organization, err := sc.Organization().UpdateOrganizationSettings(ctx, organizationId, settings) if err != nil { // Handle error } ``` Alternatively, enable SCIM provisioning from the Scalekit dashboard: navigate to Organizations, open the menu (⋯) for an organization, and check SCIM provisioning. 2. ## Enable admin portal for enterprise customer onboarding [Section titled “Enable admin portal for enterprise customer onboarding”](#enable-admin-portal-for-enterprise-customer-onboarding) After SCIM provisioning is enabled for that organization, provide a method for configuring a SCIM connection with the organization’s identity provider. Scalekit offers two primary approaches: * Generate a link to the admin portal from the Scalekit dashboard and share it with organization admins via your usual channels. * Or embed the admin portal in your application in an inline frame so administrators can configure their IdP without leaving your app. [See how to onboard enterprise customers ](/directory/guides/onboard-enterprise-customers/) 3. ## Test your SCIM integration [Section titled “Test your SCIM integration”](#test-your-scim-integration) To verify that SCIM provisioning is working correctly, create a new user in the directory provider and confirm that it is automatically created in the Scalekit organization’s user list. To programmatically list the connected directories in your app, use the following SDK methods: * Node.js List connected directories ```javascript const { directories } = await scalekit.directory.listDirectories(''); ``` * Python List connected directories ```python directories = scalekit_client.directory.list_directories(organization_id='') ``` * Java List connected directories ```java ListDirectoriesResponse response = scalekitClient.directories().listDirectories(organizationId); ``` * Go List connected directories ```go directories, err := sc.Directory().ListDirectories(ctx, organizationId) ``` The response will be a list of connected directories, similar to the following: List connected directories response ```json { "directories": [ { "attribute_mappings": { "attributes": [] }, "directory_endpoint": "https://yourapp.scalekit.com/api/v1/directoies/dir_123212312/scim/v2", "directory_provider": "OKTA", "directory_type": "SCIM", "email": "john.doe@scalekit.cloud", "enabled": true, "groups_tracked": "ALL", "id": "dir_121312434123312", "last_synced_at": "2024-10-01T00:00:00Z", "name": "Azure AD", "organization_id": "org_121312434123312", "role_assignments": { "assignments": [ { "group_id": "dirgroup_121312434123", "role_name": "string" } ] }, "secrets": [ { "create_time": "2024-10-01T00:00:00Z", "directory_id": "dir_12362474900684814", "expire_time": "2025-10-01T00:00:00Z", "id": "string", "last_used_time": "2024-10-01T00:00:00Z", "secret_suffix": "Nzg5", "status": "INACTIVE" } ], "stats": { "group_updated_at": "2024-10-01T00:00:00Z", "total_groups": 10, "total_users": 10, "user_updated_at": "2024-10-01T00:00:00Z" }, "status": "IN_PROGRESS", "total_groups": 10, "total_users": 10 } ] } ``` 4. ## Enterprise users are now automatically provisioned your app [Section titled “Enterprise users are now automatically provisioned your app”](#enterprise-users-are-now-automatically-provisioned-your-app) Scalekit automatically provisions and synchronizes users from the directory provider to your application. The organization administrator configures the synchronization frequency within their directory provider console. To retrieve a list of all provisioned users, use the [Directory API](https://docs.scalekit.com/apis/#tag/directory/GET/api/v1/organizations/%7Borganization_id%7D/directories/%7Bdirectory_id%7D/users).