OAuth Endpoints Reference¶

import {
  generatePKCE,
  buildAuthorizeUrl,
  generateState,
} from '@authvital/sdk/server';

// === SERVER-SIDE (Express/Node.js) ===

// Step 1: Generate PKCE and state
app.get('/auth/login', (req, res) => {
  const { codeVerifier, codeChallenge } = generatePKCE();
  const state = generateState();

  // Store in server-side session (Express session, Redis, etc.)
  req.session.pkce_verifier = codeVerifier;
  req.session.oauth_state = state;

  // Build and redirect to authorization URL
  const authorizeUrl = buildAuthorizeUrl({
    authVitalHost: 'https://auth.example.com',
    clientId: 'your-client-id',
    redirectUri: 'https://app.example.com/callback',
    codeChallenge,
    codeChallengeMethod: 'S256',
    scope: 'openid profile email offline_access',
    state,
  });

  res.redirect(authorizeUrl);
});

// === BROWSER-SIDE (SPA) ===
// If building a pure SPA without a backend session:

// Store in sessionStorage (cleared on tab close - more secure than localStorage)
sessionStorage.setItem('pkce_verifier', codeVerifier);
sessionStorage.setItem('oauth_state', state);

// Redirect to authorize URL
window.location.href = authorizeUrl;

import { exchangeCodeForTokens } from '@authvital/sdk/server';

// In your callback handler
app.get('/callback', async (req, res) => {
  const { code, state } = req.query;

  // Verify state matches (CSRF protection)
  if (state !== req.session.oauth_state) {
    return res.status(400).json({ error: 'State mismatch' });
  }

  // Exchange code for tokens (SDK handles PKCE automatically)
  const tokens = await exchangeCodeForTokens({
    authVitalHost: process.env.AUTHVITAL_HOST!,
    clientId: process.env.AUTHVITAL_CLIENT_ID!,
    code: code as string,
    codeVerifier: req.session.pkce_verifier,
    redirectUri: 'https://app.example.com/callback',
  });

  // Set httpOnly cookie and redirect
  res.cookie('access_token', tokens.access_token, { httpOnly: true, secure: true });
  res.redirect('/dashboard');
});

import { refreshAccessToken } from '@authvital/sdk/server';

const newTokens = await refreshAccessToken({
  authVitalHost: process.env.AUTHVITAL_HOST!,
  clientId: process.env.AUTHVITAL_CLIENT_ID!,
  refreshToken: storedRefreshToken,
});

// Important: Store the new refresh token (AuthVital rotates them)
storeRefreshToken(newTokens.refresh_token);

import { createAuthVital } from '@authvital/sdk/server';

// The SDK handles client_credentials automatically for M2M calls
const authvital = createAuthVital({
  authVitalHost: process.env.AUTHVITAL_HOST!,
  clientId: process.env.AUTHVITAL_CLIENT_ID!,
  clientSecret: process.env.AUTHVITAL_CLIENT_SECRET!,
});

// For user-context operations, pass the request (JWT is extracted automatically):
const members = await authvital.memberships.listForTenant(req);

// For admin/M2M operations without user context, use the admin namespace:
const settings = await authvital.admin.getInstanceSettings();

// Or for tenant-specific M2M operations, use the licenses admin methods:
const overview = await authvital.licenses.getTenantOverview('tenant-123');