scalekit-inc/implementing-scalekit-fsa

Scalekit Full-Stack Authentication

Setup

Install the SDK and set credentials in .env:

SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
SCALEKIT_CLIENT_ID=<your-client-id>
SCALEKIT_CLIENT_SECRET=<your-client-secret>

Auth flow

1. Redirect to login

Generate an authorization URL and redirect the user:

// Node.js
const authorizationUrl = scalekit.getAuthorizationUrl(redirectUri, {
  scopes: ['openid', 'profile', 'email', 'offline_access']
});
res.redirect(authorizationUrl);

redirectUri must exactly match the allowed callback URL registered in the Scalekit dashboard.

2. Handle the callback

Exchange the authorization code for tokens:

// Node.js
const { user, idToken, accessToken, refreshToken } =
  await scalekit.authenticateWithCode(code, redirectUri);

| Token | Purpose | |---|---| | idToken | Full user profile (sub, oid, email, name, exp) | | accessToken | Roles + permissions; expires in 5 min (configurable) | | refreshToken | Long-lived; use to renew access tokens |

3. Create the session

Store tokens in HttpOnly cookies:

// Node.js
res.cookie('accessToken', authResult.accessToken, {
  maxAge: (authResult.expiresIn - 60) * 1000,
  httpOnly: true, secure: true, path: '/api', sameSite: 'strict'
});
res.cookie('refreshToken', authResult.refreshToken, {
  httpOnly: true, secure: true, path: '/auth/refresh', sameSite: 'strict'
});

Token validation middleware pattern:

1. Read accessToken cookie → decrypt → scalekit.validateAccessToken(token)
2. If invalid → scalekit.refreshAccessToken(refreshToken) → update cookies
3. If refresh fails → log out the user

4. Log out

Clear session data, then redirect to Scalekit's logout endpoint:

// Node.js
clearSessionData();
const logoutUrl = scalekit.getLogoutUrl(idTokenHint, postLogoutRedirectUri);
res.redirect(logoutUrl); // One-time use URL; expires after logout

Cross-language reference

All SDK methods follow the same pattern across languages with minor naming conventions:

| Operation | Node.js | Python | Go | Java | |---|---|---|---|---| | Auth URL | getAuthorizationUrl | get_authorization_url | GetAuthorizationUrl | getAuthorizationUrl | | Exchange code | authenticateWithCode | authenticate_with_code | AuthenticateWithCode | authenticateWithCode | | Validate token | validateAccessToken | validate_access_token | ValidateAccessToken | validateAccessToken | | Refresh token | refreshAccessToken | refresh_access_token | RefreshAccessToken | refreshToken | | Logout URL | getLogoutUrl | get_logout_url | GetLogoutUrl | getLogoutUrl |

What this unlocks

One integration enables: Magic Link & OTP, social sign-ins, enterprise SSO, workspaces, MCP authentication, SCIM provisioning, and user management.