Scalekit Docs | Blog

Build a daily briefing agent with Vercel AI SDK and Scalekit Agent Auth

Fri, 27 Mar 2026 00:00:00 GMT

A daily briefing agent needs two things: today’s calendar events and the latest unread emails. Both live behind OAuth-protected APIs, and each requires its own token, its own authorization flow, and its own refresh logic. Before you write any scheduling logic, you’re already maintaining two parallel token lifecycles.

Scalekit eliminates that overhead. It stores one OAuth session per connector per user, handles token refresh automatically, and gives you a single API surface regardless of which provider you’re talking to. This recipe shows how to use it with Google Calendar and Gmail — and demonstrates two patterns for consuming those credentials in your agent.

What this recipe covers:

OAuth token pattern — Scalekit provides a valid token; your agent calls the Google Calendar REST API directly. Use this when you need full control over the request.
Built-in action pattern — Your agent calls execute_tool("gmail_fetch_mails"); Scalekit executes the Gmail API call and returns structured data. Use this when you want speed and don’t need to customize the request.

The complete source used here is available in the vercel-ai-agent-toolkit repository, with a TypeScript implementation using the Vercel AI SDK and a Python implementation using the Anthropic SDK directly.

1. Set up connections in Scalekit

In the Scalekit Dashboard, create two connections under Agent Auth → Connections:

googlecalendar — Google Calendar OAuth connection
gmail — Gmail OAuth connection

The connection names are identifiers your code references directly. They must match exactly.

cd typescript
pnpm install

The typescript/package.json includes:

{
  "dependencies": {
    "ai": "^4.3.15",
    "@ai-sdk/anthropic": "^1.2.12",
    "@scalekit-sdk/node": "2.2.0-beta.1",
    "zod": "^3.0.0",
    "dotenv": "^16.0.0"
  }
}

cd python
uv venv .venv
uv pip install -r requirements.txt

The python/requirements.txt includes:

scalekit-sdk-python
anthropic
requests
python-dotenv

3. Configure credentials

Copy the example env file and fill in your credentials:

cp typescript/.env.example typescript/.env   # TypeScript
cp typescript/.env.example python/.env       # Python (same variables)

.env

SCALEKIT_ENV_URL=https://your-env.scalekit.dev
SCALEKIT_CLIENT_ID=skc_...
SCALEKIT_CLIENT_SECRET=your-secret

ANTHROPIC_API_KEY=sk-ant-...

Get your Scalekit credentials at app.scalekit.com → Settings → API Credentials.

4. Initialize the Scalekit client

TypeScript
Python

import { ScalekitClient } from '@scalekit-sdk/node';
import { ConnectorStatus } from '@scalekit-sdk/node/lib/pkg/grpc/scalekit/v1/connected_accounts/connected_accounts_pb.js';
import 'dotenv/config';

// Never hard-code credentials — they would be exposed in source control.
// Pull them from environment variables at runtime.
const scalekit = new ScalekitClient(
  process.env.SCALEKIT_ENV_URL!,
  process.env.SCALEKIT_CLIENT_ID!,
  process.env.SCALEKIT_CLIENT_SECRET!,
);

const USER_ID = 'user_123'; // Replace with the real user ID from your session

ConnectorStatus is imported from the SDK’s generated protobuf file. Compare connectedAccount.status against ConnectorStatus.ACTIVE rather than the string 'ACTIVE' — TypeScript’s type system enforces this.

import os
import json
import requests
from datetime import datetime, timezone
from dotenv import load_dotenv
import anthropic
import scalekit.client

load_dotenv()

# Never hard-code credentials — they would be exposed in source control.
# Pull them from environment variables at runtime.
scalekit_client = scalekit.client.ScalekitClient(
    client_id=os.environ["SCALEKIT_CLIENT_ID"],
    client_secret=os.environ["SCALEKIT_CLIENT_SECRET"],
    env_url=os.environ["SCALEKIT_ENV_URL"],
)
actions = scalekit_client.actions

USER_ID = "user_123"  # Replace with the real user ID from your session

scalekit_client.actions is the entry point for all connected-account operations: creating accounts, generating auth links, fetching tokens, and executing built-in tools.

5. Ensure each connector is authorized

Before calling any API, check whether the user has an active connected account. If not, print an authorization link and wait for them to complete the browser OAuth flow.

TypeScript
Python

async function ensureConnected(connector: string) {
  const { connectedAccount } =
    await scalekit.connectedAccounts.getOrCreateConnectedAccount({
      connector,
      identifier: USER_ID,
    });

  if (connectedAccount?.status !== ConnectorStatus.ACTIVE) {
    const { link } =
      await scalekit.connectedAccounts.getMagicLinkForConnectedAccount({
        connector,
        identifier: USER_ID,
      });
    console.log(`\n[${connector}] Authorization required.`);
    console.log(`Open this link:\n\n  ${link}\n`);
    console.log('Press Enter once you have completed the OAuth flow...');
    await new Promise<void>(resolve => {
      process.stdin.resume();
      process.stdin.once('data', () => { process.stdin.pause(); resolve(); });
    });
  }

  return connectedAccount;
}

def ensure_connected(connector: str):
    response = actions.get_or_create_connected_account(
        connection_name=connector,
        identifier=USER_ID,
    )
    connected_account = response.connected_account

    if connected_account.status != "ACTIVE":
        link_response = actions.get_authorization_link(
            connection_name=connector,
            identifier=USER_ID,
        )
        print(f"\n[{connector}] Authorization required.")
        print(f"Open this link:\n\n  {link_response.link}\n")
        input("Press Enter once you have completed the OAuth flow...")

    return connected_account

After the first successful authorization, getOrCreateConnectedAccount / get_or_create_connected_account returns an active account on all subsequent calls. Scalekit refreshes expired tokens automatically — your code never calls a token-refresh endpoint.

6. Fetch calendar events using the OAuth token pattern

For Google Calendar, retrieve a valid access token from Scalekit and call the Google Calendar REST API directly. This pattern gives you full control over query parameters, pagination, and error handling.

TypeScript
Python

async function getAccessToken(connector: string): Promise<string> {
  const response =
    await scalekit.connectedAccounts.getConnectedAccountByIdentifier({
      connector,
      identifier: USER_ID,
    });
  const details = response?.connectedAccount?.authorizationDetails?.details;
  if (details?.case === 'oauthToken' && details.value?.accessToken) {
    return details.value.accessToken;
  }
  throw new Error(`No access token found for ${connector}`);
}

Use this token in a tool that the LLM can call:

import { tool } from 'ai';
import { z } from 'zod';

const today = new Date();
const timeMin = new Date(today.getFullYear(), today.getMonth(), today.getDate()).toISOString();
const timeMax = new Date(today.getFullYear(), today.getMonth(), today.getDate(), 23, 59, 59).toISOString();

const calendarToken = await getAccessToken('googlecalendar');

const getCalendarEvents = tool({
  description: "Fetch today's events from Google Calendar",
  parameters: z.object({
    maxResults: z.number().optional().default(5),
  }),
  execute: async ({ maxResults }) => {
    const url = new URL('https://www.googleapis.com/calendar/v3/calendars/primary/events');
    url.searchParams.set('timeMin', timeMin);
    url.searchParams.set('timeMax', timeMax);
    url.searchParams.set('maxResults', String(maxResults));
    url.searchParams.set('orderBy', 'startTime');
    url.searchParams.set('singleEvents', 'true');

    const res = await fetch(url.toString(), {
      headers: { Authorization: `Bearer ${calendarToken}` },
    });
    if (!res.ok) throw new Error(`Calendar API error: ${res.status}`);
    const data = await res.json() as { items?: unknown[] };
    return data.items ?? [];
  },
});

def get_access_token(connector: str) -> str:
    # get_connected_account always returns a fresh token —
    # Scalekit refreshes expired tokens before returning.
    response = actions.get_connected_account(
        connection_name=connector,
        identifier=USER_ID,
    )
    tokens = response.connected_account.authorization_details["oauth_token"]
    return tokens["access_token"]

def fetch_calendar_events(access_token: str, max_results: int = 5) -> list:
    today = datetime.now(timezone.utc).astimezone()
    time_min = today.replace(hour=0, minute=0, second=0, microsecond=0).isoformat()
    time_max = today.replace(hour=23, minute=59, second=59, microsecond=0).isoformat()

    resp = requests.get(
        "https://www.googleapis.com/calendar/v3/calendars/primary/events",
        headers={"Authorization": f"Bearer {access_token}"},
        params={
            "timeMin": time_min,
            "timeMax": time_max,
            "maxResults": max_results,
            "orderBy": "startTime",
            "singleEvents": "true",
        },
    )
    resp.raise_for_status()
    return resp.json().get("items", [])

7. Fetch emails using the built-in action pattern

For Gmail, call execute_tool with the built-in gmail_fetch_mails action. Scalekit executes the Gmail API call using the stored token and returns structured data. You don’t need to build the request, handle the token, or parse the response format.

TypeScript
Python

const getUnreadEmails = tool({
  description: 'Fetch top unread emails from Gmail via Scalekit actions',
  parameters: z.object({
    maxResults: z.number().optional().default(5),
  }),
  execute: async ({ maxResults }) => {
    const response = await scalekit.tools.executeTool({
      toolName: 'gmail_fetch_mails',
      connectedAccountId: gmailAccount?.id,
      params: {
        query: 'is:unread',
        max_results: maxResults,
      },
    });
    return response.data?.toJson() ?? {};
  },
});

def fetch_unread_emails(connected_account_id: str, max_results: int = 5) -> dict:
    response = actions.execute_tool(
        tool_name="gmail_fetch_mails",
        connected_account_id=connected_account_id,
        tool_input={
            "query": "is:unread",
            "max_results": max_results,
        },
    )
    return response.result

The built-in action pattern trades flexibility for brevity. You can’t customize headers or pagination, but you also don’t need to read Gmail API documentation — the tool parameters are consistent across all Scalekit connectors. See all supported agent connectors for the full list of built-in tools.

8. Wire the agent together

Pass both tools to the LLM and ask for a daily summary.

TypeScript
Python

The TypeScript version uses the Vercel AI SDK’s generateText with maxSteps to allow the LLM to call multiple tools in sequence before producing the final response.

import { generateText } from 'ai';
import { anthropic } from '@ai-sdk/anthropic';

const [calendarAccount, gmailAccount] = await Promise.all([
  ensureConnected('googlecalendar'),
  ensureConnected('gmail'),
]);

const calendarToken = await getAccessToken('googlecalendar');

const { text } = await generateText({
  model: anthropic('claude-sonnet-4-6'),
  prompt: `Give me a summary of my day for ${today.toDateString()}: list today's calendar events and my top 5 unread emails.`,
  tools: {
    getCalendarEvents,
    getUnreadEmails,
  },
  maxSteps: 5, // allow the LLM to call multiple tools before responding
});

console.log(text);

maxSteps controls how many tool-call rounds the LLM can make before it must return a final text response. Without it, generateText stops after the first tool call.

The Python version uses the Anthropic SDK directly with a manual agentic loop. The loop continues until the model returns stop_reason == "end_turn" with no pending tool calls.

def run_agent():
    gmail_account = ensure_connected("gmail")
    ensure_connected("googlecalendar")
    calendar_token = get_access_token("googlecalendar")

    client = anthropic.Anthropic()
    today = datetime.now().strftime("%A, %B %d, %Y")

    tools = [
        {
            "name": "get_calendar_events",
            "description": "Fetch today's events from Google Calendar",
            "input_schema": {
                "type": "object",
                "properties": {"max_results": {"type": "integer", "default": 5}},
            },
        },
        {
            "name": "get_unread_emails",
            "description": "Fetch top unread emails from Gmail via Scalekit actions",
            "input_schema": {
                "type": "object",
                "properties": {"max_results": {"type": "integer", "default": 5}},
            },
        },
    ]

    messages = [
        {
            "role": "user",
            "content": f"Give me a summary of my day for {today}: list today's calendar events and my top 5 unread emails.",
        }
    ]

    while True:
        response = client.messages.create(
            model="claude-sonnet-4-6",
            max_tokens=1024,
            tools=tools,
            messages=messages,
        )
        messages.append({"role": "assistant", "content": response.content})

        if response.stop_reason == "end_turn":
            for block in response.content:
                if hasattr(block, "text"):
                    print(block.text)
            break

        tool_results = []
        for block in response.content:
            if block.type == "tool_use":
                max_results = block.input.get("max_results", 5)
                if block.name == "get_calendar_events":
                    result = fetch_calendar_events(calendar_token, max_results)
                elif block.name == "get_unread_emails":
                    result = fetch_unread_emails(gmail_account.id, max_results)
                else:
                    result = {"error": f"Unknown tool: {block.name}"}
                tool_results.append({
                    "type": "tool_result",
                    "tool_use_id": block.id,
                    "content": json.dumps(result),
                })

        if tool_results:
            messages.append({"role": "user", "content": tool_results})
        else:
            break

if __name__ == "__main__":
    run_agent()

9. Testing

Run the agent:

TypeScript
Python

cd typescript && pnpm start

cd python && .venv/bin/python index.py

On first run, you see two authorization prompts in sequence:

[googlecalendar] Authorization required.
Open this link:

  https://auth.scalekit.dev/connect/...

Press Enter once you have completed the OAuth flow...

[gmail] Authorization required.
Open this link:

  https://auth.scalekit.dev/connect/...

Press Enter once you have completed the OAuth flow...

After both connectors are authorized, the agent fetches your data and returns a summary:

Here's your day for Friday, March 27, 2026:

📅 Calendar — 3 events today
• 9:00 AM  Team standup (30 min)
• 1:00 PM  Product review
• 4:00 PM  1:1 with manager

📧 Unread emails — top 5
• "Q1 roadmap feedback needed" — Sarah Chen, 1h ago
• "Deploy failed: production" — GitHub Actions, 2h ago
• "New PR review requested" — Lin Feng, 3h ago
...

On subsequent runs, both authorization prompts are skipped. Scalekit returns the active session directly.

Common mistakes

Connection name mismatch

Symptom: getOrCreateConnectedAccount returns an error for googlecalendar or gmail
Cause: The connection name in the Scalekit Dashboard does not match the literal string in your code
Fix: Make the dashboard connection name match your code exactly, for example googlecalendar instead of google-calendar

TypeScript status compared to a string

Symptom: TypeScript raises TS2367 for connectedAccount?.status !== 'ACTIVE'
Cause: The SDK returns a ConnectorStatus enum, not a string literal
Fix: Import ConnectorStatus from the SDK’s generated protobuf file and compare against ConnectorStatus.ACTIVE

Python naive datetimes in API calls

Symptom: Google Calendar returns a 400 error for your event query
Cause: A naive datetime produces an ISO string without timezone information
Fix: Use datetime.now(timezone.utc) and call .astimezone() so the generated timestamps are timezone-aware

maxSteps missing in the Vercel AI SDK

Symptom: generateText stops after the first tool call instead of returning a final summary
Cause: The model is not allowed to make enough tool-call rounds
Fix: Set maxSteps to at least 3, and increase it if your workflow needs more than one tool call plus a final response

toolInput used instead of params

Symptom: executeTool succeeds but the Gmail tool receives no parameters
Cause: @scalekit-sdk/node expects a params field, not toolInput
Fix: Pass tool arguments in params, for example { query: 'is:unread', max_results: 5 }

Production notes

User ID from session — Both implementations hardcode USER_ID = "user_123". In production, replace this with the real user identifier from your application’s session. A mismatch means Scalekit looks up the wrong user’s tokens.

Token freshness — getConnectedAccountByIdentifier (TypeScript) and get_connected_account (Python) always return a fresh token — Scalekit refreshes it before returning if it has expired. You do not need to track expiry or call a refresh endpoint.

First-run blocking — The authorization prompt blocks the process until the user completes OAuth in the browser. In a web application, redirect the user to link instead of printing it, and handle the callback before proceeding.

execute_tool response shape — In Python, response.result is a dictionary whose structure depends on the tool. In TypeScript, response.data?.toJson() converts the protobuf response to a plain object. Log the raw response on first use to understand the shape before passing it to the LLM.

Rate limits — The Google Calendar API and Gmail API both have per-user daily quotas. If your agent runs frequently, add exponential backoff around the API calls and cache calendar events across requests where freshness allows.

Next steps

Add more connectors — The same ensureConnected pattern works for any Scalekit-supported connector. Swap the connector name and replace the Google API calls with the target service’s API. See all supported connectors.
Use the built-in Calendar action — Scalekit also provides a googlecalendar_list_events built-in action. If you don’t need custom query parameters, switch the Calendar tool to execute_tool and remove the getAccessToken call entirely.
Stream the response — Replace generateText with streamText in the Vercel AI SDK to stream the LLM’s summary token-by-token instead of waiting for the full response.
Handle re-authorization — If a user revokes access, getOrCreateConnectedAccount returns an inactive account. Add a re-authorization path to recover gracefully instead of crashing.
Review the agent auth quickstart — For a broader overview of the connected-accounts model and supported providers, see the agent auth quickstart.

Search Scalekit docs with ref.tools

Thu, 26 Mar 2026 00:00:00 GMT

Every time you need to look up a Scalekit API, scope name, or configuration option, you break your flow: open a new tab, search the docs, copy the answer, switch back. With ref.tools configured as an MCP server, your AI coding assistant can search Scalekit documentation inline and return accurate, up-to-date answers without you leaving the editor. Setup takes about two minutes.

The problem

AI coding assistants are good at generating code, but they have two failure modes when it comes to third-party docs:

Hallucination — The model invents an API that doesn’t exist or gets parameter names wrong because its training data is incomplete
Stale knowledge — Even accurate training data goes out of date as SDKs and APIs evolve

Both problems get worse when you’re working with a narrowly scoped platform like Scalekit. The model may have seen very little training data about it, and what it did see may be outdated.

The standard workaround is to paste docs into the chat manually — which means constant context-switching between your editor and a browser. ref.tools solves both problems by connecting your AI assistant directly to live Scalekit documentation through an MCP tool call.

Who needs this

This cookbook is for you if:

✅ You use Cursor, Claude Code, Windsurf, or another MCP-compatible AI assistant
✅ You’re building with Scalekit (auth, SSO, MCP servers, M2M, SCIM)
✅ You want accurate, up-to-date answers without context-switching to a browser

You don’t need this if:

❌ You prefer pasting docs into your chat manually
❌ Your AI assistant doesn’t support MCP

The solution

ref.tools is a documentation search platform that indexes third-party docs — including Scalekit — and exposes them as an MCP tool called ref_search_documentation. Once you add the ref.tools MCP server to your AI assistant, you can prompt it to search Scalekit docs and it will call the tool and return current results directly in chat.

The server supports two transports:

Streamable HTTP (recommended) — Direct HTTP connection using your API key; lower latency, no local process required
stdio (legacy) — Runs a local npx process; works with any MCP client that supports stdio

Set up ref.tools

Get your API key
1. Go to ref.tools and sign in
2. Search for Scalekit to confirm the documentation source is indexed
3. Open the Quick Install panel for Scalekit — your API key is pre-filled in the install commands
4. Copy your API key; you’ll use it in the next step
Add the MCP server to your AI assistant

Pick your tool and apply the matching configuration.

Claude Code

Run this command in your terminal to add the MCP server globally across all projects:
```
claude mcp add --transport http ref-context https://api.ref.tools/mcp \
  --header "x-ref-api-key: YOUR_API_KEY"
```
To scope it to a single project instead, add --scope project to the command.

Cursor

Add the following to .cursor/mcp.json in your project root (or via Settings → MCP):
.cursor/mcp.json
```
{
  "ref-context": {
    "type": "http",
    "url": "https://api.ref.tools/mcp?apiKey=YOUR_API_KEY"
  }
}
```
Windsurf

Add the following to ~/.codeium/windsurf/mcp_config.json:
~/.codeium/windsurf/mcp_config.json
```
{
  "ref-context": {
    "serverUrl": "https://api.ref.tools/mcp?apiKey=YOUR_API_KEY"
  }
}
```
Other (stdio)

For any MCP client that supports stdio, add to your MCP config:
mcp.json
```
{
  "ref-context": {
    "command": "npx",
    "args": ["ref-tools-mcp@latest"],
    "env": {
      "REF_API_KEY": "YOUR_API_KEY"
    }
  }
}
```
This requires Node.js installed locally. The npx command fetches and runs the server on first use.
Verify it’s working
1. Restart your AI assistant (or use its MCP reload command if available)
2. Open a new chat and send this prompt:
```
Use ref to look up how to add OAuth 2.1 authorization to an MCP server with Scalekit
```
3. Your assistant should call the ref_search_documentation tool and return results from docs.scalekit.com
If the tool doesn’t appear, check that you restarted the assistant after saving the config, and that the API key is correct.

Example searches to try

Once ref.tools is connected, use phrases like “use ref to…” or “look up in ref…” to trigger the tool explicitly:

Use ref to find the Scalekit MCP auth quickstart
Look up how to configure SSO with Scalekit
Use ref to find Scalekit M2M token documentation
Search Scalekit docs for SCIM provisioning setup
Use ref to look up Scalekit SDK environment variables

You can also just ask naturally — most assistants will call the tool automatically when the question is about Scalekit.

Common mistakes

API key committed to git

Symptom: Your key appears in git history or a public repository
Cause: Config file with the key inline was committed
Fix: Use an environment variable ($REF_API_KEY) and add the config file to .gitignore if it contains real credentials

Wrong transport for your client

Symptom: MCP server fails to connect or appears as disconnected
Cause: Some clients only support stdio; others support both HTTP and stdio
Fix: Check your client’s MCP documentation. Cursor and Claude Code support streamable HTTP. Older or less common clients may require stdio.

Server name not matching what the client expects

Symptom: Tool calls fail with “unknown tool” or the server doesn’t appear in the tool list
Cause: The config key (e.g., ref-context) doesn’t match what you reference in prompts, or the client uses a different config field name
Fix: Confirm the key in your config file matches the server name shown in your client’s MCP settings panel

Tool not appearing after config change

Symptom: You updated the config but the ref_search_documentation tool isn’t available
Cause: The MCP connection wasn’t refreshed
Fix: Fully restart your AI assistant, or use its MCP reload command (Claude Code: claude mcp list to verify; Cursor: reload the window)

Next steps

For further setup, authentication options, and available documentation sources, see the links below.

Add OAuth 2.1 authorization to MCP servers — the most common thing developers look up using ref
ref.tools — browse all available documentation sources you can add alongside Scalekit
M2M authentication overview — machine-to-machine auth patterns frequently searched via ref

Add Enterprise SSO to Next.js with Auth.js

Tue, 10 Mar 2026 00:00:00 GMT

Enterprise customers don’t want to hand over their employees’ credentials to your app — they want SSO through their own IdP. Auth.js handles sessions well, but it has no concept of per-tenant SAML connections or routing by organization. Scalekit fills that gap: it exposes a single OIDC-compliant endpoint that sits in front of every IdP your customers use. This cookbook wires those two pieces together so your app gets enterprise SSO without writing a line of SAML code.

The problem

Adding enterprise SSO to a Next.js app sounds simple until you start building it:

SAML complexity — every IdP (Okta, Azure AD, Google Workspace, Ping) uses different metadata, certificate rotation schedules, and attribute mappings. You end up maintaining per-IdP configuration forever.
Per-tenant routing — each sign-in attempt needs to resolve to the right connection for that customer. A single clientId in Auth.js doesn’t model this.
Duplicate boilerplate — Okta setup is not Azure AD setup. You write the integration N times, once per IdP your enterprise customers use.
Session ownership — SAML assertions and OIDC tokens are not app sessions. Bridging them correctly (handling expiry, attribute claims, refresh) is error-prone without a clear seam.

Who needs this

This cookbook is for you if:

✅ You’re building a multi-tenant B2B SaaS app
✅ You already use Auth.js for session management and want to keep it
✅ You have enterprise customers who require SSO through their own IdP
✅ You want to avoid ripping out Auth.js to adopt a fully managed auth platform

You don’t need this if:

❌ You’re building a consumer app with no enterprise requirements
❌ Your app has no concept of organizations or tenants
❌ You don’t have customers asking for Okta/Azure AD/Google Workspace integration

The solution

Scalekit exposes a single OIDC-compliant authorization endpoint. Auth.js treats it like any other OIDC provider and manages the session after the callback. You never write SAML code — Scalekit handles the protocol translation, certificate rotation, and attribute normalization for every IdP your customers connect. The routing params (connection_id, organization_id, domain) let you target the right enterprise connection at sign-in time.

Implementation

1. Set up Scalekit

Create an environment in the Scalekit dashboard:

Copy your Issuer URL (e.g. https://yourenv.scalekit.dev), Client ID (skc_...), and Client Secret from API Keys.
Register your redirect URI: http://localhost:3000/auth/callback/scalekit

Auth.js v5 defaults to /auth as its base path — not /api/auth. The callback URL must match exactly or the OAuth flow will fail.
Create an Organization and add an SSO Connection for your test IdP.
Copy the Connection ID (conn_...) — you’ll use it to route sign-in attempts during development.

2. Install dependencies

pnpm add next-auth

Auth.js v5 (next-auth@5) ships as a single package. No separate adapter is needed for JWT sessions.

3. Add the Scalekit provider

providers/scalekit.ts

import type { OAuthConfig, OAuthUserConfig } from "next-auth/providers"

export interface ScalekitProfile extends Record<string, any> {
  sub: string
  email: string
  email_verified: boolean
  name: string
  given_name: string
  family_name: string
  picture: string
  oid: string // organization_id
}

export default function Scalekit<P extends ScalekitProfile>(
  options: OAuthUserConfig<P> & {
    issuer: string
    organizationId?: string
    connectionId?: string
    domain?: string
  }
): OAuthConfig<P> {
  const { issuer, organizationId, connectionId, domain } = options

  return {
    id: "scalekit",
    name: "Scalekit",
    type: "oidc",
    issuer,
    authorization: {
      params: {
        scope: "openid email profile",
        ...(connectionId && { connection_id: connectionId }),
        ...(organizationId && { organization_id: organizationId }),
        ...(domain && { domain }),
      },
    },
    profile(profile) {
      return {
        id: profile.sub,
        name: profile.name ?? `${profile.given_name} ${profile.family_name}`,
        email: profile.email,
        image: profile.picture ?? null,
      }
    },
    style: { bg: "#6f42c1", text: "#fff" },
    options,
  }
}

After PR #13392 merges, replace the local import with:

import Scalekit from "next-auth/providers/scalekit"

4. Configure `auth.ts`

Create auth.ts in your project root:

import NextAuth from "next-auth"
import Scalekit from "./providers/scalekit"  // → "next-auth/providers/scalekit" after PR #13392

export const { handlers, auth, signIn, signOut } = NextAuth({
  providers: [
    Scalekit({
      issuer: process.env.AUTH_SCALEKIT_ISSUER!,
      clientId: process.env.AUTH_SCALEKIT_ID!,
      clientSecret: process.env.AUTH_SCALEKIT_SECRET!,
      // Routing: set one of these (see step 7 for strategy)
      connectionId: process.env.AUTH_SCALEKIT_CONNECTION_ID,
    }),
  ],
  basePath: "/auth",
  session: { strategy: "jwt" },
})

basePath: "/auth" is required to match the redirect URI you registered in step 1. Without it, Auth.js uses /api/auth and the Scalekit callback will fail.

5. Set environment variables

.env.local

# Generate with: npx auth secret
AUTH_SECRET=

# From Scalekit dashboard → API Keys
AUTH_SCALEKIT_ISSUER=https://yourenv.scalekit.dev
AUTH_SCALEKIT_ID=skc_...
AUTH_SCALEKIT_SECRET=

# Connection ID for development routing (conn_...)
# In production, resolve this dynamically per tenant — see step 7
AUTH_SCALEKIT_CONNECTION_ID=conn_...

AUTH_SECRET is not optional. Auth.js uses it to sign JWTs and encrypt session cookies. Missing it causes sign-in to fail silently.

6. Wire up route handlers

Create app/auth/[...nextauth]/route.ts:

import { handlers } from "@/auth"
export const { GET, POST } = handlers

This exposes GET /auth/callback/scalekit and POST /auth/signout — the endpoints Auth.js needs. The directory must be app/auth/ (not app/api/auth/) to match the basePath you configured.

7. SSO routing strategies

Scalekit resolves which IdP connection to activate using these params (highest to lowest precedence):

Scalekit({
  issuer: process.env.AUTH_SCALEKIT_ISSUER!,
  clientId: process.env.AUTH_SCALEKIT_ID!,
  clientSecret: process.env.AUTH_SCALEKIT_SECRET!,

  // Option A — exact connection (dev / single-tenant use)
  connectionId: "conn_...",

  // Option B — org's active connection (multi-tenant: look up org from user's DB record)
  organizationId: "org_...",

  // Option C — resolve org from email domain (useful at login prompt)
  domain: "acme.com",
})

In production, don’t hardcode these values. Store organizationId or connectionId per tenant in your database, then construct the signIn() call dynamically based on the authenticated user’s org:

// Example: look up org at sign-in time
const org = await db.organizations.findByDomain(emailDomain)

await signIn("scalekit", {
  organizationId: org.scalekitOrgId,
  redirectTo: "/dashboard",
})

A server component reads the session, and a sign-in form triggers the flow:

app/page.tsx

import { auth, signIn } from "@/auth"

export default async function Home() {
  const session = await auth()

  if (session) {
    return (
      <div>
        <p>Signed in as {session.user?.email}</p>
      </div>
    )
  }

  return (
    <form
      action={async () => {
        "use server"
        await signIn("scalekit", { redirectTo: "/dashboard" })
      }}
    >
      <button type="submit">Sign in with SSO</button>
    </form>
  )
}

session.user includes name, email, and image normalized from the Scalekit OIDC profile.

Testing

Run pnpm dev and visit http://localhost:3000.
Click Sign in with SSO — you should be redirected to your IdP’s login page.
Complete authentication and confirm you land back on your app.
Check the session at http://localhost:3000/api/auth/session or read it from a server component — you should see user.email populated.

If the redirect fails immediately, enable debug logging to trace the OIDC callback:

AUTH_DEBUG=true pnpm dev

Common mistakes

Wrong redirect URI — registering /api/auth/callback/scalekit instead of /auth/callback/scalekit. Auth.js v5 changed the default basePath from /api/auth to /auth. The URI in Scalekit’s dashboard must match the callback path Auth.js actually uses.
Missing AUTH_SECRET — sign-in appears to start but fails on the callback with no visible error. Always set AUTH_SECRET. Generate one with npx auth secret.
Hardcoding connectionId in production — works in development, breaks for every other tenant. Store connection identifiers per-organization in your database and resolve them at runtime.
Missing basePath in auth.ts — if you omit basePath: "/auth", Auth.js defaults to /api/auth. Your route handler must be at app/api/auth/[...nextauth]/route.ts and your redirect URI must use /api/auth/callback/scalekit. Pick one and be consistent.
Using the wrong import path — next-auth/providers/scalekit only resolves after PR #13392 merges. Until then, the local file at ./providers/scalekit is the correct import.

Production notes

Rotate secrets without code changes — update AUTH_SCALEKIT_SECRET in your environment configuration; Scalekit handles IdP certificate rotation automatically.
Dynamic connection routing — store organizationId or connectionId per tenant in your database. Resolve at sign-in time based on the user’s email domain or their existing tenant membership.
Debug OIDC callback issues — set AUTH_DEBUG=true temporarily in production to emit detailed callback traces. Remove it after diagnosing.
Session persistence — JWT sessions (the default) work without a database. If you need server-side session invalidation, add an Auth.js adapter (e.g. Prisma, Drizzle) and switch to strategy: "database".
Scalekit handles IdP complexity — certificate rotation, SAML metadata updates, and attribute mapping changes happen in the Scalekit dashboard without touching your code.

Next steps

scalekit-developers/scalekit-authjs-example — full working repo for this cookbook
Auth.js PR #13392 — track native Scalekit provider availability
Scalekit SSO routing documentation — full reference for connection_id, organization_id, and domain routing params
Auth.js adapters — add database-backed sessions for server-side invalidation
Scalekit organization management API — look up organizationId dynamically from your tenant records

Build an agent that books meetings and drafts emails

Fri, 06 Mar 2026 00:00:00 GMT

Scheduling a meeting sounds simple: find a free slot, create an event, send a confirmation. But in an agent, each of those steps crosses a tool boundary — and each tool requires its own OAuth token. Without a managed auth layer, you end up writing token-fetching, refresh logic, and error handling three times over before you write a single line of scheduling logic. This cookbook solves that by using Scalekit to own the OAuth lifecycle for each connector, so your agent can focus on the workflow itself.

This is a Python recipe for agents that call two or more external APIs on behalf of a user. If you’re using a service account rather than user-delegated OAuth, or building in JavaScript, the pattern is the same but the source differs — see the javascript/ track in agent-auth-examples. The complete Python source used here is python/meeting_scheduler_agent.py in that repo.

The core problems this solves:

One token per connector — Google Calendar and Gmail use separate OAuth scopes and separate access tokens. Your agent must manage both independently.
First-run authorization is blocking — If the user has not yet authorized a connector, your agent cannot proceed until they complete the browser OAuth flow.
Token expiry is silent — A token that worked yesterday fails today, and the failure looks identical to a permissions error.
Chaining tool outputs is fragile — The event link from the Calendar API needs to appear in the Gmail draft. If the Calendar call fails mid-workflow, the draft gets a broken link or never gets created.

Scalekit exposes a connected_accounts abstraction that maps a user ID to an authorized OAuth session per connector. When your agent calls get_or_create_connected_account, Scalekit either returns an existing active account with a valid token or creates a new one and returns an authorization URL. Once the user authorizes, get_connected_account returns the token. From that point, Scalekit handles refresh automatically.

This means your agent’s authorization step is a single function regardless of which connector you’re targeting. The rest of the code — Calendar queries, event creation, Gmail drafts — is plain HTTP with the token Scalekit provides.

Set up the environment

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 two connections for your environment:
- googlecalendar — Google Calendar OAuth connection
- gmail — Gmail OAuth connection
The script references these names literally. The names must match exactly.

Initialize the Scalekit client

meeting_scheduler_agent.py

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.

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, so the caller sees a clear error rather than a silent wrong result. 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 useful first-draft strategy: simple, readable, easy to debug. Its limits are real (one-hour granularity, UTC-only, primary calendar only) and addressed in Production notes below.

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 also sends an invitation email to each attendee automatically when the event is created; the draft you create in the next step is a separate follow-up, not the invitation itself.

Draft the confirmation email

Build the email body, base64-encode it, and post it to Gmail’s drafts endpoint:

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.")

The script creates a draft, not a sent message. The user reviews it before sending. This is the right default for an agent — it takes the action but keeps a human in the loop for outbound communication.

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

Run the agent from the command line:

python meeting_scheduler_agent.py

On first run, you should see two authorization prompts in sequence:

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, the authorization prompts are skipped and the agent goes straight to availability checking.

Verify the results:

Open Google Calendar — you should see the event on the chosen date
Open Gmail — you should see a draft in the Drafts folder with the event link

Common mistakes

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 match the string you pass to authorize() exactly.
Missing OAuth scopes — If you see a 403 Forbidden when calling the Calendar or Gmail API, the OAuth app in Google Cloud Console is missing the required scopes. Calendar needs https://www.googleapis.com/auth/calendar and 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 error. 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.

Production notes

Timezone handling — The working-hours check (WORK_START_HOUR, WORK_END_HOUR) 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 — The one-hour increment misses 30- and 15-minute openings. For real scheduling, use the busy intervals directly to calculate the gaps between events, then filter by minimum duration.

Multiple calendars — The freeBusy query checks only primary. Users who manage work and personal calendars separately will show false availability. Expand the items list to include all calendars the user has shared access to.

Draft vs send — Creating a draft is safer for a first deployment. When you’re confident in the agent’s output quality, switch the Gmail endpoint from /drafts to /messages/send to make the agent fully autonomous. Add a confirmation step before making this change.

Error recovery — If create_event succeeds but create_draft fails, you have an orphaned event with no follow-up email. In production, wrap the two calls in a compensation pattern: track the event ID and delete it if the draft creation fails.

Rate limits — Google Calendar and Gmail both have per-user quotas. If your agent runs frequently for the same user, add exponential backoff around the requests.post calls.

Next steps

Add user input — Replace the hardcoded ATTENDEE_EMAIL, MEETING_TITLE, and DURATION_MINUTES with parameters parsed from natural language using an LLM tool call.
Build the JavaScript equivalent — The agent-auth-examples repo includes a JavaScript track. Compare the two implementations to see where the patterns converge and where they differ.
Handle re-authorization — If a user revokes access, get_connected_account returns an inactive account. Add a re-authorization path to recover gracefully instead of crashing.
Explore other connectors — The same authorize() pattern works for any Scalekit-supported connector: 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, see the agent auth quickstart.

Configuring JWT Validation Timeouts in Spring Boot 4.0+

Wed, 19 Feb 2025 00:00:00 GMT

If you’re using Spring Boot 4.0.0 or later and experiencing connection timeout errors when validating JWT tokens from Scalekit, you’ll need to explicitly configure timeout values. This is a known issue affecting Spring Security’s OAuth2 resource server configuration.

The problem

Your Spring Boot application successfully configures the issuer-uri for JWT validation:

spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: https://auth.scalekit.com

But authentication fails with timeout errors like:

java.net.SocketTimeoutException: Connect timed out
  at org.springframework.security.oauth2.jwt.JwtDecoders.fromIssuerLocation

Why this happens

Starting with Spring Boot 4.0.0, Spring Security changed how it handles HTTP connections during JWT validation:

Before 4.0.0: Spring used default system timeouts (often much longer)
After 4.0.0: Spring enforces strict, short timeout defaults that can be too aggressive for production

When your application starts or validates its first JWT token, Spring Security:

Fetches the OpenID Connect discovery document from issuer-uri
Retrieves the JWKS (JSON Web Key Set) to verify token signatures
Caches these for future validations

If these initial requests timeout, authentication fails completely.

Who needs this fix

This issue specifically affects:

✅ Spring Boot applications version 4.0.0 or later
✅ Using issuer-uri for JWT validation (not manual jwk-set-uri)
✅ Production environments with network latency or firewall rules
✅ Applications experiencing intermittent authentication failures

You don’t need this if:

❌ Using Spring Boot 3.x or earlier
❌ Manually configuring jwk-set-uri instead of issuer-uri
❌ Already have custom RestTemplate or WebClient configurations

The solution

Configure explicit timeout values for the OAuth2 resource server’s HTTP client. Spring Security provides configuration properties specifically for this:

application.yml
application.properties

spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: https://auth.scalekit.com
          # Configure timeouts for JWKS and discovery endpoints
          client:
            registration:
              connect-timeout: 10000  # 10 seconds for connection
              read-timeout: 10000     # 10 seconds for reading response

spring.security.oauth2.resourceserver.jwt.issuer-uri=https://auth.scalekit.com
# Configure timeouts for JWKS and discovery endpoints
spring.security.oauth2.resourceserver.jwt.client.registration.connect-timeout=10000
spring.security.oauth2.resourceserver.jwt.client.registration.read-timeout=10000

Timeout values explained

connect-timeout: Maximum time (in milliseconds) to establish a connection to Scalekit’s servers
read-timeout: Maximum time (in milliseconds) to wait for a response after connection is established

Recommended values:

Development: 5000ms (5 seconds) for faster feedback
Production: 10000-15000ms (10-15 seconds) to handle network variability

Alternative: Programmatic configuration

If you need more control or want to configure this per-environment, use Java configuration:

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.client.SimpleClientHttpRequestFactory;
import org.springframework.security.oauth2.jwt.JwtDecoder;
import org.springframework.security.oauth2.jwt.NimbusJwtDecoder;
import org.springframework.web.client.RestTemplate;

@Configuration
public class SecurityConfig {

    @Bean
    public JwtDecoder jwtDecoder() {
        // Create a RestTemplate with custom timeouts
        SimpleClientHttpRequestFactory factory = new SimpleClientHttpRequestFactory();
        factory.setConnectTimeout(10000);  // 10 seconds
        factory.setReadTimeout(10000);     // 10 seconds

        RestTemplate restTemplate = new RestTemplate(factory);

        // Use the custom RestTemplate for JWT validation
        return NimbusJwtDecoder
            .withIssuerLocation("https://auth.scalekit.com")
            .restOperations(restTemplate)
            .build();
    }
}

This approach gives you:

Full control over HTTP client configuration
Ability to add custom headers or interceptors
Environment-specific timeout tuning

Verifying the fix

After applying the configuration:

Restart your application - Spring Security initializes the JWT decoder on startup
Test authentication - Make a request with a valid Scalekit JWT token
Check logs - You should see successful JWKS retrieval:

DEBUG o.s.security.oauth2.jwt.JwtDecoder - Retrieved JWKS from https://auth.scalekit.com/.well-known/jwks.json

If you still see timeout errors:

Verify network connectivity to auth.scalekit.com
Check firewall rules allowing outbound HTTPS
Increase timeout values if your network has high latency

When to use standard Spring Security instead

This cookbook addresses a specific Spring Boot 4.0+ timeout issue. For general JWT validation setup:

Follow the Spring Security OAuth2 Resource Server documentation
Use Scalekit’s standard Java SDK for token validation if not using Spring Security
Consider the default issuer-uri configuration if you’re not experiencing timeouts

Implementing Passwordless Auth in Next.js 15

Wed, 19 Feb 2025 00:00:00 GMT

Next.js 15’s App Router expects authentication to be server-first: tokens generated on the server, verification happening in Route Handlers or Server Actions, and sessions stored in HttpOnly cookies. If you’re building passwordless authentication (magic links + OTP), traditional client-side SDKs won’t work properly with this model.

This cookbook shows you how to implement passwordless auth that works natively with Next.js 15’s architecture using Scalekit’s headless API.

The problem

You want passwordless authentication in Next.js 15 but face these challenges:

Client-side SDKs break App Router patterns - They expect browser-side token handling, which violates server-first principles
Vendor UIs don’t match your design - Pre-built login pages force you to compromise on branding
DIY is complex - Building secure token generation, email delivery, verification, and session management from scratch is a significant lift
Cross-device failures - Magic links often break when users switch devices or email clients strip parameters

Who needs this

This cookbook is for you if:

✅ You’re building a Next.js 15 application using App Router
✅ You want passwordless authentication (magic links, OTP, or both)
✅ You need full control over your login UI and email design
✅ You don’t want to migrate your existing user database
✅ You require server-side security for compliance

You don’t need this if:

❌ You’re happy with vendor-hosted login pages
❌ You’re using Next.js Pages Router (not App Router)
❌ You prefer traditional username/password authentication

The solution

Scalekit’s passwordless API provides three server-side methods that integrate directly with Next.js 15’s architecture:

sendPasswordlessEmail() - Generates and sends magic link/OTP to user’s email
verifyPasswordlessEmail() - Validates the token/code and returns verified identity
resendPasswordlessEmail() - Issues a fresh credential if the first expires

All security logic stays server-side, works with Server Actions and Route Handlers, and integrates with Edge Middleware for route protection.

Implementation

1. Configure Scalekit dashboard

Enable passwordless authentication in your Scalekit dashboard:

Navigate to Authentication → Passwordless
Select Magic Link + Verification Code for maximum reliability
Set Expiry Period (e.g., 600 seconds for 10-minute lifetime)
Enable Enforce same browser origin to prevent link hijacking
(Optional) Enable Regenerate credentials on resend to invalidate old links

2. Install dependencies and configure environment

npm install @scalekit-sdk/node jsonwebtoken

Create .env.local:

SCALEKIT_ENVIRONMENT_URL=env_xxxx
SCALEKIT_CLIENT_ID=skc_xxx
SCALEKIT_CLIENT_SECRET=your_secret
APP_URL=http://localhost:3000
JWT_SECRET=your_jwt_secret

3. Create session management utilities

Create lib/session-store.ts to handle server-side session creation:

import jwt from 'jsonwebtoken';
import { cookies } from 'next/headers';

const COOKIE = 'session';
const SECRET = process.env.JWT_SECRET!;

export function createSession(email: string) {
  const token = jwt.sign({ email }, SECRET, { expiresIn: '7d' });
  cookies().set(COOKIE, token, {
    httpOnly: true,
    secure: process.env.NODE_ENV === 'production',
    sameSite: 'lax',
    path: '/',
    maxAge: 60 * 60 * 24 * 7,
  });
}

export function readSessionEmail(): string | null {
  const token = cookies().get(COOKIE)?.value;
  if (!token) return null;

  try {
    const decoded = jwt.verify(token, SECRET) as { email: string };
    return decoded.email;
  } catch {
    return null;
  }
}

export function clearSession() {
  cookies().delete(COOKIE);
}

4. Create send email endpoint

Create app/api/auth/send-passwordless/route.ts:

import Scalekit from '@scalekit-sdk/node';
import { NextRequest, NextResponse } from 'next/server';

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

export async function POST(req: NextRequest) {
  const { email } = await req.json();

  try {
    const response = await scalekit.passwordless.sendPasswordlessEmail(email, {
      template: 'SIGNIN',
      expiresIn: 600, // 10 minutes
      state: crypto.randomUUID(),
      magiclinkAuthUri: `${process.env.APP_URL}/api/auth/verify`,
    });

    return NextResponse.json({
      authRequestId: response.authRequestId,
      expiresAt: response.expiresAt,
    });
  } catch (error) {
    return NextResponse.json(
      { error: 'Failed to send email' },
      { status: 500 }
    );
  }
}

5. Create verification endpoint

Create app/api/auth/verify/route.ts with both GET (magic link) and POST (OTP) handlers:

import Scalekit from '@scalekit-sdk/node';
import { NextRequest, NextResponse } from 'next/server';
import { createSession } from '@/lib/session-store';

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

// Magic link verification
export async function GET(req: NextRequest) {
  const url = new URL(req.url);
  const linkToken = url.searchParams.get('link_token');
  const authRequestId = url.searchParams.get('auth_request_id') ?? undefined;

  if (!linkToken) {
    return NextResponse.redirect(
      new URL('/login?error=missing_token', req.url)
    );
  }

  try {
    const verified = await scalekit.passwordless.verifyPasswordlessEmail(
      { linkToken },
      authRequestId
    );

    createSession(verified.email);
    return NextResponse.redirect(new URL('/dashboard', req.url));
  } catch {
    return NextResponse.redirect(
      new URL('/login?error=verification_failed', req.url)
    );
  }
}

// OTP verification
export async function POST(req: NextRequest) {
  const { code, authRequestId } = await req.json();

  if (!code || !authRequestId) {
    return NextResponse.json(
      { error: 'Missing required fields' },
      { status: 400 }
    );
  }

  try {
    const verified = await scalekit.passwordless.verifyPasswordlessEmail(
      { code },
      authRequestId
    );

    createSession(verified.email);
    return NextResponse.json({ success: true });
  } catch {
    return NextResponse.json(
      { error: 'Invalid or expired code' },
      { status: 400 }
    );
  }
}

6. Add resend endpoint

Create app/api/auth/resend-passwordless/route.ts:

import Scalekit from '@scalekit-sdk/node';
import { NextRequest, NextResponse } from 'next/server';

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

export async function POST(req: NextRequest) {
  const { authRequestId } = await req.json();

  if (!authRequestId) {
    return NextResponse.json(
      { error: 'Missing authRequestId' },
      { status: 400 }
    );
  }

  try {
    const response = await scalekit.passwordless.resendPasswordlessEmail(
      authRequestId
    );

    return NextResponse.json({
      authRequestId: response.authRequestId,
      expiresAt: response.expiresAt,
    });
  } catch {
    return NextResponse.json(
      { error: 'Resend failed' },
      { status: 400 }
    );
  }
}

7. Protect routes with middleware

Create middleware.ts in your project root:

import { NextRequest, NextResponse } from 'next/server';

export function middleware(req: NextRequest) {
  const protectedPath = req.nextUrl.pathname.startsWith('/dashboard');
  const hasSession = Boolean(req.cookies.get('session')?.value);

  if (protectedPath && !hasSession) {
    const url = new URL('/login', req.url);
    url.searchParams.set('next', req.nextUrl.pathname);
    return NextResponse.redirect(url);
  }

  return NextResponse.next();
}

export const config = {
  matcher: ['/dashboard/:path*'],
};

Create app/login/page.tsx:

'use client';

import { useState } from 'react';
import { useRouter } from 'next/navigation';

export default function LoginPage() {
  const [email, setEmail] = useState('');
  const [authRequestId, setAuthRequestId] = useState('');
  const [showOtp, setShowOtp] = useState(false);
  const [otp, setOtp] = useState('');
  const router = useRouter();

  async function handleSendEmail(e: React.FormEvent) {
    e.preventDefault();

    const res = await fetch('/api/auth/send-passwordless', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ email }),
    });

    const data = await res.json();
    setAuthRequestId(data.authRequestId);
    setShowOtp(true);
  }

  async function handleVerifyOtp(e: React.FormEvent) {
    e.preventDefault();

    const res = await fetch('/api/auth/verify', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ code: otp, authRequestId }),
    });

    if (res.ok) {
      router.push('/dashboard');
    }
  }

  return (
    <div>
      {!showOtp ? (
        <form onSubmit={handleSendEmail}>
          <input
            type="email"
            value={email}
            onChange={(e) => setEmail(e.target.value)}
            placeholder="Enter your email"
            required
          />
          <button type="submit">Send magic link</button>
        </form>
      ) : (
        <form onSubmit={handleVerifyOtp}>
          <p>Check your email for a magic link or enter the code below:</p>
          <input
            type="text"
            value={otp}
            onChange={(e) => setOtp(e.target.value)}
            placeholder="Enter 6-digit code"
            maxLength={6}
          />
          <button type="submit">Verify</button>
        </form>
      )}
    </div>
  );
}

Security features

Scalekit enforces these protections automatically:

Rate limiting: 2 emails per minute per address, 5 OTP attempts per 10 minutes
Short-lived tokens: Configure expiry from 60 seconds to 1 hour
Same-browser enforcement: When enabled, links can only be verified from the originating browser
HttpOnly sessions: Tokens never touch client JavaScript

Error handling

Map Scalekit errors to user-friendly messages:

function getErrorMessage(error: string): string {
  if (error.includes('expired')) {
    return 'This link has expired. Request a new one.';
  }
  if (error.includes('rate')) {
    return 'Too many attempts. Please try again later.';
  }
  if (error.includes('invalid')) {
    return 'Invalid code. Please check and try again.';
  }
  return 'Verification failed. Please try again.';
}

Production checklist

Before deploying:

✅ Set secure: true for session cookies (enforced automatically in production)
✅ Configure production Scalekit credentials in environment variables
✅ Verify dashboard settings match your security requirements
✅ Test magic link + OTP flow on multiple email clients
✅ Set up monitoring for authentication errors and rate limit hits
✅ Configure custom email templates with your branding

Complete example

Full working code is available in the Scalekit GitHub repository.

Why this approach works

This implementation:

Works natively with App Router - All sensitive operations are server-side
Maintains full UI control - No vendor widgets or redirects to hosted pages
Handles cross-device gracefully - OTP fallback covers magic link failures
Requires no user migration - Works on top of your existing user store
Stays secure by default - HttpOnly cookies, server-only verification, automatic rate limiting

Building a Custom Organization Switcher

Tue, 21 Jan 2025 00:00:00 GMT

When users belong to multiple organizations, the default Scalekit organization switcher handles most use cases. However, some applications require deeper integration—a custom switcher embedded directly in your app’s navigation, or a specialized UI that matches your design system.

This guide shows you how to build your own organization switcher using Scalekit’s APIs.

Why build a custom switcher?

The default Scalekit-hosted switcher works well for most scenarios. Build a custom switcher when you need:

In-app navigation: Users switch organizations without leaving your application
Custom branding: The switcher matches your application’s design language
Specialized workflows: Your app needs org-specific logic during switches
Reduced redirects: Avoid sending users through the authentication flow for every switch

How the custom switcher works

Your application handles the entire switching flow:

User authenticates through Scalekit and receives a session
Your app fetches the user’s organizations via the User Sessions API
You render your own organization selector UI
When a user selects an organization, your app updates the active context

This approach gives you full control over the UI and routing, but requires you to manage session state and organization context within your application.

Fetch user organizations

The User Sessions API returns the authenticated_organizations field containing all organizations the user can access. Use this data to populate your switcher UI.

Express.js

// Use case: Get user's organizations for your switcher UI
// Security: Always validate session ownership before returning org data
const session = await scalekit.session.getSession(sessionId);

// Extract organizations from the session response
const organizations = session.authenticated_organizations || [];

// Render your organization switcher with this data
res.json({ organizations });

Flask

# Use case: Get user's organizations for your switcher UI
# Security: Always validate session ownership before returning org data
session = scalekit_client.session.get_session(session_id)

# Extract organizations from the session response
organizations = session.get('authenticated_organizations', [])

# Render your organization switcher with this data
return jsonify({'organizations': organizations})

Gin

// Use case: Get user's organizations for your switcher UI
// Security: Always validate session ownership before returning org data
session, err := scalekitClient.Session().GetSession(ctx, sessionId)
if err != nil {
    return err
}

// Extract organizations from the session response
organizations := session.AuthenticatedOrganizations

// Render your organization switcher with this data
c.JSON(http.StatusOK, gin.H{"organizations": organizations})

Spring

// Use case: Get user's organizations for your switcher UI
// Security: Always validate session ownership before returning org data
Session session = scalekitClient.sessions().getSession(sessionId);

// Extract organizations from the session response
List<Organization> organizations = session.getAuthenticatedOrganizations();

// Render your organization switcher with this data
return ResponseEntity.ok(Map.of("organizations", organizations));

The response includes organization IDs, names, and metadata for each organization the user can access.

Add domain context

Enhance your switcher by displaying which domains are associated with each organization. Use the Domains API to fetch this information.

// Example: Fetch domains for an organization
const domains = await scalekit.domains.list({ organizationId: 'org_123' });

// Display "@acme.com" next to the organization name in your UI

This helps users quickly identify the correct organization, especially when they belong to organizations with similar names.

Handle organization selection

When a user selects an organization in your custom switcher, update your application’s context. Store the active organization ID in session storage or a cookie, then use it for subsequent API calls.

Express.js

// Use case: Store selected organization and fetch org-specific data
app.post('/api/select-organization', async (req, res) => {
  const { organizationId } = req.body;
  const sessionId = req.session.scalekitSessionId;

  // Security: Verify the user belongs to this organization
  const session = await scalekit.session.getSession(sessionId);
  const hasAccess = session.authenticated_organizations.some(
    org => org.id === organizationId
  );

  if (!hasAccess) {
    return res.status(403).json({ error: 'Unauthorized' });
  }

  // Store the active organization in the user's session
  req.session.activeOrganizationId = organizationId;

  res.json({ success: true });
});

Flask

# Use case: Store selected organization and fetch org-specific data
@app.route('/api/select-organization', methods=['POST'])
def select_organization():
  data = request.get_json()
  organization_id = data.get('organizationId')
  session_id = session.get('scalekit_session_id')

  # Security: Verify the user belongs to this organization
  user_session = scalekit_client.session.get_session(session_id)
  has_access = any(
    org['id'] == organization_id
    for org in user_session.get('authenticated_organizations', [])
  )

  if not has_access:
    return jsonify({'error': 'Unauthorized'}), 403

  # Store the active organization in the user's session
  session['active_organization_id'] = organization_id

  return jsonify({'success': True})

Gin

// Use case: Store selected organization and fetch org-specific data
func SelectOrganization(c *gin.Context) {
  var req struct {
    OrganizationID string `json:"organizationId"`
  }
  if err := c.BindJSON(&req); err != nil {
    c.JSON(http.StatusBadRequest, gin.H{"error": "Invalid request"})
    return
  }

  sessionID := c.GetString("scalekitSessionID")

  // Security: Verify the user belongs to this organization
  session, err := scalekitClient.Session().GetSession(ctx, sessionID)
  if err != nil {
    c.JSON(http.StatusInternalServerError, gin.H{"error": "Session error"})
    return
  }

  hasAccess := false
  for _, org := range session.AuthenticatedOrganizations {
    if org.ID == req.OrganizationID {
      hasAccess = true
      break
    }
  }

  if !hasAccess {
    c.JSON(http.StatusForbidden, gin.H{"error": "Unauthorized"})
    return
  }

  // Store the active organization in the user's session
  c.SetCookie("activeOrganizationID", req.OrganizationID, 3600, "/", "", true, true)

  c.JSON(http.StatusOK, gin.H{"success": true})
}

Spring

// Use case: Store selected organization and fetch org-specific data
@PostMapping("/api/select-organization")
public ResponseEntity<?> selectOrganization(
  @RequestBody Map<String, String> request,
  HttpSession httpSession
) {
  String organizationId = request.get("organizationId");
  String sessionId = (String) httpSession.getAttribute("scalekitSessionId");

  // Security: Verify the user belongs to this organization
  Session session = scalekitClient.sessions().getSession(sessionId);
  boolean hasAccess = session.getAuthenticatedOrganizations().stream()
    .anyMatch(org -> org.getId().equals(organizationId));

  if (!hasAccess) {
    return ResponseEntity.status(HttpStatus.FORBIDDEN)
      .body(Map.of("error", "Unauthorized"));
  }

  // Store the active organization in the user's session
  httpSession.setAttribute("activeOrganizationId", organizationId);

  return ResponseEntity.ok(Map.of("success", true));
}

Always verify that the user actually belongs to the organization they’re attempting to switch to. The authenticated_organizations array from the session is your source of truth for access control.

When to use the hosted switcher instead

The default Scalekit-hosted switcher is the right choice when:

You want the quickest implementation with minimal code
Your application doesn’t require in-app organization switching
You’re okay with users navigating through the authentication flow to switch organizations

Build a custom switcher when user experience requirements demand deeper integration with your application’s UI and routing.

You may refer to our Sample Org Swithcer application to better understand how the API calls enable this custom org switcher that is embedded inside your application.

Scalekit Docs | Blog

Build a daily briefing agent with Vercel AI SDK and Scalekit Agent Auth

1. Set up connections in Scalekit

2. Install dependencies

3. Configure credentials

4. Initialize the Scalekit client

5. Ensure each connector is authorized

6. Fetch calendar events using the OAuth token pattern

7. Fetch emails using the built-in action pattern

8. Wire the agent together

9. Testing

Common mistakes

Production notes

Next steps

Search Scalekit docs with ref.tools

The problem

Who needs this

The solution

Set up ref.tools

Get your API key

Add the MCP server to your AI assistant

Claude Code

Cursor

Windsurf

Other (stdio)

Verify it’s working

Example searches to try

Common mistakes

Next steps

Add Enterprise SSO to Next.js with Auth.js

The problem

Who needs this

The solution

Implementation

1. Set up Scalekit

2. Install dependencies

3. Add the Scalekit provider

4. Configure auth.ts

5. Set environment variables

6. Wire up route handlers

7. SSO routing strategies

8. Trigger sign-in and read the session

Testing

Common mistakes

Production notes

Next steps

Build an agent that books meetings and drafts emails

Testing

Common mistakes

Production notes

Next steps

Configuring JWT Validation Timeouts in Spring Boot 4.0+

The problem

Why this happens

Who needs this fix

The solution

Timeout values explained

Alternative: Programmatic configuration

Verifying the fix

When to use standard Spring Security instead

Related resources

Implementing Passwordless Auth in Next.js 15

The problem

Who needs this

The solution

Implementation

1. Configure Scalekit dashboard

2. Install dependencies and configure environment

3. Create session management utilities

4. Create send email endpoint

5. Create verification endpoint

6. Add resend endpoint

7. Protect routes with middleware

8. Build login UI (example)

Security features

Error handling

Production checklist

Complete example

Why this approach works

Related resources

4. Configure `auth.ts`