Scalekit Docs | Blog

M2M JWT verification with JWKS and OAuth scopes

Wed, 15 Apr 2026 00:00:00 GMT

When you add OAuth 2.0 client credentials for your APIs, callers receive JWT access tokens. Before you trust any claim, you must verify the signature using Scalekit’s public keys (JWKS). After verification, you authorize the request—often by checking OAuth scopes carried in the token.

This cookbook explains how JWKS and scopes fit together for Scalekit M2M flows: where keys live, how verification works at a high level, how scopes are defined and stored, and how to enforce them in your service.

Why JWKS and scopes belong in one place

JWKS answers “is this token real?” — You use the key identified by kid in the JWT header to validate the signature (typically RS256).
Scopes answer “what may this client do?” — After the token is valid, you inspect the scopes claim (and your routing rules) to allow or deny the operation.

Skipping either step breaks your security model: verified-but-overpowered clients, or unverified tokens.

JWKS and Scalekit keys

A JSON Web Key Set (JWKS) is JSON that lists one or more JWKs—public key material identified by a kid (key ID). Scalekit puts the matching kid in the JWT header so your validator can pick the right key without baking certificates into your app.

Each environment publishes signing keys at:

GET https://<SCALEKIT_ENVIRONMENT_URL>/keys

Use the same base URL as /oauth/token (for example https://your-app.scalekit.dev).

Example response shape:

Example JWKS document

{
  "keys": [
    {
      "use": "sig",
      "kty": "RSA",
      "kid": "snk_58327480989122566",
      "alg": "RS256",
      "n": "…",
      "e": "AQAB"
    }
  ]
}

For access tokens, use the key where use is sig and alg is RS256.

Verify an access token

At implementation time, your API typically:

Extracts the bearer token from Authorization: Bearer <token>.
Decodes the JWT header (base64url, first segment) and reads kid and alg. Do not trust the payload until the signature checks out.
Resolves the signing key — fetch https://<SCALEKIT_ENVIRONMENT_URL>/keys, or use a JWKS client (for example jwks-rsa in Node.js) with caching and refresh when you see an unknown kid.
Verifies the signature with your JWT library (RS256 for Scalekit access tokens).
Validates claims such as exp, iss (your environment URL), and aud if your API relies on audience restrictions.
Authorizes the operation using application claims—especially scopes (covered in the next section).

Operational practices

Cache JWKS responses; refetch when verification fails with an unknown kid (key rotation).
Fail closed on bad signature, wrong issuer, or expired token (401; use 403 when the token is valid but not allowed).
Never skip signature verification based on the payload alone.

OAuth scopes for machine clients

Scopes are permission names you attach to an OAuth client. In M2M flows they describe what a client may do—separate from who it is (client_id / sub).

Why scopes matter

Without scopes, any valid client could hit any endpoint. Scopes let you apply least privilege, document what each integration is for, and enforce rules in your API by reading the scopes array on the JWT.

How scopes work in Scalekit M2M

When you register an API client for an organization, you pass a scopes array (REST or SDKs).
Scalekit stores those scopes and includes them on issued access tokens.
Your API verifies the JWT (steps above), then checks that scopes includes what the route requires.

Use a consistent naming pattern such as resource:action (for example deployments:read, deployments:write).

Register scopes on the client

Scopes are set at client creation (and when you update the client via the API). Example:

scopes on create client (illustrative)

"scopes": [
  "deploy:applications",
  "read:deployments"
]

The same values appear on the client record and in issued tokens.

Validate scopes on your API

After the token is verified:

Read scopes from the payload, for example:
scopes in JWT payload (example)
```
"scopes": [
  "deploy:applications",
  "read:deployments"
]
```
Compare what the token grants to what the route allows (for example require deploy:applications on POST /deploy); return 403 if a required scope is missing.
Use SDK helpers where they fit your stack to combine signature and scope checks (see the quickstart).

Add OAuth 2.0 to your APIs — client registration, tokens, examples
API keys — long-lived keys; patterns may differ from OAuth client credentials
Authenticate customer apps — customer-facing API auth and JWKS examples

Set up AgentKit with your coding agent

Wed, 15 Apr 2026 00:00:00 GMT

Install the Scalekit Auth Stack plugin into your coding agent and paste one prompt. The agent generates client initialization, connected account management, OAuth authorization, and token handling — no boilerplate required.

Before you start

A Scalekit account at app.scalekit.com
A connector configured under Agent Auth → Connections (for example, gmail)
Your API credentials from Developers → API Credentials

Pick your coding agent

Terminal

claude plugin marketplace add scalekit-inc/claude-code-authstack && claude plugin install agent-auth@scalekit-auth-stack

Installing the plugin sets up Scalekit’s MCP server and triggers an OAuth authorization flow in your browser. Complete the authorization before continuing — this gives Claude Code direct access to your Scalekit environment to search docs, manage connections, and check connected account status.

Then paste this prompt:

Implementation prompt

Configure Scalekit agent authentication for [connector-name]. Provide code to create a connected account, generate an authorization link, retrieve the token, and call the API on behalf of the user.

Terminal

curl -fsSL https://raw.githubusercontent.com/scalekit-inc/codex-authstack/main/install.sh | bash

Restart Codex → Plugin Directory → Scalekit Auth Stack → install agent-auth. If a browser authorization prompt appears, complete the OAuth flow before continuing. Then paste the implementation prompt above.

Terminal

copilot plugin marketplace add scalekit-inc/github-copilot-authstack
copilot plugin install agent-auth@scalekit-auth-stack

Then run:

Terminal

copilot "Configure Scalekit agent authentication for [connector-name]. Provide code to create a connected account, generate an authorization link, retrieve the token, and call the API on behalf of the user."

Terminal

curl -fsSL https://raw.githubusercontent.com/scalekit-inc/cursor-authstack/main/install.sh | bash

Reload Cursor → Settings → Plugins → enable Agent Auth. If a browser authorization prompt appears, complete the OAuth flow before continuing. Open chat (Cmd+L / Ctrl+L) and paste the implementation prompt above.

Terminal

npx skills add scalekit-inc/skills --skill integrating-agent-auth

Then ask your agent to configure Scalekit authentication for your connector and generate connected account, auth link, and token-fetch code.

Supported agents include Claude Code, Cursor, GitHub Copilot CLI, OpenCode, Windsurf, Cline, Gemini CLI, Codex, and 30+ others.

Verify the setup

Set environment variables — copy SCALEKIT_CLIENT_ID, SCALEKIT_CLIENT_SECRET, and SCALEKIT_ENV_URL from the dashboard → API Credentials.
Trigger the authorization flow — run the generated example and confirm the browser redirects to the connector’s consent page.
Fetch a token — after consent, call the token-fetch function and confirm you receive a valid response.

Troubleshooting

The agent generated code for a connector I haven’t configured yet

The plugin uses the connector name you provide in the prompt. If that connector isn’t configured in your Scalekit Dashboard, the OAuth flow will fail at runtime with a “connector not found” error.

Fix: go to Agent Auth → Connections in the Scalekit Dashboard, create the connection, then re-run the agent prompt with the exact connection name from the dashboard.

I want to swap connectors after the initial generation

Re-run the implementation prompt with the new connector name. The agent updates the connector reference in the client initialization and regenerates the token-fetch call. Existing connected accounts for the old connector are not affected.

The scaffolded code references an SDK version that doesn’t match my lockfile

The plugin targets the latest stable Scalekit SDK. If your lockfile pins an older version, either upgrade the SDK (npm install @scalekit-sdk/node@latest or equivalent) or ask the agent to regenerate using your pinned version by adding “use SDK version X.Y.Z” to the prompt.

Enforce seat limits with SCIM provisioning

Tue, 14 Apr 2026 00:00:00 GMT

SCIM (System for Cross-domain Identity Management) provisioning runs unsupervised. When a customer’s HR system pushes user #51 to a 50-seat plan, your application will create that user unless you explicitly block it. Scalekit delivers the provisioning events; your application decides whether to act on them.

This cookbook shows the two-event pattern that keeps your seat count accurate and tells admins when they need to upgrade their plan.

SCIM does not enforce seat limits — your app must

Scalekit translates IdP-specific provisioning protocols into a consistent set of webhook events. It does not know your billing model, your seat limits, or which organizations have room for more users. That logic lives in your application.

When a user is added in the IdP, Scalekit fires organization.directory.user_created. When a user is removed or deactivated, Scalekit fires organization.directory.user_deleted. Your webhook handler is the gate between those events and your user table.

Two webhook events carry the full user lifecycle

Both events include the organization_id, which lets you look up the seat limit for that specific customer.

Event	When it fires	What to do
`organization.directory.user_created`	IdP adds or activates a user	Check count — create user or block and notify
`organization.directory.user_deleted`	IdP removes or deactivates a user	Decrement count — clear any blocked-provisioning flag

Track a user count per organization in your database

Add a table that stores the provisioned user count and seat limit for each organization. The examples below use plain SQL — translate to your ORM if preferred.

db/schema.sql

CREATE TABLE org_seat_usage (
  org_id       TEXT PRIMARY KEY,
  seat_limit   INTEGER NOT NULL,
  used_seats   INTEGER NOT NULL DEFAULT 0
);

Seed this table when you onboard a new customer. Update seat_limit whenever the customer upgrades or downgrades their plan.

Block creation when the count reaches the limit

The user_created handler increments the seat counter and creates the user only when there is room. Always return 200 to Scalekit — returning an error code causes Scalekit to retry delivery, which does not help when the block is intentional.

webhook-handler.ts

import express from 'express'

const app = express()
app.use(express.json())

app.post('/webhooks/scalekit', async (req, res) => {
  const event = req.body

  if (event.type === 'organization.directory.user_created') {
    const orgId = event.organization_id
    const directoryUser = event.data
    let seatLimitReached = false

    // Run the check and insert in a single transaction.
    // FOR UPDATE inside the transaction holds the lock until commit.
    await db.transaction(async (tx) => {
      const usage = await tx.queryOne(
        'SELECT seat_limit, used_seats FROM org_seat_usage WHERE org_id = $1 FOR UPDATE',
        [orgId]
      )

      if (!usage || usage.used_seats >= usage.seat_limit) {
        seatLimitReached = true
        return
      }

      await tx.query(
        'INSERT INTO users (id, org_id, email, name) VALUES ($1, $2, $3, $4)',
        [directoryUser.id, orgId, directoryUser.email, directoryUser.name]
      )
      await tx.query(
        'UPDATE org_seat_usage SET used_seats = used_seats + 1 WHERE org_id = $1',
        [orgId]
      )
    })

    if (seatLimitReached) {
      // Seat limit reached — skip user creation and alert the admin.
      await notifyAdminSeatLimitReached(orgId)
    }
  }

  // Return 200 so Scalekit does not retry this event.
  res.sendStatus(200)
})

webhook_handler.py

from flask import Flask, request

app = Flask(__name__)

@app.route('/webhooks/scalekit', methods=['POST'])
def handle_webhook():
    event = request.get_json()

    if event.get('type') == 'organization.directory.user_created':
        org_id = event['organization_id']
        directory_user = event['data']
        seat_limit_reached = False

        # Run the check and insert in a single transaction.
        # FOR UPDATE inside the transaction holds the lock until commit.
        with db.transaction() as tx:
            usage = tx.query_one(
                'SELECT seat_limit, used_seats FROM org_seat_usage '
                'WHERE org_id = %s FOR UPDATE',
                (org_id,)
            )

            if not usage or usage['used_seats'] >= usage['seat_limit']:
                seat_limit_reached = True
            else:
                tx.execute(
                    'INSERT INTO users (id, org_id, email, name) VALUES (%s, %s, %s, %s)',
                    (directory_user['id'], org_id,
                     directory_user['email'], directory_user['name'])
                )
                tx.execute(
                    'UPDATE org_seat_usage SET used_seats = used_seats + 1 '
                    'WHERE org_id = %s',
                    (org_id,)
                )

        if seat_limit_reached:
            # Seat limit reached — skip user creation and alert the admin.
            notify_admin_seat_limit_reached(org_id)

    # Return 200 so Scalekit does not retry this event.
    return '', 200

webhook_handler.go

package main

import (
  "encoding/json"
  "net/http"
)

func webhookHandler(w http.ResponseWriter, r *http.Request) {
  var event map[string]interface{}
  if err := json.NewDecoder(r.Body).Decode(&event); err != nil {
    http.Error(w, "bad request", http.StatusBadRequest)
    return
  }

  if event["type"] == "organization.directory.user_created" {
    orgID := event["organization_id"].(string)
    data := event["data"].(map[string]interface{})
    seatLimitReached := false

    // Run the check and insert in a single transaction.
    // FOR UPDATE inside the transaction holds the lock until commit.
    tx, _ := db.Begin()
    var seatLimit, usedSeats int
    err := tx.QueryRow(
      "SELECT seat_limit, used_seats FROM org_seat_usage WHERE org_id = $1 FOR UPDATE",
      orgID,
    ).Scan(&seatLimit, &usedSeats)

    if err != nil || usedSeats >= seatLimit {
      seatLimitReached = true
      tx.Rollback()
    } else {
      tx.Exec(
        "INSERT INTO users (id, org_id, email, name) VALUES ($1, $2, $3, $4)",
        data["id"], orgID, data["email"], data["name"],
      )
      tx.Exec(
        "UPDATE org_seat_usage SET used_seats = used_seats + 1 WHERE org_id = $1",
        orgID,
      )
      tx.Commit()
    }

    if seatLimitReached {
      // Seat limit reached — skip user creation and alert the admin.
      notifyAdminSeatLimitReached(orgID)
    }
  }

  // Return 200 so Scalekit does not retry this event.
  w.WriteHeader(http.StatusOK)
}

WebhookController.java

import org.springframework.web.bind.annotation.*;
import java.util.Map;
import java.util.concurrent.atomic.AtomicBoolean;

@RestController
public class WebhookController {

  @PostMapping("/webhooks/scalekit")
  public ResponseEntity<Void> handleWebhook(@RequestBody Map<String, Object> event) {
    if ("organization.directory.user_created".equals(event.get("type"))) {
      String orgId = (String) event.get("organization_id");
      Map<String, Object> directoryUser = (Map<String, Object>) event.get("data");
      AtomicBoolean seatLimitReached = new AtomicBoolean(false);

      // Run the check and insert in a single transaction.
      // FOR UPDATE inside the transaction holds the lock until commit.
      transactionTemplate.execute(status -> {
        OrgSeatUsage usage = db.queryForObject(
          "SELECT seat_limit, used_seats FROM org_seat_usage WHERE org_id = ? FOR UPDATE",
          OrgSeatUsage.class, orgId
        );

        if (usage == null || usage.getUsedSeats() >= usage.getSeatLimit()) {
          seatLimitReached.set(true);
          return null;
        }

        db.update(
          "INSERT INTO users (id, org_id, email, name) VALUES (?, ?, ?, ?)",
          directoryUser.get("id"), orgId,
          directoryUser.get("email"), directoryUser.get("name")
        );
        db.update(
          "UPDATE org_seat_usage SET used_seats = used_seats + 1 WHERE org_id = ?",
          orgId
        );
        return null;
      });

      if (seatLimitReached.get()) {
        // Seat limit reached — skip user creation and alert the admin.
        notifyAdminSeatLimitReached(orgId);
      }
    }

    // Return 200 so Scalekit does not retry this event.
    return ResponseEntity.ok().build();
  }
}

Decrement the count when a user is removed

The user_deleted handler decreases the seat counter and clears any pending seat-limit notification. This lets the next user_created event succeed without manual intervention from your team.

webhook-handler.ts

if (event.type === 'organization.directory.user_deleted') {
  const orgId = event.organization_id
  const directoryUser = event.data

  await db.transaction(async (tx) => {
    // Remove the user and decrement the counter atomically.
    await tx.query('DELETE FROM users WHERE id = $1', [directoryUser.id])
    await tx.query(
      'UPDATE org_seat_usage SET used_seats = GREATEST(used_seats - 1, 0) WHERE org_id = $1',
      [orgId]
    )
    // Clear any pending seat-limit notification so the next user can be provisioned.
    await tx.query(
      "DELETE FROM notifications WHERE org_id = $1 AND type = 'seat_limit_reached'",
      [orgId]
    )
  })
}

webhook_handler.py

if event.get('type') == 'organization.directory.user_deleted':
    org_id = event['organization_id']
    directory_user = event['data']

    with db.transaction() as tx:
        # Remove the user and decrement the counter atomically.
        tx.execute('DELETE FROM users WHERE id = %s', (directory_user['id'],))
        tx.execute(
            'UPDATE org_seat_usage SET used_seats = GREATEST(used_seats - 1, 0) '
            'WHERE org_id = %s',
            (org_id,)
        )
        # Clear any pending seat-limit notification so the next user can be provisioned.
        tx.execute(
            "DELETE FROM notifications WHERE org_id = %s AND type = 'seat_limit_reached'",
            (org_id,)
        )

webhook_handler.go

if event["type"] == "organization.directory.user_deleted" {
  orgID := event["organization_id"].(string)
  data := event["data"].(map[string]interface{})

  tx, _ := db.Begin()
  // Remove the user and decrement the counter atomically.
  tx.Exec("DELETE FROM users WHERE id = $1", data["id"])
  tx.Exec(
    "UPDATE org_seat_usage SET used_seats = GREATEST(used_seats - 1, 0) WHERE org_id = $1",
    orgID,
  )
  // Clear any pending seat-limit notification so the next user can be provisioned.
  tx.Exec(
    "DELETE FROM notifications WHERE org_id = $1 AND type = 'seat_limit_reached'",
    orgID,
  )
  tx.Commit()
}

WebhookController.java

if ("organization.directory.user_deleted".equals(event.get("type"))) {
  String orgId = (String) event.get("organization_id");
  Map<String, Object> directoryUser = (Map<String, Object>) event.get("data");

  transactionTemplate.execute(status -> {
    // Remove the user and decrement the counter atomically.
    db.update("DELETE FROM users WHERE id = ?", directoryUser.get("id"));
    db.update(
      "UPDATE org_seat_usage SET used_seats = GREATEST(used_seats - 1, 0) WHERE org_id = ?",
      orgId
    );
    // Clear any pending seat-limit notification so the next user can be provisioned.
    db.update(
      "DELETE FROM notifications WHERE org_id = ? AND type = 'seat_limit_reached'",
      orgId
    );
    return null;
  });
}

Notify admins without spamming them

A new user_created event fires for every blocked user. Without deduplication, your admin will receive one email per rejected provisioning attempt. Use an idempotent insert to fire the notification only once per organization until the condition is resolved.

db/schema.sql

CREATE TABLE notifications (
  id         SERIAL PRIMARY KEY,
  org_id     TEXT NOT NULL,
  type       TEXT NOT NULL,
  resolved   BOOLEAN NOT NULL DEFAULT FALSE,
  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
  UNIQUE (org_id, type, resolved)
);

The UNIQUE (org_id, type, resolved) constraint blocks duplicate active notifications. Insert with ON CONFLICT DO NOTHING to skip the insert when a notification already exists:

notify.ts

async function notifyAdminSeatLimitReached(orgId: string) {
  // Insert only if no unresolved notification exists for this org.
  const result = await db.query(
    `INSERT INTO notifications (org_id, type, resolved)
     VALUES ($1, 'seat_limit_reached', FALSE)
     ON CONFLICT (org_id, type, resolved) DO NOTHING`,
    [orgId]
  )

  // rowCount is 0 when the conflict was skipped — admin already notified.
  if (result.rowCount === 0) return

  // Send the alert once: email, Slack, in-app — your choice.
  await sendAdminAlert(orgId, 'Seat limit reached — users are not being provisioned.')
}

notify.py

def notify_admin_seat_limit_reached(org_id: str) -> None:
    # Insert only if no unresolved notification exists for this org.
    result = db.execute(
        """INSERT INTO notifications (org_id, type, resolved)
           VALUES (%s, 'seat_limit_reached', FALSE)
           ON CONFLICT (org_id, type, resolved) DO NOTHING""",
        (org_id,)
    )

    # rowcount is 0 when the conflict was skipped — admin already notified.
    if result.rowcount == 0:
        return

    # Send the alert once: email, Slack, in-app — your choice.
    send_admin_alert(org_id, 'Seat limit reached — users are not being provisioned.')

notify.go

func notifyAdminSeatLimitReached(orgID string) {
  // Insert only if no unresolved notification exists for this org.
  result, _ := db.Exec(
    `INSERT INTO notifications (org_id, type, resolved)
     VALUES ($1, 'seat_limit_reached', FALSE)
     ON CONFLICT (org_id, type, resolved) DO NOTHING`,
    orgID,
  )

  // RowsAffected is 0 when the conflict was skipped — admin already notified.
  rows, _ := result.RowsAffected()
  if rows == 0 {
    return
  }

  // Send the alert once: email, Slack, in-app — your choice.
  sendAdminAlert(orgID, "Seat limit reached — users are not being provisioned.")
}

NotificationService.java

public void notifyAdminSeatLimitReached(String orgId) {
  // Insert only if no unresolved notification exists for this org.
  int rows = db.update(
    "INSERT INTO notifications (org_id, type, resolved) " +
    "VALUES (?, 'seat_limit_reached', FALSE) " +
    "ON CONFLICT (org_id, type, resolved) DO NOTHING",
    orgId
  );

  // rows is 0 when the conflict was skipped — admin already notified.
  if (rows == 0) return;

  // Send the alert once: email, Slack, in-app — your choice.
  sendAdminAlert(orgId, "Seat limit reached — users are not being provisioned.");
}

When a user is removed and the count drops below the limit, the user_deleted handler deletes the notification row. The next blocked user_created event will insert a fresh notification and trigger a new alert.

Related guides

SCIM provisioning quickstart — set up webhooks and the Directory API, including signature verification
Directory webhook events reference — full event payload schemas

Summarize GitHub PRs with Render Workflows

Sat, 11 Apr 2026 00:00:00 GMT

Every engineering team has open PRs that sit in review longer than they should. Before a standup, someone has to open GitHub, scan the list, read comments, and figure out what’s actually blocking. This recipe automates that briefing.

The workflow finds the five most-discussed open PRs in any repository, reads the raw code diff and comment thread for each one, and calls Claude to write one paragraph per PR in plain language — covering what the change does, how much review activity it has, and whether it looks close to merging.

What makes it multi-user: every team member runs the same deployed workflow with their own userId. Scalekit’s token vault stores a separate GitHub OAuth token per user and injects the right one automatically. The agent acts as each person — not a shared service account.

What this recipe covers:

Setting up the Scalekit GitHub connector (one-time, per environment)
Writing four durable tasks with the Render Workflows SDK: list PRs, fetch details, generate summaries, root orchestrator
Connecting each user’s GitHub account via a one-time OAuth flow
Running locally and triggering the deployed workflow via CLI

The complete source is available in the render-ai-agent-deploykit repository.

Each team member connects their GitHub account once via setupGitHubAuth. Scalekit stores the token — at runtime it’s injected automatically based on userId.

1. Set up the Scalekit GitHub connector

This is a one-time setup per Scalekit environment. It creates the GitHub OAuth app that authenticates your team’s accounts to the agent.

Go to app.scalekit.com → Agent Auth → Connectors
Click Add connector and select GitHub
Follow the setup — Scalekit creates and manages the GitHub OAuth app for you
Note the connection name assigned (e.g. github-qkHFhMip) — you’ll set this as GITHUB_CONNECTION_NAME in your environment

2. Create the project

Terminal

mkdir render-pr-summarizer && cd render-pr-summarizer
npm init -y    # or: pnpm init
npm install @renderinc/sdk @scalekit-sdk/node openai dotenv
npm install -D typescript tsx @types/node

tsconfig.json

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "outDir": "dist",
    "strict": true
  },
  "include": ["src"]
}

package.json (scripts)

{
  "type": "module",
  "scripts": {
    "dev": "tsx src/main.ts",
    "build": "tsc",
    "start": "node dist/main.js"
  }
}

3. Configure credentials

Terminal

cp .env.example .env

.env

# LiteLLM proxy (routes to Claude)
LITELLM_API_KEY=your-litellm-api-key
LITELLM_BASE_URL=https://llm.scalekit.cloud
LITELLM_MODEL=claude-haiku-4-5

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

# Connection name from Step 1
GITHUB_CONNECTION_NAME=github-qkHFhMip

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

4. Initialize the Scalekit client

src/scalekit.ts

import "dotenv/config";
import { ScalekitClient } from "@scalekit-sdk/node";

let _scalekit: ScalekitClient | null = null;

function getScalekit(): ScalekitClient {
  if (_scalekit) return _scalekit;
  if (!process.env.SCALEKIT_ENVIRONMENT_URL || !process.env.SCALEKIT_CLIENT_ID || !process.env.SCALEKIT_CLIENT_SECRET) {
    throw new Error("Missing SCALEKIT_ENVIRONMENT_URL, SCALEKIT_CLIENT_ID, or SCALEKIT_CLIENT_SECRET");
  }
  _scalekit = new ScalekitClient(
    process.env.SCALEKIT_ENVIRONMENT_URL,
    process.env.SCALEKIT_CLIENT_ID,
    process.env.SCALEKIT_CLIENT_SECRET,
  );
  return _scalekit;
}

// Lazy proxy — the client is only created when first used
export const scalekit = new Proxy({} as ScalekitClient, {
  get(_target, prop) {
    return (getScalekit() as unknown as Record<string | symbol, unknown>)[prop];
  },
});

const GITHUB_CONNECTION_NAME = process.env.GITHUB_CONNECTION_NAME ?? "github-qkHFhMip";

/**
 * Execute a pre-built GitHub tool via Scalekit on behalf of a user.
 * Scalekit injects the user's stored OAuth token automatically.
 */
export async function githubTool(
  identifier: string,
  toolName: string,
  toolInput: Record<string, unknown>,
) {
  const res = await scalekit.actions.executeTool({
    toolName,
    toolInput,
    connector: GITHUB_CONNECTION_NAME,
    identifier,
  });
  return res.data ?? {};
}

/**
 * Create or retrieve a connected account for a user and return an OAuth
 * authorization URL. The user opens the link once; Scalekit stores the token.
 */
export async function getGitHubAuthLink(identifier: string): Promise<string> {
  await scalekit.actions.getOrCreateConnectedAccount({
    connectionName: GITHUB_CONNECTION_NAME,
    identifier,
  });
  const res = await scalekit.actions.getAuthorizationLink({
    connectionName: GITHUB_CONNECTION_NAME,
    identifier,
  });
  return res.link ?? "";
}

5. Write the workflow tasks

Render Workflows are built from task() functions. Each task is independently retried, tracked, and visible in the Render Dashboard.

src/main.ts

import "dotenv/config";
import { task } from "@renderinc/sdk/workflows";
import OpenAI from "openai";
import { githubTool, getGitHubAuthLink } from "./scalekit.js";

interface PRSummaryInput { userId: string; owner: string; repo: string; }
interface PRDetail {
  number: number; title: string; totalComments: number;
  diff: string; commentBodies: string[];
}

Task 1 — List open PRs and rank by discussion volume

executeTool with github_pull_requests_list returns { array: [...] } — Scalekit wraps array responses in an envelope. The code handles all known shapes gracefully.

src/main.ts

const fetchOpenPRs = task(
  { name: "fetchOpenPRs", retry: { maxRetries: 3, waitDurationMs: 1000 } },
  async function fetchOpenPRs(userId: string, owner: string, repo: string) {
    const raw = await githubTool(userId, "github_pull_requests_list", {
      owner,
      repo,
      state: "open",
    });

    // Scalekit wraps array responses — handle all known shapes
    const r = raw as Record<string, unknown>;
    const list = Array.isArray(raw) ? raw
      : Array.isArray(r.array) ? r.array
      : Array.isArray(r.pull_requests) ? r.pull_requests
      : Array.isArray(r.data) ? r.data
      : null;

    if (!list) {
      throw new Error(`Unexpected response shape: ${JSON.stringify(raw).slice(0, 200)}`);
    }

    type PRItem = { number: number; title: string; comments: number; review_comments: number };
    const sorted = (list as PRItem[]).sort(
      (a, b) => (b.comments + b.review_comments) - (a.comments + a.review_comments),
    );
    return sorted.slice(0, 5);
  },
);

Task 2 — Fetch the raw diff and comments for each PR

GitHub’s public API is called directly for the diff (Accept: application/vnd.github.diff) and the issue comments list. Diffs are truncated to 3000 characters to keep LLM context manageable. Both requests fire in parallel per PR.

src/main.ts

const fetchPRDetails = task(
  { name: "fetchPRDetails", retry: { maxRetries: 3, waitDurationMs: 1000 } },
  async function fetchPRDetails(
    userId: string,
    owner: string,
    repo: string,
    prNumber: number,
    title: string,
    totalComments: number,
  ): Promise<PRDetail> {
    const base = `https://api.github.com/repos/${owner}/${repo}`;
    const [diffRes, commentsRes] = await Promise.all([
      fetch(`${base}/pulls/${prNumber}`, { headers: { Accept: "application/vnd.github.diff" } }),
      fetch(`${base}/issues/${prNumber}/comments`),
    ]);

    const diff = diffRes.ok ? (await diffRes.text()).slice(0, 3000) : "";
    const commentsJson = commentsRes.ok
      ? (await commentsRes.json() as Array<{ body?: string }>)
      : [];
    const commentBodies = commentsJson.slice(0, 20).map((c) => c.body ?? "").filter(Boolean);

    return { number: prNumber, title, totalComments, diff, commentBodies };
  },
);

Task 3 — Generate the summary with Claude

A single LLM call processes all five PRs. The openai package points to LiteLLM via LITELLM_BASE_URL, which routes to Claude.

src/main.ts

const generateSummary = task(
  { name: "generateSummary", retry: { maxRetries: 3, waitDurationMs: 2000 } },
  async function generateSummary(prs: PRDetail[], owner: string, repo: string): Promise<string> {
    if (prs.length === 0) return "No open pull requests found.";

    const client = new OpenAI({
      apiKey: process.env.LITELLM_API_KEY ?? process.env.OPENAI_API_KEY,
      ...(process.env.LITELLM_BASE_URL ? { baseURL: process.env.LITELLM_BASE_URL } : {}),
    });

    const prBlocks = prs.map((pr) => {
      const commentSection = pr.commentBodies.length > 0
        ? `Discussion (${pr.totalComments} comments):\n${pr.commentBodies.slice(0, 5).map((c) => `> ${c.slice(0, 300).replace(/\n/g, " ")}`).join("\n")}`
        : "No comments yet.";
      return [
        `PR #${pr.number} — ${pr.title}`,
        commentSection,
        `Code changes (first 3000 chars):\n${pr.diff || "(diff not available)"}`,
      ].join("\n");
    }).join("\n\n---\n\n");

    const response = await client.chat.completions.create({
      model: process.env.LITELLM_MODEL ?? "claude-haiku-4-5",
      messages: [
        {
          role: "system",
          content: [
            "You are summarizing GitHub pull request activity for a team lead or manager.",
            "For each pull request, write exactly one paragraph (3-4 sentences) in plain, non-technical language.",
            "Cover: what the change is about, how much discussion has happened, and whether it appears close to being merged.",
            "Do not use bullet points or code snippets.",
            "",
            "Format each PR like this:",
            "**PR #[number] — [title]**",
            "[Your paragraph here]",
          ].join("\n"),
        },
        {
          role: "user",
          content: `Repository: ${owner}/${repo}\n\nTop open PRs by discussion volume:\n\n${prBlocks}`,
        },
      ],
    });

    return response.choices[0].message.content ?? "(no summary generated)";
  },
);

Root task — orchestrate everything

fetchPRDetails calls for all five PRs fire in parallel with Promise.all.

src/main.ts

task(
  { name: "summarizePRs", timeoutSeconds: 120 },
  async function summarizePRs(input: PRSummaryInput) {
    const { userId, owner, repo } = input;

    const topPRs = await fetchOpenPRs(userId, owner, repo);
    if (topPRs.length === 0) {
      return { repository: `${owner}/${repo}`, prsAnalyzed: [], summary: "No open pull requests found." };
    }

    const details = await Promise.all(
      topPRs.map((pr) =>
        fetchPRDetails(userId, owner, repo, pr.number, pr.title, pr.comments + pr.review_comments),
      ),
    );

    const summary = await generateSummary(details, owner, repo);

    return {
      repository: `${owner}/${repo}`,
      prsAnalyzed: topPRs.map((p) => `#${p.number}: ${p.title}`),
      summary,
    };
  },
);

6. Add the one-time auth setup task

Each team member runs this once to connect their GitHub account. The task prints an authorization URL; the user opens it in a browser, completes OAuth, and Scalekit stores the token.

src/main.ts

task(
  { name: "setupGitHubAuth" },
  async function setupGitHubAuth(userId: string) {
    const link = await getGitHubAuthLink(userId);
    console.log(`[setupGitHubAuth] Auth link: ${link}`);
    return {
      userId,
      authLink: link,
      instructions: "Open the authLink in your browser to connect your GitHub account. Once authorized, run summarizePRs.",
    };
  },
);

7. Run locally

Terminal 1 — start the workflow server

Terminal

render workflows dev -- npm run dev
# or with pnpm:
render workflows dev -- pnpm dev

Terminal 2 — connect GitHub (once per user)

Terminal

render workflows tasks start setupGitHubAuth --local --input='["your-user-id"]'

Open the printed authLink in your browser and authorize GitHub access. Scalekit stores the token — this step is not needed again.

Terminal 2 — run the summarizer

Terminal

render workflows tasks start summarizePRs \
  --local \
  --input='[{"userId":"your-user-id","owner":"octocat","repo":"Hello-World"}]'

8. Deploy and trigger on Render

Sign up on Render if you haven’t already
Push this repo to GitHub (or GitLab / Bitbucket)
In the Render Dashboard, click New → Workflow
Connect your repo
Set Build command: npm install && npm run build
Set Start command: node dist/main.js
Add the environment variables from Step 3
Deploy — summarizePRs and setupGitHubAuth will appear in the Render Dashboard under Tasks

Once deployed, trigger via CLI using the full workflow-slug/task-name format:

Terminal

render workflows tasks start <your-workflow-slug>/summarizePRs \
  --input='[{"userId":"alice","owner":"octocat","repo":"Hello-World"}]'

You can also trigger tasks from the Render Dashboard → your workflow service → Tasks.

9. Sample output

Output

{
  "repository": "octocat/Hello-World",
  "prsAnalyzed": [
    "#42: Refactor authentication middleware",
    "#38: Add rate limiting to public endpoints",
    "#35: Update dependencies",
    "#31: Fix memory leak in background worker",
    "#28: Improve error messages"
  ],
  "summary": "**PR #42 — Refactor authentication middleware**\nThis change restructures how the app handles user login and session management. It has generated significant discussion with 14 review comments, suggesting the team has been actively working through the design. The back-and-forth looks mostly resolved, so this one appears close to ready.\n\n**PR #38 — Add rate limiting to public endpoints**\nThis pull request introduces guardrails to prevent API abuse on the public-facing routes. There are 9 comments, mostly around configuration choices for the limits. It still seems to have a few open questions that need resolution before merging."
}

Common mistakes

Wrong connection name in executeTool

Symptom: [not_found] connection not found for the given key
Cause: The connector field in executeTool is set to the generic provider type (e.g. "github") instead of the actual connection name from the Scalekit Dashboard
Fix: Set connector to the full connection name (e.g. github-qkHFhMip). Store it in GITHUB_CONNECTION_NAME and reference that variable everywhere.

Bare object input instead of array

Symptom: Spread syntax requires ...iterable[Symbol.iterator] to be a function
Cause: Render’s SDK spreads the --input value as positional arguments. A bare JSON object ({...}) is not iterable.
Fix: Always wrap the input in an array: --input='[{"userId":"..."}]'

github_pull_requests_list returns unexpected shape

Symptom: Unexpected PR list response shape error, or null for the PR list
Cause: Scalekit wraps array tool responses in an { array: [...] } envelope, not a plain array
Fix: Check all shapes before throwing — raw.array, raw.pull_requests, raw.data, and plain Array.isArray(raw)

Auth link appears expired immediately

Symptom: The link from setupGitHubAuth says it’s already expired when opened
Cause: Clock drift between the Scalekit dev environment and the local machine can make newly generated links appear expired
Fix: Use the getOrCreateConnectedAccount + getAuthorizationLink SDK methods (as shown in scalekit.ts) rather than the Scalekit Dashboard’s magic link generator

Production notes

User ID from session — Replace the hardcoded userId with the real identifier from your application’s session or auth system. Each user’s GitHub token is stored under this key; a mismatch means the wrong token is used.

Private repos — fetchPRDetails uses unauthenticated fetch calls against the public GitHub API. For private repos, retrieve the user’s OAuth token from Scalekit via scalekit.actions.getConnectedAccount and pass it as Authorization: Bearer <token> in the fetch headers.

Token freshness — Scalekit refreshes expired tokens automatically when getOrCreateConnectedAccount or getAuthorizationLink is called. You do not need to track expiry or call a refresh endpoint.

Wiring to a standup bot — Once deployed, summarizePRs is a standard HTTP-triggerable task. Wire it to a Slack slash command or cron job using the Render SDK:

import { WorkflowsClient } from "@renderinc/sdk";

const client = new WorkflowsClient({ apiKey: process.env.RENDER_API_KEY });

await client.startTask("<your-workflow-slug>/summarizePRs", {
  userId: "alice",
  owner: "octocat",
  repo: "Hello-World",
});

Next steps

Add more connectors — The same getOrCreateConnectedAccount + executeTool pattern works for any Scalekit-supported connector. See all supported agent connectors.
Private repo support — Retrieve the stored OAuth token from Scalekit and pass it in the Authorization header when fetching diffs and comments.
Stream the summary — Replace the single batch LLM call in generateSummary with a streaming response for a more interactive standup experience.
Review the agent auth quickstart — For a broader overview of the connected-accounts model and supported providers, see the agent auth quickstart.

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

This guide sets basePath: "/auth" in auth.ts — a custom override. The Auth.js v5 default is /api/auth. Register your redirect URI to match whatever basePath you configure 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. This guide sets basePath: "/auth" (a custom override, not the v5 default — the default remains /api/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

For Spring Security servlet resource servers, there are no properties to configure JWT discovery/JWKS HTTP timeouts. Use a custom JwtDecoder bean with RestOperations (for example, RestTemplate) and explicit timeout values:

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 gives you:

Full control over HTTP client configuration
Ability to add custom headers or interceptors
Environment-specific timeout tuning (development: 5000ms, production: 10000–15000ms)

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

M2M JWT verification with JWKS and OAuth scopes

Why JWKS and scopes belong in one place

JWKS and Scalekit keys

Verify an access token

Operational practices

OAuth scopes for machine clients

Why scopes matter

How scopes work in Scalekit M2M

Register scopes on the client

Validate scopes on your API

Related

Set up AgentKit with your coding agent

Before you start

Pick your coding agent

Verify the setup

Troubleshooting

Enforce seat limits with SCIM provisioning

SCIM does not enforce seat limits — your app must

Two webhook events carry the full user lifecycle

Track a user count per organization in your database

Block creation when the count reaches the limit

Decrement the count when a user is removed

Notify admins without spamming them

Summarize GitHub PRs with Render Workflows

1. Set up the Scalekit GitHub connector

2. Create the project

3. Configure credentials

4. Initialize the Scalekit client

5. Write the workflow tasks

6. Add the one-time auth setup task

7. Run locally

8. Deploy and trigger on Render

9. Sample output

Common mistakes

Production notes

Next steps

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

4. Configure `auth.ts`