Node.js SDK

The official Node.js SDK for integrating Scalekit with Node.js applications. It supports OIDC and SAML SSO and includes helpers for common authentication tasks.

Installation

Install the SDK using npm or yarn:

npm install @scalekit-sdk/node

or with yarn:

yarn add @scalekit-sdk/node

Quick Start

Initialize the Scalekit client with your environment credentials:

utils/auth.js

import { Scalekit } from '@scalekit-sdk/node';

export const scalekit = new Scalekit(
  process.env.SCALEKIT_ENVIRONMENT_URL,
  process.env.SCALEKIT_CLIENT_ID,
  process.env.SCALEKIT_CLIENT_SECRET
);

Security: Never hard-code credentials. Always use environment variables to store sensitive configuration.

Core Methods

Generate Authorization URL

Create an authorization URL to redirect users to Scalekit for authentication:

const redirectUri = 'https://yourapp.com/auth/callback';
const options = {
  scopes: ['openid', 'profile', 'email', 'offline_access'],
  state: generateSecureRandomState(), // For CSRF protection
};

const url = scalekit.getAuthorizationUrl(redirectUri, options);
res.redirect(url);

Exchange Authorization Code

Exchange the authorization code for user tokens after the callback:

Callback handler

app.get('/auth/callback', async (req, res) => {
  const { code, error } = req.query;

  if (error) {
    return res.redirect('/login?error=auth_failed');
  }

  try {
    const authResult = await scalekit.authenticateWithCode(
      code,
      'https://yourapp.com/auth/callback'
    );

    const { user, accessToken, refreshToken, idToken } = authResult;

    // Store tokens securely
    req.session.user = user;
    res.redirect('/dashboard');
  } catch (error) {
    console.error('Authentication failed:', error);
    res.redirect('/login?error=exchange_failed');
  }
});

Validate Access Token

Validate access tokens on protected routes:

Middleware

async function verifyToken(req, res, next) {
  const { accessToken } = req.cookies;

  if (!accessToken) {
    return res.status(401).json({ error: 'Authentication required' });
  }

  try {
    const isValid = await scalekit.validateAccessToken(accessToken);

    if (!isValid) {
      return res.status(401).json({ error: 'Invalid token' });
    }

    next();
  } catch (error) {
    return res.status(401).json({ error: 'Authentication failed' });
  }
}

Refresh Access Token

Refresh expired access tokens using the refresh token:

Token refresh

try {
  const authResult = await scalekit.refreshAccessToken(refreshToken);

  // Update stored tokens
  const { accessToken, refreshToken: newRefreshToken, expiresIn } = authResult;

  res.cookie('accessToken', accessToken, {
    maxAge: (expiresIn - 60) * 1000,
    httpOnly: true,
    secure: true,
    sameSite: 'strict'
  });
} catch (error) {
  console.error('Token refresh failed:', error);
  res.redirect('/login');
}

Organization Management

Create Organization

Create a new organization for enterprise customers:

const organization = await scalekit.organization.createOrganization('Acme Corp', {
  externalId: 'org_12345',
});

console.log('Organization created:', organization.id);

Generate Admin Portal Link

Generate a portal link for customers to configure SSO:

const link = await scalekit.organization.generatePortalLink(organizationId);

// Use link.location as iframe src or shareable URL
res.json({ portalUrl: link.location });

Session Management

Get Session Details

Retrieve details for a specific session:

const sessionDetails = await scalekit.session.getSession('ses_1234567890123456');
console.log('Session:', sessionDetails);

List User Sessions

List all active sessions for a user:

const userSessions = await scalekit.session.getUserSessions('usr_1234567890123456', {
  pageSize: 10,
  filter: {
    status: ['ACTIVE'],
  }
});

Revoke Session

Revoke a specific session (logout from one device):

const revokedSession = await scalekit.session.revokeSession('ses_1234567890123456');
console.log('Session revoked');

Revoke All User Sessions

Revoke all sessions for a user (logout from all devices):

await scalekit.session.revokeAllUserSessions('usr_1234567890123456');
console.log('All sessions revoked');

Advanced Features

Custom Authorization Options

Customize the authorization flow with additional options:

const options = {
  scopes: ['openid', 'profile', 'email', 'offline_access'],
  organizationId: 'org_123',        // Route to specific organization
  connectionId: 'conn_456',         // Route to specific connection
  loginHint: 'user@example.com',    // Pre-fill email
  prompt: 'login',                  // Force re-authentication
  state: generateState(),           // CSRF protection
};

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

Error Handling

The SDK throws errors that should be caught and handled:

try {
  const result = await scalekit.authenticateWithCode(code, redirectUri);
} catch (error) {
  if (error.code === 'invalid_grant') {
    // Authorization code expired or already used
    return res.redirect('/login?error=code_expired');
  }

  if (error.code === 'invalid_client') {
    // Invalid credentials
    console.error('SDK configuration error');
  }

  // Handle other errors
  console.error('Authentication error:', error.message);
}

TypeScript Support

The SDK includes TypeScript definitions:

import { Scalekit, AuthorizationUrlOptions, AuthenticationResponse } from '@scalekit-sdk/node';

const scalekit: Scalekit = new Scalekit(
  process.env.SCALEKIT_ENVIRONMENT_URL!,
  process.env.SCALEKIT_CLIENT_ID!,
  process.env.SCALEKIT_CLIENT_SECRET!
);

const options: AuthorizationUrlOptions = {
  scopes: ['openid', 'profile', 'email'],
};

const authResult: AuthenticationResponse = await scalekit.authenticateWithCode(
  code,
  redirectUri
);

Framework Examples

Express.js

Complete Express.js integration example:

app.js

import express from 'express';
import cookieParser from 'cookie-parser';
import session from 'express-session';
import { Scalekit } from '@scalekit-sdk/node';

const app = express();
app.use(cookieParser());
app.use(session({
  secret: process.env.SESSION_SECRET,
  resave: false,
  saveUninitialized: false,
}));

const scalekit = new Scalekit(
  process.env.SCALEKIT_ENVIRONMENT_URL,
  process.env.SCALEKIT_CLIENT_ID,
  process.env.SCALEKIT_CLIENT_SECRET
);

// Login route
app.get('/login', (req, res) => {
  const state = generateState();
  req.session.oauthState = state;

  const url = scalekit.getAuthorizationUrl(
    'https://yourapp.com/auth/callback',
    { scopes: ['openid', 'profile', 'email'], state }
  );

  res.redirect(url);
});

// Callback route
app.get('/auth/callback', async (req, res) => {
  const { code, state } = req.query;

  if (state !== req.session.oauthState) {
    return res.status(400).send('Invalid state');
  }

  const authResult = await scalekit.authenticateWithCode(
    code,
    'https://yourapp.com/auth/callback'
  );

  req.session.user = authResult.user;
  res.redirect('/dashboard');
});

Next.js

Next.js API route example:

pages/api/auth/callback.js

import { scalekit } from '@/lib/scalekit';

export default async function handler(req, res) {
  const { code } = req.query;

  try {
    const authResult = await scalekit.authenticateWithCode(
      code,
      `${process.env.NEXT_PUBLIC_APP_URL}/api/auth/callback`
    );

    // Set secure cookie
    res.setHeader('Set-Cookie', [
      `accessToken=${authResult.accessToken}; HttpOnly; Secure; SameSite=Strict; Path=/; Max-Age=${authResult.expiresIn}`,
    ]);

    res.redirect('/dashboard');
  } catch (error) {
    res.status(401).json({ error: 'Authentication failed' });
  }
}

Official SDKs

SDK Features

Installation

Quick Start

Core Methods

Generate Authorization URL

Exchange Authorization Code

Validate Access Token

Refresh Access Token

Organization Management

Create Organization

Generate Admin Portal Link

Session Management

Get Session Details

List User Sessions

Revoke Session

Revoke All User Sessions

Advanced Features

Custom Authorization Options

Error Handling

TypeScript Support

Framework Examples

Express.js

Next.js

Resources

Official SDKs

SDK Features

Documentation Index

​Installation

​Quick Start

​Core Methods

​Generate Authorization URL

​Exchange Authorization Code

​Validate Access Token

​Refresh Access Token

​Organization Management

​Create Organization

​Generate Admin Portal Link

​Session Management

​Get Session Details

​List User Sessions

​Revoke Session

​Revoke All User Sessions

​Advanced Features

​Custom Authorization Options

​Error Handling

​TypeScript Support

​Framework Examples

​Express.js

​Next.js

​Resources

Installation

Quick Start

Core Methods

Generate Authorization URL

Exchange Authorization Code

Validate Access Token

Refresh Access Token

Organization Management

Create Organization

Generate Admin Portal Link

Session Management

Get Session Details

List User Sessions

Revoke Session

Revoke All User Sessions

Advanced Features

Custom Authorization Options

Error Handling

TypeScript Support

Framework Examples

Express.js

Next.js

Resources