DEV Community: Saif

Enterprise Auth in Astro without the pain

Saif — Wed, 25 Mar 2026 01:35:05 +0000

A complete, production-oriented walkthrough of adding SSO, social login, magic links, and session management to your Astro application using Scalekit — the auth platform built for B2B and AI apps.

Why Scalekit for B2B auth?
Core concepts: OAuth 2.0, OIDC, and the token trio
Project setup & environment
Initializing the Scalekit client
The three auth endpoints
Session middleware — the right way
Protecting pages and API routes
Enterprise SSO: per-organization connections
PKCE flow (no client secret)
Production best practices
Troubleshooting common gotchas

Why Scalekit for B2B auth?

Shipping authentication feels deceptively simple: throw in a social login button, store a JWT, call it done. That works fine for consumer apps. But the moment your first enterprise prospect lands, everything changes. They need to log in via their company's Okta or Entra ID. Their IT team will ask whether you support SCIM. Their security team wants to audit every login event. And their procurement team won't sign off until you can prove SOC 2 compliance.

In 7 out of 10 enterprise deals, authentication requirements like SSO are deal-breakers. Teams that deprioritize this until they're deep in a sales cycle often spend months scrambling to retrofit auth — all while the deal sits on ice.

Scalekit is designed to short-circuit that. It is an authentication platform built specifically for the B2B and AI application layer: it handles the full OAuth 2.0 / OIDC handshake, supports SAML and OIDC enterprise SSO out of the box, includes SCIM provisioning, social logins, magic links, and MFA — and exposes all of it through a single, tightly typed SDK. You get back tokens and a user profile; the heavy lifting stays on Scalekit's side.

A single Scalekit environment can serve multiple applications (e.g., app.yourcompany.com and docs.yourcompany.com), so users authenticate once and share the same session across all of your properties. This matters especially for teams building content sites, documentation portals, or companion apps alongside a primary SaaS dashboard — a very common Astro pattern.

💡 Scalekit's philosophy: You should not need to become an identity expert to ship enterprise-grade auth. Scalekit handles SAML assertion validation, OIDC discovery, token rotation, and IdP quirks so your team can stay focused on the product.

Core concepts: OAuth 2.0, OIDC, and the token trio

Before touching code, grounding the concepts pays dividends when you're debugging at midnight before a launch. Scalekit's auth surface is built on standard protocols — nothing proprietary, nothing that locks you in.

The Authorization Code Flow

This is the flow you'll use for server-rendered Astro apps. Your server never exposes a client secret to the browser. The user is redirected to Scalekit, authenticates, and Scalekit sends a short-lived authorization code back to your callback URL. Your server exchanges that code for three tokens.

Browser → /api/auth/login → Scalekit (IdP / SSO) → /api/auth/callback → HttpOnly Cookies

The token trio

Scalekit returns three tokens on a successful exchange. Understanding their purpose determines how you store and use them:

Token	Purpose	Typical lifetime	Where to store
`idToken`	Identifies the user (name, email, sub). Used for logout hint.	1 hour	HttpOnly cookie
`accessToken`	Authorizes API calls. Validated server-side on every request.	15–60 minutes	HttpOnly cookie
`refreshToken`	Obtains a new access token without re-authentication.	Days to weeks	HttpOnly cookie (secure)

⚠️ Never store tokens in localStorage. localStorage and sessionStorage are accessible from any JavaScript running on your page, making them vulnerable to XSS attacks. Always use HttpOnly cookies on the server side. Astro's cookie API makes this trivial.

SAML vs. OIDC — which does your enterprise customer need?

Scalekit abstracts this decision for you: it accepts SAML assertions from enterprise IdPs like Okta and Entra ID and converts them into standard OIDC tokens before returning them to your app. You write OIDC code once; Scalekit handles the protocol translation. That said, knowing the landscape helps when a customer's IT team comes calling:

Protocol	Format	Common use case	Scalekit support
SAML 2.0	XML assertions	Enterprise SSO (Okta, Entra ID, ADFS)	✅ Full
OIDC	JWT tokens	Modern SSO, social login, API auth	✅ Full
OAuth 2.0	Bearer tokens	API authorization	✅ Full

Project setup & environment

Prerequisites

A Scalekit account — free tier includes 1M MAUs, 100 organizations, 1 SSO + 1 SCIM connection
An Astro project (v4 or v5) with output: 'server' configured
Node.js ≥ 18 (the SDK uses native fetch and crypto)
Your Scalekit environment URL, client ID, and client secret from the dashboard

Create the Astro project

# Scaffold a new Astro project
npm create astro@latest my-app -- --template minimal
cd my-app

# Install Scalekit SDK and the Node.js adapter
npm install @scalekit-sdk/node @astrojs/node

Configure server-side rendering

Scalekit's auth flow requires server-side code to exchange tokens and set cookies. Astro's default output: 'static' mode won't work for auth endpoints. You need output: 'server' with the Node adapter:

// astro.config.mjs
import { defineConfig } from 'astro/config';
import node from '@astrojs/node';

export default defineConfig({
  output: 'server',
  adapter: node({ mode: 'standalone' }),
});

ℹ️ Hybrid rendering: If you're using output: 'static' for most of your site but want SSR for auth, you can use hybrid mode: set output: 'static' globally and add export const prerender = false to each auth endpoint file. The behavior is identical.

Environment variables

Add your Scalekit credentials to .env. Never commit this file — add it to .gitignore.

# .env
SCALEKIT_ENVIRONMENT_URL=https://<your-env>.scalekit.cloud
SCALEKIT_CLIENT_ID=skc_<your-client-id>
SCALEKIT_CLIENT_SECRET=sks_<your-secret>
SCALEKIT_REDIRECT_URI=http://localhost:4321/api/auth/callback

TypeScript types and IntelliSense

Declare the env variables and the App.Locals shape so TypeScript can type-check your middleware and Astro pages throughout the project:

// src/env.d.ts
/// <reference types="astro/client" />

interface ImportMetaEnv {
  readonly SCALEKIT_ENVIRONMENT_URL: string;
  readonly SCALEKIT_CLIENT_ID: string;
  readonly SCALEKIT_CLIENT_SECRET: string;
  readonly SCALEKIT_REDIRECT_URI: string;
}

interface ImportMeta {
  readonly env: ImportMetaEnv;
}

declare namespace App {
  interface Locals {
    user?: {
      sub: string;
      email?: string;
      name?: string;
      orgId?: string; // available when using enterprise SSO
    };
  }
}

Initializing the Scalekit client

Create a singleton client so the SDK doesn't re-initialize on every request. Astro's server modules are cached between requests, so a module-level export is the right pattern:

// src/lib/scalekit.ts
import { ScalekitClient } from '@scalekit-sdk/node';

// Singleton — instantiated once, reused across requests
export const scalekit = new ScalekitClient(
  import.meta.env.SCALEKIT_ENVIRONMENT_URL,
  import.meta.env.SCALEKIT_CLIENT_ID,
  import.meta.env.SCALEKIT_CLIENT_SECRET,
);

export const REDIRECT_URI =
  import.meta.env.SCALEKIT_REDIRECT_URI
  ?? 'http://localhost:4321/api/auth/callback';

💡 Validate at startup: In production, wrap the ScalekitClient constructor in a guard that throws if any of the three required env vars are missing. Missing credentials fail silently in some configurations and produce confusing 401 errors at runtime.

The three auth endpoints

The entire auth flow is orchestrated through three API routes. Think of them as a clean boundary: the browser never touches tokens, and your Astro pages never call Scalekit directly. All sensitive work stays server-side.

src/pages/api/auth/
  login.ts     ← generates the authorization URL, redirects user
  callback.ts  ← exchanges code for tokens, sets cookies
  logout.ts    ← clears cookies, ends Scalekit session

login.ts — initiating the flow

The login route's only job is to redirect the user to Scalekit's authorization endpoint. The SDK builds the URL — including the correct state parameter, code challenge (if using PKCE), and any login hints you want to pass:

// src/pages/api/auth/login.ts
import type { APIRoute } from 'astro';
import { scalekit, REDIRECT_URI } from '../../../lib/scalekit';

export const GET: APIRoute = async ({ request }) => {
  // Optional: pass organizationId for direct IdP routing (enterprise SSO)
  const url = new URL(request.url);
  const orgId = url.searchParams.get('orgId') ?? undefined;

  const authUrl = scalekit.getAuthorizationUrl(REDIRECT_URI, {
    scopes: ['openid', 'profile', 'email', 'offline_access'],
    // Route directly to an enterprise IdP by org:
    ...(orgId && { organizationId: orgId }),
  });

  return Response.redirect(authUrl);
};

ℹ️ offline_access scope: Including offline_access in the scopes array instructs Scalekit to return a refresh token. Without it, users will need to re-authenticate every time the access token expires. Always include it for production applications.

callback.ts — exchanging the code for tokens

After the user authenticates, Scalekit redirects back to this endpoint with a one-time authorization code. The server exchanges it for tokens using the client secret — a step that cannot happen in the browser because it requires the secret. Tokens are then stored as HttpOnly cookies:

// src/pages/api/auth/callback.ts
import type { APIRoute } from 'astro';
import { scalekit, REDIRECT_URI } from '../../../lib/scalekit';

export const GET: APIRoute = async ({ request, cookies }) => {
  const url = new URL(request.url);
  const code = url.searchParams.get('code');
  const error = url.searchParams.get('error');

  // Handle errors gracefully — Scalekit sends them as query params
  if (error) {
    const desc = url.searchParams.get('error_description') ?? error;
    return Response.redirect(new URL(`/?error=${encodeURIComponent(desc)}`, url.origin).href);
  }

  if (!code) {
    return Response.redirect(new URL('/', url.origin).href);
  }

  try {
    const { user, idToken, accessToken, refreshToken } =
      await scalekit.authenticateWithCode(code, REDIRECT_URI);

    const secure = url.protocol === 'https:';
    const cookieOptions = {
      httpOnly: true,
      path: '/',
      sameSite: 'lax' as const,
      secure,
      // Set expiry to match the refresh token lifetime
      maxAge: 60 * 60 * 24 * 7, // 7 days
    };

    cookies.set('sk-id-token', idToken, cookieOptions);
    cookies.set('sk-access-token', accessToken, cookieOptions);
    cookies.set('sk-refresh-token', refreshToken, cookieOptions);

    // Redirect to a post-login destination (support ?next= param)
    const next = url.searchParams.get('next') ?? '/';
    return Response.redirect(new URL(next, url.origin).href);
  } catch (err) {
    console.error('[scalekit] token exchange failed', err);
    return Response.redirect(new URL('/?error=auth_failed', url.origin).href);
  }
};

logout.ts — ending the session correctly

Logout is a two-step process: clear your local cookies, then redirect to Scalekit's logout endpoint so it terminates the session on its side too. Skipping the second step means users can return to Scalekit and silently re-authenticate without entering credentials again — not what you want.

// src/pages/api/auth/logout.ts
import type { APIRoute } from 'astro';
import { scalekit } from '../../../lib/scalekit';

export const GET: APIRoute = async ({ request, cookies }) => {
  const idToken = cookies.get('sk-id-token')?.value;

  // Step 1: clear local session cookies
  const deleteOpts = { path: '/' };
  cookies.delete('sk-id-token', deleteOpts);
  cookies.delete('sk-access-token', deleteOpts);
  cookies.delete('sk-refresh-token', deleteOpts);

  // Step 2: redirect to Scalekit's logout endpoint
  const origin = new URL(request.url).origin;
  const logoutUrl = scalekit.getLogoutUrl({
    idTokenHint: idToken,
    postLogoutRedirectUri: origin,
  });

  return Response.redirect(logoutUrl);
};

⚠️ Register your post-logout redirect URI. The postLogoutRedirectUri must be registered in your Scalekit dashboard under Settings → Redirects. If it's not allowlisted, Scalekit will reject the logout request and the user will land on an error page.

Session middleware — the right way

Astro middleware runs on every incoming request before any page or API route handler fires. This is the right place to validate the session and populate Astro.locals.user. Do it once, centrally, and every page in your app benefits automatically.

The middleware below implements a two-stage validation: try the access token first, fall back to the refresh token if it's expired, and clear the session if both fail. This gives users seamless silent sessions without constant re-authentication:

// src/middleware.ts
import { defineMiddleware } from 'astro:middleware';
import type { IdTokenClaim } from '@scalekit-sdk/node';
import { scalekit } from './lib/scalekit';

const clearSession = (cookies: any) => {
  cookies.delete('sk-id-token', { path: '/' });
  cookies.delete('sk-access-token', { path: '/' });
  cookies.delete('sk-refresh-token', { path: '/' });
};

export const onRequest = defineMiddleware(async (context, next) => {
  const { pathname } = context.url;

  // Skip auth check for public assets and auth routes
  if (
    pathname.startsWith('/api/auth') ||
    pathname.startsWith('/_astro') ||
    pathname.match(/\.(ico|png|jpg|svg|css|js|woff2?)$/)
  ) {
    return next();
  }

  const accessToken = context.cookies.get('sk-access-token')?.value;

  if (!accessToken) return next();

  try {
    // Fast path: access token is still valid
    const claims = await scalekit.validateToken<IdTokenClaim>(accessToken);
    context.locals.user = {
      sub: claims.sub,
      email: claims.email,
      name: claims.name,
    };
  } catch {
    // Slow path: token expired — try refresh
    const refreshToken = context.cookies.get('sk-refresh-token')?.value;

    if (!refreshToken) {
      clearSession(context.cookies);
      return next();
    }

    try {
      const { accessToken: newToken } =
        await scalekit.refreshAccessToken(refreshToken);

      const secure = new URL(context.request.url).protocol === 'https:';
      context.cookies.set('sk-access-token', newToken, {
        httpOnly: true,
        path: '/',
        sameSite: 'lax',
        secure,
        maxAge: 60 * 60, // new access token: 1 hour
      });

      const claims = await scalekit.validateToken<IdTokenClaim>(newToken);
      context.locals.user = {
        sub: claims.sub,
        email: claims.email,
        name: claims.name,
      };
    } catch {
      // Refresh also failed — wipe everything
      clearSession(context.cookies);
    }
  }

  return next();
});

💡 Skip middleware on auth routes. Notice the early return at the top for /api/auth/*, /_astro, and static file extensions. Without this, the middleware runs on the callback endpoint before cookies are set, causing unnecessary validation overhead on unauthenticated requests.

Protecting pages and API routes

Once the middleware populates Astro.locals.user, protecting a page is just a conditional redirect in the frontmatter. No wrapper components, no higher-order functions — just plain server logic.

Protected page pattern

---
// src/pages/dashboard.astro
import Layout from '../layouts/Layout.astro';

const user = Astro.locals.user;
// Redirect unauthenticated users back through login, preserving the destination
if (!user) {
  return Astro.redirect(`/api/auth/login?next=${encodeURIComponent('/dashboard')}`);
}
---
<Layout title="Dashboard">
  <h1>Welcome, {user.name ?? user.email}</h1>
  <p>You're signed in. <a href="/api/auth/logout">Sign out</a></p>
</Layout>

Protected API route pattern

// src/pages/api/data.ts
import type { APIRoute } from 'astro';

export const GET: APIRoute = ({ locals }) => {
  if (!locals.user) {
    return new Response(JSON.stringify({ error: 'Unauthorized' }), {
      status: 401,
      headers: { 'Content-Type': 'application/json' },
    });
  }

  return new Response(JSON.stringify({
    user: locals.user,
    data: '… your data …',
  }), {
    headers: { 'Content-Type': 'application/json' },
  });
};

Navigation component

A nav component that adapts to auth state is a common need. Since it's an Astro component (server-rendered), you can read Astro.locals.user directly — no client-side JS required:

---
// src/components/AuthNav.astro
const user = Astro.locals.user;
---
<nav>
  {user ? (
    <>
      <span>{user.name ?? user.email}</span>
      <a href="/api/auth/logout">Sign out</a>
    </>
  ) : (
    <a href="/api/auth/login">Sign in</a>
  )}
</nav>

Enterprise SSO: per-organization connections

One of Scalekit's headline capabilities is letting each of your enterprise customers connect their own IdP — Okta, Microsoft Entra ID, Google Workspace, PingFederate, ADFS — without you writing any IdP-specific code. Scalekit stores the per-org SSO configuration and does the SAML/OIDC handshake transparently.

From your application's perspective, you simply pass an organizationId (or a loginHint email domain) when generating the authorization URL, and Scalekit routes the user to the correct IdP automatically:

// src/pages/api/auth/login.ts — enterprise routing
export const GET: APIRoute = async ({ request }) => {
  const url = new URL(request.url);

  // Option A: route by org ID (stored in your DB after org onboarding)
  const orgId = url.searchParams.get('orgId');

  // Option B: route by email domain (Scalekit resolves IdP from domain)
  const loginHint = url.searchParams.get('email');

  const authUrl = scalekit.getAuthorizationUrl(REDIRECT_URI, {
    scopes: ['openid', 'profile', 'email', 'offline_access'],
    ...(orgId && { organizationId: orgId }),
    ...(loginHint && { loginHint }),
  });

  return Response.redirect(authUrl);
};

The org-aware login form

A typical enterprise login UX asks for a work email, resolves the org from the domain, and redirects silently into SSO. No custom IdP UI needed on your end:

---
// src/pages/login.astro
const error = Astro.url.searchParams.get('error');
---
<form action="/api/auth/login" method="GET">
  <label>
    Work email
    <input type="email" name="email" required placeholder="you@company.com" />
  </label>
  <button type="submit">Continue with SSO</button>
  {error && <p class="error">{decodeURIComponent(error)}</p>}
</form>

<p><a href="/api/auth/login">Or sign in with Google / GitHub</a></p>

💡 IdP-initiated SSO: Some enterprise IdPs can initiate SSO by pushing an assertion to your app without the user visiting your login page first (common in Okta app launchers). Scalekit handles this scenario. In your callback handler, if the code exchange succeeds but there's no state parameter in the redirect, you're in an IdP-initiated flow. Validate carefully and redirect to a safe default post-login destination.

Reading org context from the token

After a successful SSO authentication, the decoded access token claims will include the user's orgId. Use this to scope database queries and enforce multi-tenant isolation:

// src/middleware.ts — extended claims
const claims = await scalekit.validateToken<IdTokenClaim>(accessToken);
context.locals.user = {
  sub: claims.sub,
  email: claims.email,
  name: claims.name,
  orgId: (claims as any).org_id, // available on enterprise SSO logins
};

PKCE flow (no client secret)

The Authorization Code flow with a client secret is ideal for traditional SSR apps like Astro in server mode. But there are scenarios where you won't have — or don't want — a secret: Astro's hybrid/static mode with edge functions, or an open-source site where the server code is public. In those cases, use PKCE (Proof Key for Code Exchange).

PKCE replaces the client secret with a cryptographic challenge/verifier pair generated fresh per-request. Scalekit's developer docs site itself is an open-source Astro project that uses PKCE — it's a real-world reference you can study.

Step	Authorization Code + Secret	PKCE (no secret)
Code generation	SDK builds URL, secret on server	SDK generates `code_verifier` + `code_challenge`
Verifier storage	N/A	Session cookie or server-side store
Token exchange	`code` + `secret`	`code` + `code_verifier`
Best for	SSR Astro (server mode)	Edge, static hybrid, public repos

// src/pages/api/auth/login.ts — PKCE variant
import { generatePkce } from '@scalekit-sdk/node'; // or your own crypto util

export const GET: APIRoute = async ({ request, cookies }) => {
  const { codeVerifier, codeChallenge } = await generatePkce();

  // Store verifier server-side — needed at callback
  cookies.set('pkce-verifier', codeVerifier, {
    httpOnly: true, path: '/', sameSite: 'lax', maxAge: 300,
  });

  const authUrl = scalekit.getAuthorizationUrl(REDIRECT_URI, {
    scopes: ['openid', 'profile', 'email', 'offline_access'],
    codeChallenge,
    codeChallengeMethod: 'S256',
  });

  return Response.redirect(authUrl);
};

Production best practices

BP 01 — Always set Secure + HttpOnly + SameSite on cookies
All three attributes together block the main vectors of session hijacking. SameSite: 'lax' is the right default — it allows top-level navigations but blocks cross-site POSTs.

BP 02 — Validate the access token on every request
Never trust a cookie value without cryptographic validation. The SDK's validateToken() verifies the signature and expiry. This check is fast — it's local JWT verification with no network call.

BP 03 — Rotate tokens silently with refresh
The middleware's fallback to refreshAccessToken() keeps users logged in seamlessly for the lifetime of the refresh token. Always store the refresh token in an HttpOnly cookie.

BP 04 — Implement post-login redirect with ?next=
When a user hits a protected page unauthenticated, store their intended URL and restore it after login. Otherwise you always land on the home page, frustrating deep-link sharing.

BP 05 — Handle errors in the callback, not with crashes
Scalekit sends ?error=&error_description= to your callback URL on failure (cancelled login, misconfigured IdP). Always check for these and redirect gracefully rather than letting the exchange throw.

BP 06 — Register all redirect URIs before deploying
Scalekit validates every redirect URI against a strict allowlist. Add your production, staging, and preview URLs in the dashboard before deploying. Mismatched URIs are the #1 cause of auth failures at launch.

BP 07 — Use environment-specific Scalekit environments
Scalekit supports multiple environments (dev, staging, prod) with separate credentials and SSO connections. Never use the same environment URL for local development and production.

BP 08 — Multi-tenant isolation via orgId
When enterprise SSO is used, the token includes org_id. Always scope database queries and API calls to this value. Never let a user from Org A read data from Org B by trusting only the sub claim.

Security headers

Beyond token security, add HTTP security headers to your Astro middleware. These are complementary to auth, not a substitute:

// src/middleware.ts — security headers addition
// At the end of your middleware, before returning next()
const response = await next();
response.headers.set('X-Frame-Options', 'DENY');
response.headers.set('X-Content-Type-Options', 'nosniff');
response.headers.set('Referrer-Policy', 'strict-origin-when-cross-origin');
response.headers.set(
  'Content-Security-Policy',
  "default-src 'self'; script-src 'self'; connect-src 'self' https://*.scalekit.cloud;",
);
return response;

Troubleshooting common gotchas

`redirect_uri_mismatch`

This is the single most common error. Scalekit requires the redirect URI in the authorization request to exactly match a registered URI — including trailing slashes, protocol, and port. Check:

The URI in your .env matches what's registered in the Scalekit dashboard
You're not accidentally including or omitting a trailing slash
In development, the port (4321) is correct and not being remapped
In production, you've added the https:// version, not just http://

Token validation fails after deployment

validateToken() checks the token's iss claim against your environment URL. If your SCALEKIT_ENVIRONMENT_URL has a trailing slash in one place and not another, validation will fail. Normalize it: strip trailing slashes before passing to the client constructor.

Refresh token not returned

If refreshToken is undefined after the code exchange, you forgot to include offline_access in your scopes. Update your login endpoint's scopes array and test with a fresh login (existing tokens won't gain offline_access retroactively).

Middleware runs on static assets

Astro middleware runs before static file serving in some adapter configurations. Add an early return for paths you know are static (the example in Section 6 already includes this). If you're still seeing performance issues, verify your adapter version.

Enterprise SSO user not found in your database

The first time a user logs in via enterprise SSO, they may not have a row in your database. The sub claim is the stable identifier — it won't change even if the user changes their email. On first login, use it as the primary key to create a new user record. Treat this as a just-in-time (JIT) provisioning pattern — a common B2B requirement when SCIM is not yet configured.

Putting it all together

Here's the final file structure for a complete Scalekit + Astro authentication setup. Everything fits in a handful of files — no auth framework configuration DSLs, no provider callback soup:

src/
  lib/
    scalekit.ts          ← SDK singleton + REDIRECT_URI
  pages/
    api/auth/
      login.ts           ← GET → redirect to Scalekit
      callback.ts        ← GET → exchange code, set cookies
      logout.ts          ← GET → clear cookies, end session
    login.astro          ← Login page with email input
    dashboard.astro      ← Protected page
  components/
    AuthNav.astro        ← Conditional sign in/out nav
  middleware.ts          ← Token validation + silent refresh
  env.d.ts               ← TypeScript env + App.Locals types
.env                     ← SCALEKIT_* credentials (gitignored)
astro.config.mjs         ← output: 'server', adapter: node

Scalekit's value proposition is exactly this compactness. You've added enterprise SSO, social login, magic link support, SCIM-ready organization management, token rotation, and production-grade session handling — and you haven't written a single line of SAML parsing, JWT signing, or PKCE crypto yourself. The auth complexity lives inside Scalekit's infrastructure; your codebase stays readable.

🚀 Next steps: Once auth is running, the natural next steps in a B2B application are SCIM provisioning (so your enterprise customers can auto-provision and deprovision users from their IdP), organization management APIs (invite flows, role assignment), and Auth Logs for audit trails. All are available in Scalekit — the same SDK, same environment, no new dependencies.

Resources

Scalekit developer docs — docs.scalekit.com
Node.js SDK source — github.com/scalekit-inc/scalekit-sdk-node
Astro example with Authorization Code flow — github.com/scalekit-developers/astro-scalekit-auth-example
Scalekit developer docs site (PKCE, no SDK) — github.com/scalekit-inc/developer-docs
Astro on-demand rendering guide — docs.astro.build/en/guides/on-demand-rendering

Written for the Scalekit developer community · scalekit.com

Add Enterprise SSO to Your Next.js App in Minutes Using Claude Code & Scalekit

Saif — Tue, 24 Mar 2026 04:13:07 +0000

The old way: Spend hours reading OAuth documentation, configuring SAML endpoints, building login flows, handling token validation, and creating admin portals for your enterprise customers.

The new way: Describe what you want in plain English. Let Claude Code and Scalekit's plugin do the rest.

This guide shows you how to add production-ready enterprise Single Sign-On to a Next.js application using Claude Code's plugin ecosystem—going from zero to a working SSO flow with customer self-service portal in under 10 minutes.

What You're Building
Understanding the Plugin Architecture
Prerequisites
Step-by-Step Implementation
Testing with the IDP Simulator
How It Actually Works
Production Considerations
Alternative: Using Other AI Coding Agents
Why This Matters

What You're Building

By the end of this guide, you'll have:

1. Enterprise SSO Authentication Flow

Users enter their work email (user@company.com)
Automatic redirect to their organization's identity provider (Microsoft Entra ID, Okta, Google Workspace, etc.)
Secure callback handling with token validation
Session creation with verified user identity

2. Self-Service Admin Portal

Your B2B customers configure their own IDP connections
No engineering involvement needed for enterprise onboarding
Support for SAML and OIDC protocols
Real-time connection status monitoring

3. Production-Ready Code

Environment-based configuration
Proper error handling
Security best practices baked in
Next.js App Router patterns

Understanding the Plugin Architecture

Before we dive in, let's understand what makes this possible.

What Are Claude Code Plugins?

Claude Code plugins are packaged bundles of capabilities that extend what Claude can do. Think of them as specialized skill packs that teach Claude how to work with specific services, frameworks, or patterns.

A plugin can contain:

Skills: Context-aware instruction sets Claude automatically uses when relevant
MCP Servers: Connections to external APIs and services via Model Context Protocol
Commands: Slash commands you invoke manually (e.g., /deploy)
Subagents: Specialized AI agents for specific tasks (e.g., security review)
Hooks: Scripts that run on specific events (pre-commit, post-deployment)

How Scalekit's Plugin Works

The Scalekit Auth Stack plugin gives Claude Code:

Documentation Access: Real-time access to Scalekit's implementation guides via MCP
API Integration: Ability to query your Scalekit environment, retrieve config, manage connections
Implementation Patterns: Battle-tested code patterns for SSO flows, session management, and security
Framework Knowledge: How to properly integrate with Next.js, Express, FastAPI, and other frameworks

When you ask Claude to "add SSO," it:

Reads your existing codebase structure
Pulls relevant Scalekit documentation
Queries your Scalekit environment via MCP
Generates complete, working code that follows your project's patterns

Prerequisites

Required:

A Next.js application (even a fresh create-next-app works)
Claude Code installed and configured
A Scalekit account with dashboard access

You'll need from Scalekit:

Environment URL (e.g., https://yourenv.scalekit.com)
Client ID (from your Scalekit dashboard)
Client Secret (generate in dashboard, keep secure)

Time investment: ~10 minutes

Step-by-Step Implementation

Step 1: Install the Scalekit Plugin

Open your terminal and start the Claude Code REPL:

claude

Add the Scalekit Auth Stack marketplace:

/plugin marketplace add scalekit-inc/claude-code-authstack

You should see confirmation:

❯ /plugin marketplace add scalekit-inc/claude-code-authstack

⎿  Successfully added marketplace: scalekit-auth-stack

Now install the Modular SSO plugin:

/plugin install modular-sso@scalekit-auth-stack

What just happened?

Claude Code now has access to Scalekit's SSO implementation knowledge
The plugin includes MCP servers that can query your Scalekit environment
Skills are loaded that guide code generation for auth flows

Verify installation:

/plugins

You should see modular-sso in your installed plugins list.

Step 2: Navigate to Your Project

Exit the REPL (Ctrl+D or exit) and navigate to your Next.js project:

cd /path/to/your-nextjs-app

Start Claude Code in your project:

claude

Step 3: Give Claude the Objective

Here's where the magic happens. Paste this prompt:

My goal is to add SSO to my application and also let my customers 
configure SSO connections with their IDP using an admin portal.

Watch Claude work:

Skill Detection: Claude automatically identifies the Modular SSO skill is relevant
Codebase Analysis: Reads your package.json, route structure, and existing patterns
Documentation Retrieval: Fetches Scalekit's implementation guide via MCP
Environment Discovery: Queries your Scalekit account to get environment details
Code Generation: Creates all necessary files following Next.js conventions

You'll see output like:

Loading skill: Modular SSO
Analyzing project structure...
Reading Next.js configuration...
Fetching Scalekit environment configuration...
Found environment: https://yourenv.scalekit.com
Retrieved Client ID: sk_live_...

Step 4: Approve the Redirect URI

Claude will ask permission to configure a redirect URI in your Scalekit environment:

I need to add a redirect URI to your Scalekit environment:
http://localhost:3000/api/auth/callback

Allow? [y/n]

Type y and press Enter.

Why this matters:
The redirect URI is where Scalekit sends users after they authenticate with their IDP. It must be registered for security—preventing malicious sites from receiving your auth callbacks.

Step 5: Add Your Client Secret

Claude will generate a .env.local file with:

SCALEKIT_ENV_URL=https://yourenv.scalekit.com
SCALEKIT_CLIENT_ID=sk_live_abc123...
SCALEKIT_CLIENT_SECRET=

Open your Scalekit dashboard, navigate to Settings → API Keys, and generate a new Client Secret.

Copy it and add to .env.local:

SCALEKIT_CLIENT_SECRET=sk_secret_xyz789...

Security note: Never commit this file. Claude should have added it to .gitignore automatically.

Step 6: Review Generated Files

Claude will have created:

your-app/
├── .env.local                          # Environment configuration
├── app/
│   ├── api/
│   │   └── auth/
│   │       ├── [org]/
│   │       │   └── route.ts           # SSO initiation
│   │       └── callback/
│   │           └── route.ts           # OAuth callback handler
│   ├── login/
│   │   └── page.tsx                   # Login page with email input
│   └── sso-settings/
│       └── page.tsx                   # Admin portal for IDP config
├── lib/
│   └── scalekit.ts                    # Scalekit client initialization
└── middleware.ts                       # Session validation (optional)

Key file: lib/scalekit.ts

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

export const scalekit = new ScalekitClient(
  process.env.SCALEKIT_ENV_URL!,
  process.env.SCALEKIT_CLIENT_ID!,
  process.env.SCALEKIT_CLIENT_SECRET!
);

Key file: app/api/auth/callback/route.ts

import { scalekit } from '@/lib/scalekit';
import { NextRequest } from 'next/server';

export async function GET(request: NextRequest) {
  const searchParams = request.nextUrl.searchParams;
  const code = searchParams.get('code');
  const error = searchParams.get('error');

  if (error) {
    return Response.redirect('/login?error=' + error);
  }

  if (!code) {
    return Response.redirect('/login?error=no_code');
  }

  try {
    // Exchange code for user identity
    const result = await scalekit.authenticateWithCode(
      code,
      request.nextUrl.origin + '/api/auth/callback'
    );

    // Create session with user data
    // (Implementation depends on your session strategy)

    return Response.redirect('/dashboard');
  } catch (err) {
    console.error('Auth error:', err);
    return Response.redirect('/login?error=auth_failed');
  }
}

Step 7: Install Dependencies

Claude should have updated package.json, but verify:

pnpm install
# or npm install, or yarn install

Testing with the IDP Simulator

You don't need a real enterprise IDP to test this. Scalekit provides a built-in simulator.

Start Your Dev Server

pnpm dev

Navigate to http://localhost:3000—you should be redirected to /login.

Use the Test Organization

In your Scalekit dashboard:

Go to Organizations
Find the Test Organization (created by default)
Note it's configured with example.com as an organization domain
The IDP is set to IDP Simulator (simulates Okta/Microsoft/Google)

Test the Flow

On the login page, enter: yourname@example.com
Click Continue
You'll be redirected to the IDP Simulator (looks like a real enterprise login page)
Enter any name in the form
Click Simulate Login

What happens:

Scalekit matches example.com to the Test Organization
Redirects to the configured IDP (Simulator)
Simulator "authenticates" the user
Redirects back to your app at /api/auth/callback?code=...
Your app exchanges the code for user identity
Session is created, user is logged in

Check the Admin Portal

Navigate to http://localhost:3000/sso-settings

You should see:

Connected Identity Providers section
Status of each IDP (Enabled/Disabled)
Available IDPs to configure (Microsoft Entra ID, Okta, Google, etc.)

This is what your enterprise customers will use to self-serve their SSO configuration.

How It Actually Works

Let's demystify what just happened.

The SSO Flow

1. User visits app
   ↓
2. Redirected to /login
   ↓
3. User enters work email: user@acme.com
   ↓
4. App calls Scalekit: "Get SSO URL for acme.com"
   ↓
5. Scalekit checks: Is there an org with domain acme.com?
   ↓
6. If yes: Return IDP login URL for that org
   ↓
7. User redirected to their company's IDP (Okta/Microsoft/etc)
   ↓
8. User authenticates at IDP
   ↓
9. IDP redirects back to: yourapp.com/api/auth/callback?code=xyz
   ↓
10. App exchanges code with Scalekit for user identity
    ↓
11. Scalekit returns: { email, name, organization, ... }
    ↓
12. App creates session, user is logged in

Organization-Based Routing

The key insight: Scalekit routes authentication based on email domain.

When a user enters jane@acme.com:

Scalekit looks up which organization owns acme.com
Retrieves that organization's configured IDP
Returns the appropriate login URL

This is why your B2B customers can each use different IDPs—routing happens automatically per organization.

The Admin Portal

The self-service portal uses Scalekit's management APIs to:

List Organizations: Show the customer their organization details
Configure Connections: Let them set up SAML/OIDC with their IDP
Test Connections: Validate the setup before going live
Manage Domains: Add/remove email domains for their org

All without your engineering team touching anything.

Security Considerations Built In

The generated code includes:

PKCE (Proof Key for Code Exchange): Protects against authorization code interception
State Parameter: Prevents CSRF attacks
Token Validation: Ensures codes haven't been tampered with
Environment-Based Config: Secrets never in version control
HTTPS Enforcement: Redirect URIs must use HTTPS in production

Production Considerations

Environment Variables

For production, set these in your hosting platform (Vercel, AWS, etc.):

SCALEKIT_ENV_URL=https://yourenv.scalekit.com
SCALEKIT_CLIENT_ID=sk_live_...
SCALEKIT_CLIENT_SECRET=sk_secret_...

Update Redirect URIs

In your Scalekit dashboard, add production callback URLs:

https://yourdomain.com/api/auth/callback

Session Management

Claude generates a basic session setup. For production, consider:

Session Storage: Redis, database, or encrypted cookies
Session Lifetime: How long until re-authentication required
Token Refresh: For long-lived sessions
Multi-Device: Handling concurrent sessions

Error Handling

Add user-friendly error messages:

// app/login/page.tsx
const errorMessages = {
  no_code: 'Authentication failed. Please try again.',
  auth_failed: 'Could not verify your identity.',
  invalid_email: 'Please use your work email address.',
  no_org: 'Your organization has not set up SSO yet.'
};

Monitoring

Track:

Failed authentication attempts
Organization-wise SSO usage
IDP connection health
Session creation/destruction

Scalekit provides webhooks for these events.

Alternative: Using Other AI Coding Agents

Scalekit's Auth Stack works with 40+ AI coding agents, not just Claude Code.

GitHub Copilot CLI

# Install marketplace
copilot plugin marketplace add scalekit-inc/github-copilot-authstack

# Install plugin
copilot plugin install modular-sso@scalekit-auth-stack

# Generate implementation
copilot "Add Scalekit SSO to my app with admin portal for customer IDP configuration"

Cursor

Option: Use Claude Code marketplace (works now)

# In Claude Code REPL
/plugin marketplace add scalekit-inc/claude-code-authstack

# Cursor automatically picks up Claude Code plugins
# Open Cursor → Settings → Plugins → Enable Modular SSO

Then use Cursor's chat with Cmd+L / Ctrl+L:

Add Scalekit SSO with customer admin portal for IDP configuration

Any Agent via Vercel Skills

# Interactive install
npx skills add scalekit-inc/skills

# Or list and pick
npx skills add scalekit-inc/skills --list

# Install specific skill
npx skills add scalekit-inc/skills --skill modular-sso

# Global install for all projects
npx skills add scalekit-inc/skills --all --global

Supported agents: Windsurf, Cline, Gemini CLI, OpenCode, Codex, and 30+ others.

Why This Matters

Traditional SSO implementation:

Read OAuth 2.0 / SAML spec (hours)
Study IDP-specific quirks (hours)
Write authorization URL generation (30 min)
Handle callback and token exchange (1 hour)
Build session management (2+ hours)
Create admin UI for IDP config (3+ hours)
Test with multiple IDPs (hours)
Debug edge cases (days)

Total: 1-2 weeks for an experienced developer

With Claude Code + Scalekit:

Install plugin (1 minute)
Describe what you want (30 seconds)
Review generated code (5 minutes)
Test with simulator (2 minutes)

Total: ~10 minutes

The code quality is production-ready because:

The plugin encodes battle-tested patterns from thousands of implementations
It follows your framework's conventions automatically
Security best practices are baked in
Scalekit handles the complex parts (SAML parsing, token validation, IDP integrations)

Conclusion

Enterprise SSO used to be a feature that delayed product launches. Between understanding OAuth flows, handling SAML complexity, and building customer onboarding portals, it was weeks of work.

AI coding agents with specialized plugins collapse that timeline to minutes. But this isn't about AI writing code faster—it's about encoding expert knowledge into reusable skills that handle entire feature implementations.

The Scalekit plugin doesn't just generate boilerplate. It:

Understands your codebase structure
Queries your live environment
Follows security best practices
Creates complete, working flows

This is the new paradigm: describe the outcome, let specialized agents handle the implementation details.

Next steps:

Try it yourself: The fastest way to understand this isn't reading—it's doing. Spin up a fresh Next.js app, install the plugin, and watch Claude build your SSO flow in real-time.

The future of development isn't writing less code. It's describing what you want and having specialized agents that actually understand your domain build it for you.

Have questions? Join the Scalekit's Slack or the Claude Code community.

Multi-Connector OAuth: Meeting Scheduler Agent using Google Calendar, Gmail, Scalekit

Saif — Thu, 12 Mar 2026 10:46:15 +0000

Scheduling a meeting takes three API calls: check availability, create the event, and draft the confirmation.

In a human workflow, those three steps share a session.

In an agent, every tool calling crosses an independent OAuth boundary - and each boundary requires its own token, its own refresh logic, its own error handling.

This is the part of agentic development that doesn't show up in agent demos. The demo shows the agent booking a meeting. The production reality is that you've written token-fetching code three times, your refresh logic has a race condition you'll discover at 2 am, and your error messages could be indistinguishable between "token expired" and "wrong scope."

This cookbook solves that by delegating OAuth lifecycle management to Scalekit entirely, so the agent code is just workflow logic.

What You're Actually Building

A Python agent that:

Authorizes against Google Calendar and Gmail independently
Queries the freeBusy endpoint to find open slots
Creates a calendar event with attendee(s)
Drafts (not sends - more on that), a follow-up email with the event link

The complete source code is in python/meeting_scheduler_agent.py in the agent-auth-examples repo.

Why OAuth Gets Complicated in Multi-Step Agents

Single-API agents are manageable: You fetch a token, store it, and refresh it when it expires. It's boilerplate, but contained boilerplate.

Multi-API agents have a compounding problem. Google Calendar and Gmail use separate OAuth scopes and issue separate access tokens. Your agent must manage both independently, and the failure modes interact in non-obvious ways.

The four OAuth problems that make this harder than it looks:

One token per connector. Calendar and Gmail have different scope requirements and different token lifetimes. You can't share a token between them, and the refresh logic for each has to be independent.
First-run authorization is blocking. If the user hasn't authorized a connector yet, your agent can't proceed until they complete the OAuth flow in a browser. That blocking behavior needs to be handled explicitly - not just as an error case, but as a designed state in the workflow.
Token expiry is silent. A token that worked yesterday fails today, and the failure looks identical to a permissions error. Without explicit expiry tracking, your agent degrades silently.
Chaining tool outputs is fragile. The Calendar API returns an event link. That link needs to appear in the Gmail draft. If the Calendar call succeeds but the Gmail call fails, you have an orphaned calendar event with no follow-up email. The compensation logic is real work.

These aren't edge cases. They're the normal operating conditions of any agent that touches more than one external system.

The Architecture: Delegated OAuth Lifecycle

Scalekit exposes a connected_accounts abstraction: a mapping from a user identifier to an authorized OAuth session per connector. When your agent calls get_or_create_connected_account, Scalekit either returns an existing active session with a valid token or creates a new one and returns an authorization URL. After the user authorizes, get_connected_account returns the token. From that point, Scalekit handles refresh automatically - including rotation, expiry detection, and re-issuance.

The consequence: your agent's authorization step is a single function regardless of which connector you're targeting. Calendar, Gmail, Slack, Jira - the pattern is identical. The connector-specific OAuth complexity lives in Scalekit's infrastructure, not in your agent code.

This is the same principle behind why enterprises centralize OAuth in a gateway rather than distributing token management across individual services. When credentials live in one place, you get consistent refresh handling, consistent revocation, and a coherent audit trail. For an agent, Scalekit is that centralized layer.

Setup

Create a .env file at the project root with your Scalekit credentials:

SCALEKIT_ENVIRONMENT_URL=https://your-env.scalekit.com
SCALEKIT_CLIENT_ID=your-client-id
SCALEKIT_CLIENT_SECRET=your-client-secret

Install dependencies:

pip install scalekit-sdk python-dotenv requests

In the Scalekit Dashboard, create 2 connections:

googlecalendar - Google Calendar OAuth connection
gmail - Gmail OAuth connection

The connection names must match exactly what you pass to authorize(). A mismatch returns an error, not a helpful message.

The Code for Building Meeting Scheduler Agent using Google Calendar, Gmail, and Scalekit

Initialize the Scalekit client

import os
import base64
from datetime import datetime, timezone, timedelta
from email.mime.text import MIMEText

import requests
from dotenv import load_dotenv
from scalekit import ScalekitClient

load_dotenv()

# Never hard-code credentials - they would be exposed in source control
# and CI logs. Pull them from environment variables instead.
scalekit_client = ScalekitClient(
    environment_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"),
    client_id=os.getenv("SCALEKIT_CLIENT_ID"),
    client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),
)

actions = scalekit_client.actions

# Replace with a real user identifier from your application's session
USER_ID = "user_123"
ATTENDEE_EMAIL = "attendee@example.com"
MEETING_TITLE = "Quick Sync"
DURATION_MINUTES = 60
SEARCH_DAYS = 3
WORK_START_HOUR = 9   # UTC
WORK_END_HOUR = 17    # UTC

scalekit_client.actions is the entry point for all connected-account operations. Initialize it once and pass actions to the functions below.

Authorize each connector

The authorize function handles the first-run prompt and returns a valid access token:

def authorize(connector: str) -> str:
    """Ensure the user has an active connected account and return its access token.

    On first run, this prints an authorization URL and waits for the user
    to complete the browser OAuth flow before continuing.
    """
    account = actions.get_or_create_connected_account(connector, USER_ID)

    if account.status != "active":
        auth_link = actions.get_authorization_link(connector, USER_ID)
        print(f"\nOpen this link to authorize {connector}:\n{auth_link}\n")
        input("Press Enter after completing authorization in your browser...")
        account = actions.get_connected_account(connector, USER_ID)

    return account.authorization_details["oauth_token"]["access_token"]

Call this once per connector before any API calls:

calendar_token = authorize("googlecalendar")
gmail_token = authorize("gmail")

After the first successful authorization, get_or_create_connected_account returns status == "active" on subsequent runs and the if block is skipped. Scalekit refreshes expired tokens automatically - you never write refresh logic.

The critical property: this function is identical regardless of which connector you're authorizing. Swap "googlecalendar" for "slack" and the same code handles Slack's OAuth flow, token storage, and refresh lifecycle. The connector-specific behavior lives in Scalekit's configuration, not in your agent.

Query calendar availability

With a valid Calendar token, query the freeBusy endpoint to get the user’s busy intervals:

def get_busy_slots(token: str) -> list[dict]:
    """Fetch busy intervals for the user's primary calendar."""
    now = datetime.now(timezone.utc)
    window_end = now + timedelta(days=SEARCH_DAYS)

    response = requests.post(
        "https://www.googleapis.com/calendar/v3/freeBusy",
        headers={"Authorization": f"Bearer {token}"},
        json={
            "timeMin": now.isoformat(),
            "timeMax": window_end.isoformat(),
            "items": [{"id": "primary"}],
        },
    )
    response.raise_for_status()
    return response.json()["calendars"]["primary"]["busy"]

raise_for_status() converts 4xx and 5xx responses into exceptions. Without it, a 403 from a missing scope fails silently and returns empty busy slots - which means your agent will try to book into a slot that doesn't exist. Always raising an error.

The busy list contains {"start": "...", "end": "..."} dicts in ISO 8601 format.

Find the first open slot

Walk forward in one-hour increments from now and return the first candidate that falls within working hours and does not overlap a busy interval:

def find_free_slot(busy_slots: list[dict]) -> tuple[datetime, datetime] | None:
    """Return the first open one-hour slot during working hours in UTC.

    Returns None if no slot is available in the search window.
    """
    now = datetime.now(timezone.utc)
    # Round up to the next whole hour so the candidate is always in the future
    candidate = now.replace(minute=0, second=0, microsecond=0) + timedelta(hours=1)
    window_end = now + timedelta(days=SEARCH_DAYS)

    while candidate < window_end:
        slot_end = candidate + timedelta(minutes=DURATION_MINUTES)

        if WORK_START_HOUR <= candidate.hour < WORK_END_HOUR:
            overlap = any(
                candidate < datetime.fromisoformat(b["end"])
                and slot_end > datetime.fromisoformat(b["start"])
                for b in busy_slots
            )
            if not overlap:
                return candidate, slot_end

        candidate += timedelta(hours=1)

    return None

This is a deliberate first-draft implementation: one-hour granularity, UTC-only, primary calendar. The limits are real and addressed in the production notes below - but starting simple makes the logic auditable. You can see exactly what the agent will do before it does it.

Create the calendar event

Post the event to the Google Calendar API and return its HTML link, which you’ll include in the email draft:

def create_event(token: str, start: datetime, end: datetime) -> str:
    """Create a calendar event and return its HTML link."""
    response = requests.post(
        "https://www.googleapis.com/calendar/v3/calendars/primary/events",
        headers={"Authorization": f"Bearer {token}"},
        json={
            "summary": MEETING_TITLE,
            "description": "Scheduled by agent",
            "start": {"dateTime": start.isoformat(), "timeZone": "UTC"},
            "end": {"dateTime": end.isoformat(), "timeZone": "UTC"},
            "attendees": [{"email": ATTENDEE_EMAIL}],
        },
    )
    response.raise_for_status()
    return response.json()["htmlLink"]

The htmlLink in the response is the calendar event URL. Google sends an invitation to each attendee automatically - the draft in the next step is a separate follow-up, not a duplicate of the invitation.

Draft the confirmation email

def create_draft(token: str, event_link: str, start: datetime) -> None:
    """Create a Gmail draft with the meeting details."""
    body = (
        f"Hi,\n\n"
        f"I've scheduled '{MEETING_TITLE}' for "
        f"{start.strftime('%A, %B %d at %H:%M UTC')} ({DURATION_MINUTES} min).\n\n"
        f"Calendar link: {event_link}\n\n"
        f"Looking forward to it!"
    )

    message = MIMEText(body)
    message["to"] = ATTENDEE_EMAIL
    message["subject"] = f"Invitation: {MEETING_TITLE}"

    # Gmail's API requires the raw RFC 2822 message encoded as URL-safe base64
    raw = base64.urlsafe_b64encode(message.as_bytes()).decode()

    response = requests.post(
        "https://gmail.googleapis.com/gmail/v1/users/me/drafts",
        headers={"Authorization": f"Bearer {token}"},
        json={"message": {"raw": raw}},
    )
    response.raise_for_status()
    print("Draft created in Gmail.")

This creates a draft, not a sent message. The user reviews it before sending. For an agent taking actions on behalf of a user, draft-then-review is the right default - it keeps a human in the loop for outbound communication while still eliminating the scheduling work. When you're confident in the agent's output quality, switching to /messages/send is a one-line change.

Wire it together

def main() -> None:
    print("Authorizing Google Calendar...")
    calendar_token = authorize("googlecalendar")

    print("Authorizing Gmail...")
    gmail_token = authorize("gmail")

    print("Checking calendar availability...")
    busy_slots = get_busy_slots(calendar_token)

    slot = find_free_slot(busy_slots)
    if not slot:
        print(f"No free slot found in the next {SEARCH_DAYS} days.")
        return

    start, end = slot
    print(f"Found slot: {start.strftime('%A %B %d, %H:%M')} UTC")

    print("Creating calendar event...")
    event_link = create_event(calendar_token, start, end)
    print(f"Event created: {event_link}")

    print("Creating Gmail draft...")
    create_draft(gmail_token, event_link, start)


if __name__ == "__main__":
    main()

Testing Your Agent

Run the agent:

python meeting_scheduler_agent.py

On first run:

Authorizing Google Calendar...

Open this link to authorize googlecalendar:
https://accounts.google.com/o/oauth2/auth?...

Press Enter after completing authorization in your browser...

Authorizing Gmail...

Open this link to authorize gmail:
https://accounts.google.com/o/oauth2/auth?...

Press Enter after completing authorization in your browser...

Checking calendar availability...
Found slot: Wednesday March 11, 10:00 UTC
Creating calendar event...
Event created: https://calendar.google.com/calendar/event?eid=...
Creating Gmail draft...
Draft created in Gmail.

On subsequent runs, authorization prompts are skipped. The agent goes straight to availability checking.

Verify:

Open Google Calendar - the event should appear on the chosen date
Open Gmail Drafts - the draft should contain the event link

Common Mistakes while Building Your Agent

Connection name mismatch.
If you name the Scalekit connection google-calendar instead of googlecalendar, get_or_create_connected_account returns an error. The name in the Dashboard must exactly match the string you pass to authorize().
Missing OAuth scopes.
A 403 when calling the Calendar or Gmail API means the OAuth app in Google Cloud Console is missing required scopes. Calendar needs https://www.googleapis.com/auth/calendar, Gmail needs https://www.googleapis.com/auth/gmail.compose.
raise_for_status() swallowing context.
The default exception message from requests truncates the response body. In development, add print(response.text) before raise_for_status() to see the full error from Google.
UTC times without timezone info.
Passing a naive datetime (without timezone.utc) to isoformat() produces a string without a Z suffix. Google Calendar rejects this with a 400. Always construct datetimes with timezone.utc.
USER_ID not matching your session.
The script uses a hardcoded "user_123". In production, replace this with the actual user ID from your application's session. A mismatch means the connected account query returns the wrong user's tokens - and you'll get valid tokens for the wrong person.

Production Notes

Timezone handling.
The working-hours check is UTC-only. In production, convert the user's local timezone and the attendee's timezone before searching. The zoneinfo module (Python 3.9+) handles this without third-party dependencies.
Slot granularity.
One-hour increments miss 30- and 15-minute openings. Use the busy intervals directly to calculate gaps between events, then filter by minimum duration.
Multiple calendars.
The freeBusy query checks only primary. Users who split work and personal calendars will show false availability. Expand the items list to include all calendars they've shared access to.
Error recovery.
If create_event succeeds but create_draft fails, you have an orphaned event with no follow-up email. Wrap the two calls in a compensation pattern: store the event ID and delete it if draft creation fails.
Credentials in multi-tenant deployments.
The USER_ID here is a single hardcoded identifier. In a real multi-tenant system, each user needs their own connected account - and those accounts need to be isolated from each other. Scalekit's connected account model handles this by design: get_or_create_connected_account(connector, user_id) creates a separate authorized session per user, per connector. No token sharing, no cross-user access.
Rate limits.
Google Calendar and Gmail have per-user quotas. If your agent runs frequently for the same user, add exponential backoff around the requests.post calls.

What This Pattern Generalizes To

The authorize() function in this recipe is connector-agnostic. The same four lines handle authorization for any Scalekit-supported connector: swap "googlecalendar" for "slack", "notion", or "jira" and the OAuth lifecycle - initial authorization, token storage, automatic refresh, revocation handling - is managed identically.

This matters as agents get more capable. An agent that starts by booking meetings will eventually need to create Notion docs summarizing those meetings, post Slack updates to the relevant channel, and open Jira tickets for action items. Each of those integrations would traditionally mean writing OAuth boilerplate again. With the connected account model, it means adding one authorize() call per connector and focusing the rest of the code on the workflow.

The engineering leverage is the point. OAuth is infrastructure. Agents are products. The less time you spend on the former, the more you can invest in the latter.

Next Steps

Add natural language input - Replace hardcoded ATTENDEE_EMAIL, MEETING_TITLE, and DURATION_MINUTES with parameters parsed from an LLM tool call
Build the JavaScript equivalent - The agent-auth-examples repo includes a JavaScript track with the same pattern
Handle re-authorization - If a user revokes access, get_connected_account returns an inactive account; add a re-authorization path instead of crashing
Add more connectors - The authorize() pattern works for Slack, Notion, Jira - swap the connector name and replace the Google API calls with the target service's API
Review the Scalekit agent auth quickstart - For a broader overview of the connected-accounts model and how it handles multi-tenant deployments

Automate Slack workflows with LangGraph

Saif — Wed, 05 Nov 2025 12:38:08 +0000

How to turn messy #product-support Slack messages into auditable tasks

We’ve been experimenting with AI workflows (like most of the dev world lately — and of course, using Scalekit for the auth layer. Full disclosure: I work for Scalekit. Our offering is always free for devs tinkering with stuff).

For our first one, we tried automating Slack workflows with LangGraph and Scalekit. Here’s what we built 👇

🎫 Auto-create GitHub issues or Zendesk tickets directly from Slack messages
🔐 Simplify OAuth, token management, and API calls using Scalekit
🔁 Use LangGraph to design modular, observable workflows

The idea

Slack is great for fast communication, but terrible as a system of record. Important messages about bugs or support requests get buried almost instantly.

So we built an agent that:

Watches specific Slack channels
Classifies each message (bug, support, ignore)
Creates a GitHub issue or Zendesk ticket based on that classification
Posts a confirmation reply in Slack

Why LangGraph + Scalekit

Scalekit takes care of all the auth plumbing, so no need to manually store Slack or GitHub tokens, refresh them, or juggle SDKs. You just call execute_tool with the right parameters, and Scalekit securely handles the rest.

LangGraph gives you a clean, node-based workflow where each step is independent and observable. Instead of a big procedural script, you have a graph that shows exactly how data moves, which is perfect when you want to debug or extend it later.

How it works

Here’s the basic flow:

# triage.py
from routing import classify_route
from actions import create_github_issue, post_slack_confirmation, handle_zendesk_ticket

def triage_message(slack_user, channel, ts, text):
    route = classify_route(text)

    if route == "github":
        issue = create_github_issue(slack_user, channel, ts, text)
        post_slack_confirmation(slack_user, channel, ts, f"Created GitHub issue → {issue['url']}")
    elif route == "zendesk":
        handle_zendesk_ticket(slack_user, channel, ts)
    else:
        # ignored message
        pass

Each message gets classified, turned into a structured task, and acknowledged back in Slack — no human in the loop.

Moving to LangGraph

Once we had the script working, we turned it into a LangGraph workflow:

from langgraph import StateGraph
graph = (
    StateGraph()
      .add("parse", parse_node)
      .add("classify", classify_node)
      .add("execute", execute_node)
      .add("confirm", confirm_node)
      .edge("parse", "classify")
      .edge("classify", "execute")
      .edge("execute", "confirm")
      .entry("parse")
)

Each node handles one job, and you can easily replace or expand them later, like plugging in an LLM classifier, adding retries, or branching into multiple integrations.

Why is this useful?

Keeps your Slack channels clean and actionable
Saves hours of manual triage work
Makes tasks traceable and auditable
Easy to extend to Notion, Jira, or any API Scalekit supports

Try it yourself

Connect Slack + GitHub via Scalekit
Drop in the triage script
Run your loop or use webhooks for real-time updates
Watch your Slack messages turn into issues and tickets automatically

If you'd like a more comprehensive tutorial, head to this blog (It has working code, screenshots, and links to Git repos).

Automating Slack workflows with LangGraph and Scalekit

Building passwordless authentication in React

Saif — Wed, 10 Sep 2025 10:21:14 +0000

Imagine this: your SaaS product has grown quickly, and users are constantly forgetting their passwords. Support tickets pile up, password resets consume engineering time, and the login flow feels more like a barrier than an entry point. Your team decides to modernize by going passwordless, replacing passwords with short codes or magic links. Simple in theory, but the implementation? Not so much.

If you're building with React, here's what you have to tackle: Multiple forms, async calls colliding with redirects, state that doesn’t survive reloads, and code that breaks when users switch devices. Suddenly, what seemed like a straightforward UX improvement feels like a maintenance nightmare.

The real problem isn’t the idea of magic links or OTPs — those are well understood. The problem lies in managing state and security guarantees in a way that keeps your React code clean and your backend trustworthy.

What a passwordless flow actually looks like

At a high level, passwordless authentication follows a simple sequence:

Collect an email from the user.
Issue a credential — either a one-time passcode or a magic link.
Verify the code or token when the user comes back.
Mark the session as authenticated.

That’s it. No password resets, no strength meters, no secret storage. Just short-lived credentials that expire quickly and can’t be reused.

The tricky part is not the flow itself, but handling all the edge cases:

1. Users clicking a link twice.
2. Codes expiring while the form is still open.
3. Redirects landing in a different tab.
4. Sessions being dropped after a page reload.

Without a structured approach, developers end up duct-taping state machines across components and hoping everything holds.

Why security has to be server-first

Even if you nail the React side, passwordless only works if the server enforces the rules. That means:

Generating cryptographically signed tokens.
Enforcing expiry windows.
Preventing replay across devices.
Making sure resends invalidate old codes.

This isn’t something you want scattered through frontend code. The backend should own these guarantees so the client can stay focused on state and UX.

How Scalekit simplifies it

Scalekit takes on the server-side heavy lifting. It issues and validates short-lived tokens, handles resends safely, and ensures credentials are bound to the right context. You never expose secrets to the client, and you don’t need to reinvent cryptography or expiry logic.

On the React side, you just consume that flow declaratively. Using Scalekit’s SDK, you can:

Collect an email and request a magic link or OTP.
Handle redirects automatically and verify tokens.
Track session state across reloads.
Show clear UI states for sending, verifying, success, or error.

Instead of juggling timers and redirects by hand, your components stay focused: one handles email input, another handles code entry, and global context keeps track of whether the user is authenticated.

Wrapping up

Passwordless authentication removes one of the biggest sources of friction for users, but only if it’s implemented with both security and developer sanity in mind. By splitting responsibilities — React for state and UX, Scalekit for token security — you get a system that’s secure by default and reusable across projects.

If you’re ready to ditch fragile password resets and move to something users actually enjoy, check out the full guide and working example here: Passwordless authentication in React with Scalekit

Passwordless logins with magic links using Next.js 15 & Scalekit

Saif — Tue, 02 Sep 2025 17:00:18 +0000

Passwords are messy. Users forget them, reset flows break, and security teams keep telling us to add more rules (uppercase, symbols, no reuse). For developers, this means complexity. For users, it means frustration.

There’s a cleaner way: magic links.

With Scalekit, you can implement passwordless login in Next.js 15 using nothing more than API routes and middleware. Let’s see how.

Why magic links?

At Scalekit, we’ve seen teams run into the same problems:

Password resets flood support.
SMS-based codes lag or fail at scale.
Session state spreads across multiple services, making incidents hard to debug.

Magic links fix this by collapsing login into three simple server-side steps:

Issue a link
Verify it
Create a session

That’s it. No passwords, no SMS gateways, no half-baked tokens in the browser.

Step 1: Sending a link

In Next.js, create an API route /api/send-magic-link that accepts an email and calls Scalekit to generate a passwordless request:

// /api/send-magic-link/route.ts
export async function POST(req: NextRequest) {
  const { email } = await req.json()
  const resp = await client.passwordless.createAuthRequest({
    email,
    passwordlessType: 'MAGIC_LINK',
    expiresIn: 600,
  })

  const res = NextResponse.json({ ok: true })
  res.cookies.set('sk_auth_request_id', resp.authRequestId, { httpOnly: true, secure: true })
  return res
}

The cookie (sk_auth_request_id) ties the link back to this origin so clients can’t fake it.

Step 2: Verifying

When the user clicks the link, your /api/verify-magic-link route checks the token:

export async function POST(req: NextRequest) {
  const { link_token, auth_request_id } = await req.json()
  const result = await client.passwordless.verifyAuthRequest({ linkToken: link_token, authRequestId: auth_request_id })
  return NextResponse.json({ email: result.email })
}

Step 3: creating a session

Finally, issue a short-lived JWT stored in an HttpOnly cookie:

const token = jwt.sign({ email }, process.env.SESSION_JWT_SECRET, { expiresIn: '30m' })
res.cookies.set('sk_session', token, { 
httpOnly: true, 
secure: true, 
sameSite: 'lax' 
})

Middleware can now enforce that any protected route requires a valid JWT before it runs.

Why this works

Server-first: all sensitive logic (link creation, verification, session minting) happens in the backend.

Client-agnostic: the same API works for web apps, mobile apps, even CLI tools.

Observable: logs tell you who requested, who verified, and when the session was issued.

This design trims moving parts and makes login flows something you can trust and monitor.

Full guide

This post only scratches the surface. The full tutorial covers:

Rate limiting (stop bots from spamming send/verify).
Security headers (CSP, HSTS, etc).
Structured logging with correlation IDs.
Redis/SQL persistence for production.

👉 Read the complete step-by-step guide here

Your turn

Have you implemented passwordless login in your projects? Magic links, OTPs, or something else?

Share your setup, lessons, or gotchas in the comments: Other devs (and future you) will thank you.

How to safely let AI agents act on behalf of users

Saif — Tue, 26 Aug 2025 15:54:09 +0000

When you introduce AI agents into production systems, they don’t just run in isolation. They often act on behalf of real users—querying dashboards, triggering deploys, posting comments, or raising incidents.

The problem? Traditional OAuth and identity systems were built for single-user sessions, not autonomous agents. If you let agents impersonate users directly, you end up with over-permissioned, untraceable access.

That’s where On-Behalf-Of (OBO) authentication comes in. It creates a secure way for agents to operate with scoped, revocable permissions, while maintaining a clear audit trail that says exactly who acted, on whose behalf, and within which scopes.

The challenge: Delegation in AI workflows

Imagine your DevOps team builds an AI agent called InfraBot. Its job is to:

Query metrics from Datadog
File alerts in PagerDuty
Post comments on GitHub pull requests
Trigger rollbacks in ArgoCD

InfraBot should act only with the permissions of the engineer who initiated the action. But today’s identity systems don’t support this dual identity (user + agent). Without OBO, you end up with:

Tokens tied only to agents means no attribution to the human who delegated authority
Over-permissioning means agents get more access than they need
Weak audit trails mean logs just say “InfraBot did X”

How OBO works: dual identity in tokens

OBO authentication encodes both the agent and the user inside a single token. This is done using structured JWT claims.

Here’s a simple example of a decoded JWT payload:

{
  "sub": "agent:infrabot",
  "act": {
    "sub": "user:eng123",
    "scope": ["incident:read", "monitoring:query"]
  }
}

This tells downstream systems:

The agent making the request is agent:infrabot
The user who delegated authority is user:eng123
The scopes permitted are incident:read, monitoring:query

Now, when InfraBot calls GitHub or PagerDuty, those systems know both who executed the request and who authorized it.

Scoped, explicit, and revocable permissions

Delegation should never mean “full access.” Tokens must be:
Explicit: Only the required scopes (e.g., deploy:create)
Scoped: Limited to specific resources or environments
Temporary: Short-lived (5–15 minutes)
Revocable: Tied to user state so that if Sam loses deploy access, InfraBot loses it too

Here’s an example of a structured, short-lived delegation token:

{
  "sub": "agent:infrabot",
  "act": {
    "sub": "user:sam",
    "scope": ["urn:infra:monitoring:read"],
    "context": {
      "trigger": "ci_pipeline",
      "environment": "prod"
    }
  },
  "exp": 1722000000,
  "revocation_url": "https://auth.company.com/revoke/token123",
  "log_url": "https://audit.company.com/logs/token123"
}

Multi-level delegation: Chaining identities

Things get more complex when agents call other agents. For example:
Sam → InfraBot → ArgoCD → AWS

Nested claims in the token can represent that chain:

{
  "sub": "agent:argocd",
  "act": {
    "sub": "agent:infrabot",
    "act": {
      "sub": "user:sam",
      "scope": ["deploy:create"]
    }
  }
}

Downstream services can then parse the chain and know:

Sam triggered the workflow
InfraBot delegated to ArgoCD
ArgoCD is the final executor
Enforcing delegation in your services

Issuing tokens is only half the work. Every service receiving the token must:

Validate the chain of actors (sub + act.sub)
Enforce scopes against allowed operations
Log both the agent and the user

Here’s a simple Node.js middleware example:

function delegationMiddleware(req, res, next) {
  const token = req.headers.authorization?.split(" ")[1];
  const payload = jwt.verify(token, publicKey);

  req.agent = payload.sub;
  req.user = payload.act?.sub;
  req.scope = payload.act?.scope || [];

  if (!req.user) return res.status(401).send("Missing delegation context");
  next();
}

Takeaways

Are your AI agents still using service accounts or static tokens? Start by:

Issuing structured tokens with both agent + user identities
Enforcing scopes at runtime in your APIs
Shortening token lifetimes and adding revocation checks
Logging both the actor and delegator in every request

Building trustworthy delegation is the difference between uncontrolled automation and secure, enterprise-ready AI workflows.

Want to go deeper? Check out the full write-up here: Understanding On-Behalf-Of in AI agent authentication

Will your existing API work with AI agents?

Saif — Wed, 20 Aug 2025 15:57:41 +0000

If you've built a solid REST API and you're starting to integrate AI agents, MCP wrapping might be your fast track to compatibility. Wrapping doesn't mean rebuilding your backend. It means adding a machine-callable layer around it so AI models can treat those endpoints as structured tools.

Let’s break down when wrapping makes sense, and walk through four practical patterns to help your agents interact cleanly with your system.

When wrapping MCP around your existing API makes sense

Wrapping is a smart shortcut when:

Your API is stable, versioned, and well-documented
You’re short on time or backend bandwidth
You're prototyping AI integrations but don't want to overhaul your stack
You need a buffer for legacy systems, adding structure, auth, and formatting without touching internal logic

Instead of rewriting endpoints, you make them agent-ready with minimal effort, complete with typed inputs, response templates, and security layers.

Four wrapper architecture patterns

Here are four proven approaches to MCP wrapping. Choose one based on your API design and integration goals:

1. Direct translation: Each endpoint becomes one tool

Simply map each REST route to an MCP tool (e.g., get_user_profile). Easy to automate using OpenAPI.

Pros: Minimal logic, fast to generate

Cons: Too granular, potentially overwhelming

2. Capability aggregation: Bundle related endpoints into intelligent tools

For example, wrap create_invoice, update_invoice, cancel_invoice into a single InvoiceManager tool.

Pros: Cleaner for agents, allows orchestration or retries

Cons: Needs more design and docs effort

3. Context-aware wrapping: Add short-term memory to tools

Useful for flows like “search → select → update.” Maintain light session state or context to avoid repetition.

Pros: Natural conversations; richer UX

Cons: Adds complexity: reset, expire, manage state, etc.

4. Hybrid: Mix tool exposure and direct API calls

Expose only core actions as tools, while letting internal services or legacy parts remain untouched.

Pros: Flexible, low-risk for prototypes

Cons: Requires clear documentation and boundaries

Speed things up with OpenAPI-to-MCP tooling

If your API already follows OpenAPI, you can generate MCP tool definitions automatically. The openapi-to-mcp-converter lets you:

Turn an OpenAPI spec into MCP-ready tool configs
Generate typed arguments + response templates effortlessly
Add optional prompts or formatting hints to enrich outputs

This gives you a jump-start on wrapping with minimal manual work.

Wrapping vs. rebuilding: A quick comparison

Rebuilding as native MCP tools can be more structured, but it takes time
Wrapping gives you a fast way to support agents using your existing stack
Most teams start with wrapping and refactor toward full tools only when needed

Your next steps

Choose a wrapper pattern based on your API and agent needs
Run OpenAPI-to-MCP tools if your spec supports it
Add structured prompts and validation to make tools intuitive for agents
Document and test using an agent client like Claude, ChatGPT, or your own agent test harness

Want a full walkthrough and examples on wrapping MCP around your API for agents? Check out the detailed guide: Wrap MCP around your existing API

Mapping an existing API to MCP tools

Saif — Tue, 12 Aug 2025 16:19:07 +0000

Imagine your team has an internal productivity API, built over the years, that powers projects, tasks, comments, roles, notifications, and access control. It’s stable and well‑used, but it’s not yet ready for AI agents.

The challenge is to expose this system as a clean, composable set of MCP tools, not just wrappers, but schema‑driven, predictable, and reusable.

Here’s how you can do it.

1️⃣ Understand your API surface

Group endpoints into logical domains:

Users
Tasks
Comments
Roles
Projects

For each domain, list the operations: fetch, list, create, update, delete. This mapping leads to tool names like get_user, list_projects, create_task.

2️⃣ MCP tools represent capabilities, not routes

Each tool is a single, self‑contained capability:

name: "get_user"
description: "Retrieve a user by ID"
inputSchema: { userId: string }
outputSchema: { name: string; email: string }
handler: async ({ userId }) => { /* ... */ }

Flatten all request inputs into inputSchema and define predictable JSON outputs. Remove HTTP status codes from the interface.

3️⃣ Transform OpenAPI into Agent‑Friendly Schemas

From OpenAPI:

GET /users/{id}
- path param: id: string
- 200 response: { name, email }

To MCP tool:

name: "get_user",
inputSchema: { userId: z.string() },
outputSchema: { name: z.string(), email: z.string() }

This makes tools self‑documenting and composable.

4️⃣ Handle real‑world patterns

We applied consistent schemas for:

CRUD (get_user, create_task)
Filtering/Search (search_tasks)
Batch Operations (create_tasks_batch)
File Uploads/Downloads (signed URLs)

Example filter:

inputSchema: {
  status: z.enum(["open", "in_progress", "closed"]),
  assignedTo: z.string().optional()
}

5️⃣ Keep tools predictable and reusable

Stick to conventions (get_, list_, create_, update_, delete_), share object schemas, and avoid mixing unrelated actions in a single tool.

6️⃣ Clean, testable implementation

Modular structure:

src/
  tools/
    user-tools.ts
    task-tools.ts
  schemas/
    shared.ts
  server.ts

Example:

export const getUserTool: MCPTool = {
  name: "get_user",
  description: "Retrieve a user by ID",
  inputSchema: z.object({ userId: z.string() }),
  outputSchema: UserSchema,
  handler: async ({ userId }) => {
    const user = getUserById(userId);
    if (!user) throw { code: "NOT_FOUND", message: "User not found" };
    return user;
  }
};

7️⃣ Test with a mock backend

With mockDB:

it("get_user: throws on missing user", async () => {
  await expect(getUserTool.handler({ userId: "nope" }))
    .rejects.toMatchObject({ code: "NOT_FOUND" });
});

Result: A predictable, composable MCP tool layer with structured errors and maintainable code, ready for AI agents to use reliably.

📖 Read the deep dive

Your turn. Let me know your experiences about mapping API to MCP in the comments section below.

Implementing OAuth for MCP servers: a developer's guide

Saif — Tue, 29 Jul 2025 16:47:05 +0000

Imagine you've built an AI-driven sales analytics tool used by enterprise SaaS businesses. It aggregates sales data, integrates with CRMs, and helps companies forecast revenue accurately.

In today’s AI-centric ecosystem, you would need to have the capability to use conversational prompts to surface the right insights. How do you securely handle authentication and manage API requests at scale without exposing sensitive customer data?

MCP servers act as a secure layer that enables your AI application to interact safely and efficiently with external systems. With an MCP server in place, your sales analytics tool can securely handle auth, manage access to sensitive data, and control interactions between your app and client systems, all without exposing direct access credentials or data endpoints.

As your MCP server moves from prototype to production, OAuth 2.1 authentication becomes critical. Here’s a step-by-step guide on securely implementing OAuth 2.1, with code examples.

OAuth implementation overview

Implementing OAuth for MCP involves four core steps:

Register your MCP server and define OAuth scopes
Expose OAuth protected resource metadata
Validate JWT tokens
Implement scope-based authorization

Let's dive right in.

Step 1: Register your MCP server

First, register your MCP server in your Scalekit dashboard:

Server name: e.g., "Sales Analytics API"
Resource identifier: Unique URL (e.g., https://api.sales-analytics.com)
Dynamic client registration: Enabled for automatic onboarding
Token lifetime: Access tokens (5 min–1 hr), refresh tokens (up to 24 hrs)

Define your OAuth scopes

Scopes should clearly represent permissions. Examples:

mcp:tools:sales-data:read - Read sales data
mcp:tools:crm:write - Update CRM records
mcp:resources:customer-insights:read - Access customer insights

Step 2: OAuth protected resource metadata

Your MCP server exposes metadata for clients to auto-discover OAuth endpoints:

app.get('/.well-known/oauth-protected-resource', (req, res) => {
  res.json({
    resource: 'https://api.sales-analytics.com',
    authorization_servers: ['https://your-org.scalekit.com'],
    bearer_methods_supported: ['header'],
    resource_documentation: 'https://api.sales-analytics.com/docs',
    scopes_supported: [
      'mcp:tools:sales-data',
      'mcp:tools:crm:read',
      'mcp:tools:crm:write',
      'mcp:tools:notifications:send',
      'mcp:resources:*'
    ]
  });
});

Step 3: Validate JWT tokens

Each request to your MCP endpoints must validate a JWT token:

import { jwtVerify, createRemoteJWKSet } from 'jose';

const JWKS = createRemoteJWKSet(
  new URL('https://your-org.scalekit.com/.well-known/jwks')
);

const validateToken = async (req, res, next) => {
  const token = req.headers.authorization?.split(' ')[1];

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

  try {
    const { payload } = await jwtVerify(token, JWKS, {
      issuer: 'https://your-org.scalekit.com',
      audience: 'https://api.sales-analytics.com'
    });

    req.auth = {
      userId: payload.sub,
      scopes: payload.scope?.split(' ') || [],
      clientId: payload.client_id,
      expiresAt: payload.exp
    };

    next();
  } catch (error) {
    return res.status(401).json({ error: 'Invalid or expired token' });
  }
};

app.use('/mcp', validateToken);

Step 4: Scope-based authorization

Scopes provide granular permissions:

const requireScope = (requiredScope) => (req, res, next) => {
  const userScopes = req.auth.scopes;
  const hasScope = userScopes.some(scope =>
    scope === requiredScope || scope.endsWith(':*') && requiredScope.startsWith(scope.slice(0, -1))
  );

  if (!hasScope) {
    return res.status(403).json({
      error: 'insufficient_scope',
      required_scope: requiredScope
    });
  }

  next();
};

app.post('/mcp/tools/sales-data',
  requireScope('mcp:tools:sales-data:read'),
  handleSalesDataRequest
);

Testing your implementation

Thoroughly test OAuth integration:

const testMCPAuth = async () => {
  const tokenResponse = await fetch('https://your-org.scalekit.com/oauth2/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      grant_type: 'client_credentials',
      client_id: 'test-client-id',
      client_secret: 'test-client-secret',
      scope: 'mcp:tools:sales-data'
    })
  });

  const { access_token } = await tokenResponse.json();

  const response = await fetch('https://api.sales-analytics.com/mcp/tools/sales-data', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${access_token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      method: 'sales/get_forecast',
      params: { region: 'North America' }
    })
  });

  console.log(await response.json());
};

For further details, explore our comprehensive guide: Implement OAuth authentication for MCP servers using Scalekit.

Why you need token vaults for AI agent workflows

Saif — Mon, 21 Jul 2025 12:24:01 +0000

Managing credentials for AI agents often means scattering secrets across containers and services. Hard-coded tokens and custom refresh logic quickly become security risks.

A token vault centralizes credential storage, handles automatic rotation, and dispenses short-lived access tokens on demand. Agents simply request the tokens they need. No long-lived secrets in their code.

Below, we’ll cover why a token vault is essential for modern workflows, walk through a real-world productivity tracker example, and share vetted code snippets to help you get started.

What is a token vault?

A token vault is a dedicated service that holds and manages all your API credentials. Instead of embedding OAuth tokens or service-account secrets inside each agent, you give every agent a single vault credential.

When an agent needs to call an API (Say, to create a calendar entry or fetch analytics data), it asks the vault for a scoped access token. The vault handles refreshing tokens, auditing access, and enforcing least-privilege policies.

Practical use case: AI productivity tracker

Imagine you’re building a productivity tracker that uses AI to summarize a user’s meetings, log tasks to a time-tracking tool, and post daily digests to Slack. Each of these integrations requires separate OAuth tokens, and each agent instance, running per user session, needs its own credentials.

Without a vault, you’d end up hard-coding refresh tokens in every container, writing duplicate logic to detect expiration and refresh tokens, and struggling to audit which agent accessed which service.

With a token vault, your tracker agents become credential-agnostic. They simply request “give me a Slack token” or “give me a time-tracker token” and get back a valid bearer token, scoped exactly to the API they need.

Core vault workflow

At a high level, the vault flow works like this:

The vault operator performs an initial OAuth flow (or service-account exchange) to provision long-lived refresh tokens for each external API.
Agents authenticate to the vault using their own short-lived vault token.
When an agent needs to call an API, it requests a fresh token from the vault, specifying which service it needs (e.g., slack-post or time-tracker).
The vault returns a scoped access token. Under the hood, the vault uses the stored refresh token to fetch a new access token if necessary, and logs the event.

Example: Fetching a time-tracker token

Here’s how a productivity tracker agent fetches a token for the time tracking API:

import fetch from 'node-fetch';
async function getTimeTrackerToken(agentId) {
  const vaultUrl = process.env.VAULT_URL;
  const vaultToken = process.env.VAULT_AGENT_TOKEN; // short-lived
  const res = await fetch(
    `${vaultUrl}/v1/agents/${agentId}/credentials/time-tracker`,
    {
      headers: {
        'Authorization': `Bearer ${vaultToken}`,
        'Content-Type': 'application/json'
      }
    }
  );

  if (!res.ok) {
    const body = await res.text();
    throw new Error(`Vault error (${res.status}): ${body}`);
  }
  const { access_token } = await res.json();
  return access_token;
}

With this helper, your agent code stays focused on business logic: summarizing meetings or logging hours, without ever touching the underlying refresh tokens or client secrets.

Automated rotation and cleanup

A background job in the vault takes care of refreshing tokens behind the scenes:

#!/usr/bin/env bash
# refresh_time_tracker.sh

new_token=$(curl -s -X POST https://oauth.time-tracker.com/token \
  -d client_id=$TT_CLIENT_ID \
  -d client_secret=$TT_CLIENT_SECRET \
  -d grant_type=refresh_token \
  -d refresh_token=$TT_REFRESH_TOKEN)

# Store the new token in the vault
curl -X PUT "${VAULT_URL}/v1/credentials/time-tracker" \
  -H "Authorization: Bearer ${VAULT_ADMIN_TOKEN}" \
  -H "Content-Type: application/json" \
  -d "{\"refresh_token\":\"$(echo $new_token | jq -r .refresh_token)\"}"

This script can run on a schedule (e.g., cron or a Kubernetes CronJob), ensuring your agents always receive valid tokens without extra code.

Why this matters

A token vault streamlines secure credential management by centralizing storage, rotation, and access control. Agent code remains lean, secrets are protected in one place, and audit logs give you full visibility into who requested which token and when.

For platforms with dozens or hundreds of AI workflows, a vault is the only sustainable path to secure, scalable integrations.

If you’d like to get a comprehensive, step-by-step flow of how you can use a token vault, check out our blog post.

Your turn

Have you implemented a token vault or secrets manager for your AI agents or microservices? What tooling did you choose, and what challenges did you face? Share your experiences below. 👇

Mapping the MCP Ecosystem

Saif — Thu, 10 Jul 2025 15:52:28 +0000

Every week feels like a new chapter in the AI world. And if you’ve been playing around with MCP servers, you know exactly what I mean.

MCP is opening up something I’ve personally never seen at this scale:

AI agents securely calling into SaaS apps as if they were just another user.
SaaS platforms exposing their capabilities as discoverable, authenticated tools for agents to use.
Devs like us building something mindblowing every other week.

What excites me even more is just how fast this ecosystem is growing.
While building, we kept asking: who else is here? what tools are emerging? where does my work fit in?

So we decided to map it. Across categories: servers, clients, hosting, testing, registries, marketplaces, and more.

Here’s our snapshot of the MCP ecosystem today.

DEV Community: Saif

Enterprise Auth in Astro without the pain

Table of Contents

Why Scalekit for B2B auth?

Core concepts: OAuth 2.0, OIDC, and the token trio

The Authorization Code Flow

The token trio

SAML vs. OIDC — which does your enterprise customer need?

Project setup & environment

Prerequisites

Create the Astro project

Configure server-side rendering

Environment variables

TypeScript types and IntelliSense

Initializing the Scalekit client

The three auth endpoints

login.ts — initiating the flow

callback.ts — exchanging the code for tokens

logout.ts — ending the session correctly

Session middleware — the right way

Protecting pages and API routes

Protected page pattern

Protected API route pattern

Navigation component

Enterprise SSO: per-organization connections

The org-aware login form

Reading org context from the token

PKCE flow (no client secret)

Production best practices

Security headers

Troubleshooting common gotchas

redirect_uri_mismatch

Token validation fails after deployment

Refresh token not returned

Middleware runs on static assets

Enterprise SSO user not found in your database

Putting it all together

Resources

Add Enterprise SSO to Your Next.js App in Minutes Using Claude Code & Scalekit

Table of Contents

What You're Building

Understanding the Plugin Architecture

What Are Claude Code Plugins?

How Scalekit's Plugin Works

Prerequisites

Step-by-Step Implementation

Step 1: Install the Scalekit Plugin

Step 2: Navigate to Your Project

Step 3: Give Claude the Objective

Step 4: Approve the Redirect URI

Step 5: Add Your Client Secret

Step 6: Review Generated Files

Step 7: Install Dependencies

Testing with the IDP Simulator

Start Your Dev Server

Use the Test Organization

Test the Flow

Check the Admin Portal

How It Actually Works

The SSO Flow

Organization-Based Routing

The Admin Portal

Security Considerations Built In

Production Considerations

Environment Variables

Update Redirect URIs

Session Management

Error Handling

Monitoring

Alternative: Using Other AI Coding Agents

GitHub Copilot CLI

Cursor

Any Agent via Vercel Skills

Why This Matters

Conclusion

Multi-Connector OAuth: Meeting Scheduler Agent using Google Calendar, Gmail, Scalekit

What You're Actually Building

Why OAuth Gets Complicated in Multi-Step Agents

The four OAuth problems that make this harder than it looks:

The Architecture: Delegated OAuth Lifecycle

`redirect_uri_mismatch`