DEV Community: Shola Jegede

How to Add Device Authorization Flow to Your App With Kinde

Shola Jegede — Thu, 16 Apr 2026 17:29:50 +0000

Most auth tutorials assume there is a browser. Here is what to do when there is not.

In this article, you will learn:

What the device authorization flow is and why it exists
When to use it over other OAuth flows
How to set up a Device and IoT application in Kinde
How to implement the full flow end to end in Node.js
How to poll for tokens correctly and handle every error state
How to validate the access token on your API

Let's dive in!

The Problem With Browser-Based Auth

Every standard OAuth flow assumes the same thing: the user is sitting in front of a browser, they can get redirected to a login page, and they can type their credentials into a form.

That assumption breaks the moment you step outside the browser. A CLI tool cannot open a redirect. A smart TV has no way to display a full login form usably. A Raspberry Pi running a background process has no UI at all. An AI agent executing tasks on behalf of a user has no session to attach to.

For all of these cases, the OAuth 2.0 Device Authorization Grant (defined in RFC 8628) is the right answer. Instead of redirecting the device to a login page, the device asks the authorization server for a short user code and a URL, displays them to the user, and then polls for a token while the user completes login on a separate device — their phone or laptop — that actually has a browser.

The device never handles credentials. The user authenticates on a device they trust. The token lands on the original device once the user approves.

This flow is why logging into Netflix on a smart TV works the way it does. It is also how tools like the GitHub CLI, the Vercel CLI, and the AWS CLI authenticate their users without opening a browser window programmatically.

When to Use the Device Flow

The device flow is not a general-purpose replacement for the authorization code flow. Use it specifically when:

Your application runs in a terminal or CLI and cannot reliably open a browser
Your application runs on a device with limited or no input capabilities (smart TVs, set-top boxes, IoT hardware)
You are building an AI agent or automation that needs to authenticate on behalf of a human user but runs in a headless environment
You are building a desktop background process or daemon that needs user-level tokens without a UI

For standard web apps, mobile apps, or SPAs where a browser is available, stick with the authorization code flow with PKCE. The device flow adds polling complexity that you do not need when a redirect is possible.

Prerequisites

Before writing any code, make sure you have:

A Kinde account — free to sign up, no credit card required
Node.js 18 or later installed locally
A basic understanding of OAuth 2.0 token concepts

Step #1: Create a Device and IoT Application in Kinde

The device authorization flow requires a specific application type in Kinde. You cannot use an existing web or SPA application for this — the application type determines which OAuth grants are allowed.

In your Kinde dashboard, navigate to Applications and select Add application. Give it a descriptive name like My CLI Tool or Device App. Under application type, select Device and IoT. Select Save.

Once created, open the application details and note the Client ID. You will need this in every request. Device and IoT applications in Kinde do not have a client secret — the flow is designed for public clients that cannot securely store secrets.

Next, configure the authentication method for this application. Navigate to Settings > Authentication, select Configure on the Passwordless > Email + code card, and under Applications select the Device and IoT application you just created. Select Save.

This tells Kinde to use email OTP as the authentication method when a user goes to the verification URL from this application. Users will receive a one-time code by email rather than needing a password.

Step #2: Understand the Full Flow

Before writing code, it helps to see the complete sequence clearly.

Phase 1 — Device requests authorization:
Your device (the CLI, the TV, the background process) sends a POST request to Kinde's device authorization endpoint. Kinde responds with a device_code, a user_code, a verification_uri, and a verification_uri_complete.

Phase 2 — User authenticates:
Your device displays the user_code and the verification_uri to the user. The user visits the URL on their phone or laptop, enters the code, and authenticates through Kinde's normal login flow.

Phase 3 — Device polls for token:
While the user is authenticating, your device polls Kinde's token endpoint every few seconds using the device_code. Kinde returns authorization_pending until the user completes login, at which point it returns the access token.

Phase 4 — Device uses the token:
Your device now has a standard OAuth 2.0 Bearer token. It uses this to call your API.

The device_code is what your device uses internally. The user_code is what the human types. The verification_uri_complete is the full URL with the code pre-filled — useful for generating a QR code so the user does not have to type anything.

Step #3: Request the Device Code

Here is the first API call your device makes:

// src/auth.ts
import https from "https";
import { URLSearchParams } from "url";

const KINDE_DOMAIN = "YOUR_SUBDOMAIN.kinde.com";
const CLIENT_ID = "YOUR_CLIENT_ID";

interface DeviceCodeResponse {
  device_code: string;
  user_code: string;
  verification_uri: string;
  verification_uri_complete: string;
  expires_in: number;   // how long the codes are valid (seconds)
  interval: number;     // minimum polling interval (seconds)
}

async function requestDeviceCode(): Promise<DeviceCodeResponse> {
  const params = new URLSearchParams({
    client_id: CLIENT_ID,
    scope: "openid profile email offline",
  });

  const response = await fetch(
    `https://${KINDE_DOMAIN}/oauth2/device/auth`,
    {
      method: "POST",
      headers: {
        "Content-Type": "application/x-www-form-urlencoded",
      },
      body: params.toString(),
    }
  );

  if (!response.ok) {
    const error = await response.text();
    throw new Error(`Device code request failed: ${error}`);
  }

  return response.json() as Promise<DeviceCodeResponse>;
}

The scope values follow the standard OIDC conventions: openid requests an ID token, profile and email include the user's name and email in the token claims, and offline requests a refresh token so you can obtain new access tokens without requiring the user to re-authenticate.

The response from Kinde looks like this:

{
  "device_code": "kinde_dc_...",
  "user_code": "CSLDFDUU",
  "verification_uri": "https://your-subdomain.kinde.com/device",
  "verification_uri_complete": "https://your-subdomain.kinde.com/device?user_code=CSLDFDUU",
  "expires_in": 600,
  "interval": 5,
  "qr_code": "data:image/png;base64,..."
}

The user_code in Kinde is formatted as 8 uppercase characters for easy manual entry. The expires_in is 600 seconds (10 minutes) — that is how long the user has to complete the login before the codes expire. The qr_code field is a base64-encoded PNG image that you can render directly on screen, which means users with a camera can scan it instead of typing the URL and code manually.

Step #4: Display the Code to the User

Once you have the device code response, show the user what they need to do. For a CLI tool this is straightforward:

// src/cli.ts
async function startAuth() {
  console.log("\nRequesting authorization...\n");

  const deviceCodeData = await requestDeviceCode();

  console.log("To authenticate, visit:");
  console.log(`\n  ${deviceCodeData.verification_uri}\n`);
  console.log(`Enter this code: ${deviceCodeData.user_code}`);
  console.log(`\nOr open this URL directly (code pre-filled):`);
  console.log(`\n  ${deviceCodeData.verification_uri_complete}\n`);
  console.log(`Or scan the QR code if your device can display images.\n`);
  console.log(
    `Waiting for you to authenticate... (expires in ${Math.floor(deviceCodeData.expires_in / 60)} minutes)\n`
  );

  // Begin polling
  const token = await pollForToken(deviceCodeData);
  return token;
}

For a smart TV or embedded device, you would render the user_code prominently on screen alongside the verification_uri, or generate a QR code from verification_uri_complete so the user can scan it with their phone without typing anything.

Step #5: Poll for the Token

This is where most implementations go wrong. Polling is not just "keep hitting the token endpoint until it works." There are specific error states you must handle correctly.

// src/auth.ts

interface TokenResponse {
  access_token: string;
  id_token?: string;
  refresh_token?: string;
  expires_in: number;
  token_type: string;
}

type PollError =
  | "authorization_pending"  // user has not finished yet — keep polling
  | "slow_down"              // polling too fast — increase interval by 5 seconds
  | "access_denied"          // user explicitly denied — stop polling
  | "expired_token";         // codes have expired — restart the flow

async function pollForToken(
  deviceCodeData: DeviceCodeResponse
): Promise<TokenResponse> {
  let interval = deviceCodeData.interval; // start at 5 seconds
  const expiresAt = Date.now() + deviceCodeData.expires_in * 1000;

  while (Date.now() < expiresAt) {
    // Wait the current interval before polling
    await sleep(interval * 1000);

    const params = new URLSearchParams({
      grant_type: "urn:ietf:params:oauth:grant-type:device_code",
      client_id: CLIENT_ID,
      device_code: deviceCodeData.device_code,
    });

    const response = await fetch(`https://${KINDE_DOMAIN}/oauth2/token`, {
      method: "POST",
      headers: {
        "Content-Type": "application/x-www-form-urlencoded",
      },
      body: params.toString(),
    });

    if (response.ok) {
      // User authenticated — we have a token
      return response.json() as Promise<TokenResponse>;
    }

    const error = await response.json() as { error: PollError; error_description?: string };

    switch (error.error) {
      case "authorization_pending":
        // Normal state — user has not finished yet, keep waiting
        continue;

      case "slow_down":
        // We are polling too fast — increase interval by 5 seconds
        interval += 5;
        console.log(`Slowing down polling to every ${interval} seconds...`);
        continue;

      case "access_denied":
        // User explicitly denied the authorization
        throw new Error("Authorization was denied by the user.");

      case "expired_token":
        // The device code has expired — need to restart
        throw new Error(
          "The authorization code expired. Please run the command again."
        );

      default:
        throw new Error(
          `Unexpected error during polling: ${error.error} — ${error.error_description}`
        );
    }
  }

  throw new Error(
    "Authentication timed out. Please run the command again."
  );
}

function sleep(ms: number): Promise<void> {
  return new Promise((resolve) => setTimeout(resolve, ms));
}

A few things to pay attention to here:

Always wait before the first poll. The interval from the response is the minimum time between requests. Make the first poll after waiting that interval, not immediately after displaying the code to the user.

Handle slow_down correctly. When Kinde returns slow_down, you must increase your polling interval by 5 seconds for that request and all subsequent requests. Ignoring this and continuing at the original interval will result in your requests being rejected.

Respect expires_in. Stop polling when the device code expires. Do not continue indefinitely. If the code expires, the user needs to restart the process.

Distinguish authorization_pending from errors. authorization_pending is not an error — it just means the user has not finished yet. Everything else in the error response is a real problem that requires action.

Step #6: Store and Use the Token

Once polling succeeds, you have a standard OAuth 2.0 Bearer token. Store it securely and use it to authenticate API requests.

// src/token-store.ts
import fs from "fs";
import os from "os";
import path from "path";

const TOKEN_PATH = path.join(os.homedir(), ".myapp", "token.json");

interface StoredToken {
  access_token: string;
  refresh_token?: string;
  expires_at: number; // Unix timestamp in ms
}

export function saveToken(tokenResponse: TokenResponse): void {
  const dir = path.dirname(TOKEN_PATH);
  if (!fs.existsSync(dir)) {
    fs.mkdirSync(dir, { recursive: true });
  }

  const stored: StoredToken = {
    access_token: tokenResponse.access_token,
    refresh_token: tokenResponse.refresh_token,
    expires_at: Date.now() + tokenResponse.expires_in * 1000,
  };

  fs.writeFileSync(TOKEN_PATH, JSON.stringify(stored, null, 2), {
    mode: 0o600, // owner read/write only
  });
}

export function loadToken(): StoredToken | null {
  if (!fs.existsSync(TOKEN_PATH)) return null;

  try {
    return JSON.parse(fs.readFileSync(TOKEN_PATH, "utf-8")) as StoredToken;
  } catch {
    return null;
  }
}

export function isTokenExpired(token: StoredToken): boolean {
  // Add a 60-second buffer to account for clock skew
  return Date.now() >= token.expires_at - 60_000;
}

The file permissions on the token file (0o600) are important. This ensures only the current user can read the stored token, which matters when your tool runs on a shared machine.

To call your API with the token:

// src/api.ts
import { loadToken, isTokenExpired } from "./token-store";

async function callApi(endpoint: string): Promise<unknown> {
  const stored = loadToken();

  if (!stored || isTokenExpired(stored)) {
    throw new Error(
      "Not authenticated or session expired. Run `myapp login` to authenticate."
    );
  }

  const response = await fetch(`https://api.yourapp.com${endpoint}`, {
    headers: {
      Authorization: `Bearer ${stored.access_token}`,
      "Content-Type": "application/json",
    },
  });

  if (response.status === 401) {
    throw new Error(
      "Authentication failed. Run `myapp login` to re-authenticate."
    );
  }

  return response.json();
}

Step #7: Validate the Token on Your API

The device receives a standard JWT access token issued by Kinde. Your API validates it the same way it validates tokens from any other Kinde flow — by checking the signature against Kinde's public JWKS endpoint.

// api-server/middleware/auth.ts
import jwt from "jsonwebtoken";
import jwksClient from "jwks-rsa";

const KINDE_DOMAIN = "YOUR_SUBDOMAIN.kinde.com";

const client = jwksClient({
  jwksUri: `https://${KINDE_DOMAIN}/.well-known/jwks.json`,
  cache: true,
  cacheMaxAge: 600_000, // cache keys for 10 minutes
});

function getSigningKey(
  header: jwt.JwtHeader,
  callback: jwt.SigningKeyCallback
) {
  client.getSigningKey(header.kid!, (err, key) => {
    if (err) return callback(err);
    callback(null, key!.getPublicKey());
  });
}

export function verifyToken(
  req: Request,
  res: Response,
  next: NextFunction
) {
  const authHeader = req.headers["authorization"];
  const token = authHeader?.split(" ")[1];

  if (!token) {
    return res.status(401).json({ error: "No token provided" });
  }

  jwt.verify(
    token,
    getSigningKey,
    {
      algorithms: ["RS256"],
      issuer: `https://${KINDE_DOMAIN}`,
    },
    (err, decoded) => {
      if (err) {
        return res.status(403).json({ error: "Invalid token" });
      }

      // Attach the decoded claims to the request for use in route handlers
      (req as any).user = decoded;
      next();
    }
  );
}

The token issued via device flow contains the same claims as any other Kinde access token: sub (the user's Kinde ID), email, name, org_code if the user is in an organization, and any roles and permissions you have configured. Your API does not need to know or care that the token came from a device flow — the validation is identical.

Putting It All Together

Here is a complete CLI entry point that wires up everything above:

// src/index.ts
import { startAuth } from "./auth";
import { saveToken, loadToken, isTokenExpired } from "./token-store";
import { callApi } from "./api";

async function main() {
  const command = process.argv[2];

  if (command === "login") {
    console.log("Starting authentication...");
    const token = await startAuth();
    saveToken(token);
    console.log("\nAuthenticated successfully. You can now use the CLI.\n");
    return;
  }

  if (command === "whoami") {
    const stored = loadToken();

    if (!stored || isTokenExpired(stored)) {
      console.error("Not authenticated. Run `myapp login` first.");
      process.exit(1);
    }

    const user = await callApi("/me");
    console.log(user);
    return;
  }

  if (command === "logout") {
    const tokenPath = path.join(os.homedir(), ".myapp", "token.json");
    if (fs.existsSync(tokenPath)) {
      fs.unlinkSync(tokenPath);
      console.log("Logged out successfully.");
    } else {
      console.log("No active session found.");
    }
    return;
  }

  console.log("Usage: myapp <login|whoami|logout>");
}

main().catch((err) => {
  console.error(err.message);
  process.exit(1);
});

Running myapp login kicks off the device flow, shows the user a code and URL, polls until they authenticate, and saves the token locally. Every subsequent command loads the token silently from disk and uses it without interrupting the user.

Common Mistakes to Avoid

Polling immediately after displaying the code. Always wait the interval before the first poll. Hitting the token endpoint immediately wastes a request and may trigger rate limiting.

Not handling slow_down. If you receive a slow_down error and keep polling at the same rate, your requests will continue to fail. Increase the interval by 5 seconds and keep increasing it if you receive the error again.

Restarting the whole flow when authorization_pending is returned. authorization_pending means keep waiting, not start over. Only restart the flow if you receive expired_token or if the expires_in window has elapsed.

Storing the token with world-readable permissions. A token file stored at ~/.myapp/token.json with permissions 0o644 can be read by other users on the same machine. Always write token files with 0o600.

Not handling token expiry. Access tokens from Kinde expire after one hour by default. Check the expiry before every API call and prompt the user to re-authenticate if the token is expired. If you requested a refresh token (by including offline in your scopes), you can use it to get a new access token silently.

What This Enables

With device authorization flow in place, your CLI, IoT device, or headless process can authenticate real users through Kinde's full auth stack — including MFA, SSO, and org-scoped tokens — without any of that logic living in your device code. The user authenticates on a device they trust, your device gets a token, and your API validates it the same way it validates every other token.

For AI agents and automation workflows that need to act on behalf of authenticated users, this flow is the right foundation. The agent does not handle credentials. The user authorizes it explicitly. The token carries the same org and permission claims as any browser-based session.

Kinde handles the auth infrastructure — the user code generation, the verification page, the token issuance, the JWKS endpoint — so the only code you write is the polling loop and the token storage. Sign up for free and have your first device flow working in under an hour.

How to Audit Who Did What in Your Multi-Tenant App: Building an Activity Log With Convex and Kinde

Shola Jegede — Thu, 16 Apr 2026 11:48:28 +0000

Enterprise customers will not sign on the dotted line until they can answer: "Who did what, and when?" Here is how to build the activity log that closes that gap.

In this article, you will learn:

Why audit logs are no longer optional for multi-tenant SaaS — and what it costs you when they are missing
How to design an activityLogs schema in Convex that handles high-volume writes without slowing down your queries
Why you should denormalize actor fields at write time and what happens when you do not
How to build a single auditLog helper that every mutation calls — and why it being transactional is the whole point
How to pull actor identity from Kinde's server session and attach it to every log entry
How to build a filterable, paginated, real-time activity feed that org members can view
How to export activity logs as CSV for compliance teams
How to guarantee that no organization ever sees another organization's activity

Let's dive in!

The Audit Log Gap That Costs You Enterprise Deals

There is a specific moment in enterprise procurement that catches most SaaS founders off guard. You have passed the security review. The procurement lead likes the product. Then someone from IT or legal asks: "If an admin deletes something or changes a permission, can we see who did it and when?"

If the answer is no, the deal stalls — sometimes indefinitely. Enterprise customers are not being bureaucratic. They have legal obligations around data access records, SOC 2 and ISO 27001 auditors who ask for evidence of access trails, and internal IT teams that need to investigate incidents when they happen. An audit log is not a backlog item. It is infrastructure that determines whether your app is deployable inside a governed organization.

The other problem is internal. When a team member emails asking why a document disappeared, or when a customer opens a support ticket claiming their settings were changed without their knowledge, you have nothing to show them without an activity log. You either stare at database timestamps trying to reconstruct what happened, or you tell them you cannot find out. Neither is acceptable once you have paying customers.

Building this correctly is not complicated if you do it at the right layer. This article builds a complete, production-ready activity log for a multi-tenant Next.js app using Convex and Kinde. The pattern it establishes — a single helper, called inside every mutation, committed in the same transaction as the action itself — means you will never have a mutation that fires without a corresponding log entry.

Why Convex Is the Right Database for Audit Logs

Audit logs have a write pattern that is unusual compared to most application data. Entries are inserted at high frequency, almost never updated, never deleted within your retention window, and queried in time-range windows filtered by organization, actor, or resource type.

Convex handles this well for three reasons.

Writes are transactional and co-located with your mutations. Because your mutation and your auditLog call live in the same Convex function and commit in the same transaction, you cannot have a state where a document was deleted but no log entry was written. Either both commit or neither does. This property is not free in architectures where you fire a side-effect call to a separate logging service after the mutation returns — a network failure between the two leaves your audit trail permanently inconsistent.

Compound indexes make time-range queries fast. Filtering by organizationId and then ordering by creation time is exactly the access pattern an activity feed needs. Convex's index system keeps that query fast as the table grows into hundreds of thousands of rows.

Reactive queries give you a live feed for free. A feed component that uses useQuery on your log query will update in real time whenever new entries are written — without polling, without manual WebSocket management, without any extra code. Convex tracks the query's data dependencies and pushes updates automatically.

Schema

Add the activityLogs table to your convex/schema.ts.

// convex/schema.ts
import { defineSchema, defineTable } from "convex/server";
import { v } from "convex/values";

export default defineSchema({
  // ... your existing tables

  activityLogs: defineTable({
    organizationId: v.id("organizations"),
    actorId: v.string(),           // Kinde user ID — e.g. "kp_123abc"
    actorEmail: v.string(),        // Denormalized for display — no join required
    actorName: v.string(),         // Same reason: accounts get deleted, names change
    action: v.string(),            // "document.created", "member.role_changed", etc.
    resourceType: v.string(),      // "document", "member", "role", "settings"
    resourceId: v.optional(v.string()),    // ID of the affected resource
    resourceLabel: v.optional(v.string()), // Human-readable name at the time of action
    metadata: v.optional(v.any()),         // Action-specific context: before/after diffs, etc.
    ipAddress: v.optional(v.string()),
  })
    .index("by_organization", ["organizationId"])
    .index("by_org_and_actor", ["organizationId", "actorId"])
    .index("by_org_and_resource_type", ["organizationId", "resourceType"]),
});

Several design decisions here are worth explaining before you move on.

Denormalize actor fields. actorEmail and actorName are stored directly on the log entry — not as foreign keys to a users table. This means you never need a join to render the activity feed, and the log permanently records who performed the action at the time it happened, not who the account belongs to now. User display names change. Accounts get suspended or deleted. People leave companies. The audit trail must be immutable after write, which means capturing the actor's identity at write time.

Use a string for actorId, not a Convex document ID. Kinde user IDs are strings (e.g. kp_abc123def). Storing the Kinde ID directly means no lookup layer and no dependency on your local users table — the ID remains valid and meaningful even if you migrate or restructure your user data.

Store resourceLabel. When a document is deleted, the document is gone. If you only stored the resource ID, the log entry for document.deleted would show a dead reference with no human-readable context. Capture the label at write time, before the deletion.

Three indexes, not one. The primary access pattern is all logs for an org ordered by time descending. The secondary patterns are filtering by actor ("show me everything Alice did this week") and filtering by resource type ("show me all role changes"). Three focused indexes handle all three without full table scans. Per Convex best practices, by_org_and_resource_type is compound — you always scope to an organization first, so a standalone by_resource_type index would be redundant.

metadata is typed loosely by design. A document.shared event needs to capture who it was shared with. A member.role_changed event needs the before and after role values. A settings.updated event needs the field that changed and its old and new values. Rather than adding a column for every possible shape, metadata holds the action-specific payload and you validate it at the call site.

The `auditLog` Helper

Create convex/lib/audit.ts. Every mutation in your app will call this one function. Centralizing it here means you change audit log behavior in exactly one place.

// convex/lib/audit.ts
import { MutationCtx } from "../_generated/server";
import { Id } from "../_generated/dataModel";

export type AuditAction =
  | "document.created"
  | "document.updated"
  | "document.deleted"
  | "document.shared"
  | "document.unshared"
  | "member.invited"
  | "member.removed"
  | "member.role_changed"
  | "invitation.accepted"
  | "invitation.revoked"
  | "role.created"
  | "role.updated"
  | "role.deleted"
  | "settings.updated"
  | "billing.plan_changed"
  | "org.created";

export type ResourceType =
  | "document"
  | "member"
  | "invitation"
  | "role"
  | "settings"
  | "billing"
  | "org";

interface AuditLogParams {
  ctx: MutationCtx;
  organizationId: Id<"organizations">;
  actorId: string;
  actorEmail: string;
  actorName: string;
  action: AuditAction;
  resourceType: ResourceType;
  resourceId?: string;
  resourceLabel?: string;
  metadata?: Record<string, unknown>;
  ipAddress?: string;
}

export async function auditLog({
  ctx,
  organizationId,
  actorId,
  actorEmail,
  actorName,
  action,
  resourceType,
  resourceId,
  resourceLabel,
  metadata,
  ipAddress,
}: AuditLogParams): Promise<void> {
  await ctx.db.insert("activityLogs", {
    organizationId,
    actorId,
    actorEmail,
    actorName,
    action,
    resourceType,
    resourceId,
    resourceLabel,
    metadata,
    ipAddress,
  });
}

The function signature is explicit by design. AuditAction and ResourceType are union types — TypeScript enforces them at compile time, so a typo like "document.creatd" fails the build rather than silently writing a malformed entry into your audit trail. The function does exactly one thing: insert. Any filtering, validation, or transformation happens at the call site inside the mutation that needs it.

Pulling Actor Identity From Kinde

Before looking at how mutations call auditLog, you need a reliable way to get the current user's Kinde ID, email, and display name inside a Convex mutation.

The standard pattern is a getCurrentUser helper that queries your local users table using the Kinde user ID embedded in the Convex auth token. Your users table gets populated during the post-login callback — either via a Convex mutation called from the Next.js auth handler, or by checking on first load.

// convex/lib/auth.ts
import { QueryCtx, MutationCtx } from "../_generated/server";

export async function getCurrentUser(ctx: QueryCtx | MutationCtx) {
  // ctx.auth.getUserIdentity() reads the JWT Kinde issues after login.
  // The `subject` claim is the Kinde user ID (e.g. "kp_abc123def").
  const identity = await ctx.auth.getUserIdentity();
  if (!identity) return null;

  const kindeId = identity.subject;

  const user = await ctx.db
    .query("users")
    .withIndex("by_kinde_id", (q) => q.eq("kindeId", kindeId))
    .unique();

  return user;
}

Your users table needs kindeId, email, and name fields. When a user first authenticates through Kinde, those three values are written to the table from the token claims. The auditLog helper reads them and writes them directly onto the log entry — no live lookup, no join, immutable from that point forward.

Kinde's @kinde-oss/kinde-auth-nextjs SDK handles token issuance on the Next.js side. Convex picks up the token automatically when you configure it to use Kinde as the auth provider via the Convex dashboard's authentication settings.

Step #1: Call `auditLog` Inside Your Mutations

The pattern is identical across every mutation: do the database write, then call auditLog before returning. Because Convex mutations are transactional, the primary write and the log entry commit together or not at all.

Document creation

// convex/documents.ts
import { mutation } from "./_generated/server";
import { v } from "convex/values";
import { getCurrentUser, requirePermission } from "./lib/auth";
import { auditLog } from "./lib/audit";

export const create = mutation({
  args: {
    organizationId: v.id("organizations"),
    title: v.string(),
    content: v.optional(v.string()),
  },
  handler: async (ctx, args) => {
    const { user } = await requirePermission(ctx, args.organizationId, "documents:create");

    const documentId = await ctx.db.insert("documents", {
      organizationId: args.organizationId,
      title: args.title,
      content: args.content ?? "",
      createdBy: user._id,
      createdAt: Date.now(),
      updatedAt: Date.now(),
    });

    await auditLog({
      ctx,
      organizationId: args.organizationId,
      actorId: user.kindeId,
      actorEmail: user.email,
      actorName: user.name,
      action: "document.created",
      resourceType: "document",
      resourceId: documentId,
      resourceLabel: args.title,
    });

    return documentId;
  },
});

Document deletion

Read the title before the delete. Once ctx.db.delete runs, that document is gone. If you try to fetch the title after, you get nothing.

export const remove = mutation({
  args: {
    organizationId: v.id("organizations"),
    documentId: v.id("documents"),
  },
  handler: async (ctx, args) => {
    const { user } = await requirePermission(ctx, args.organizationId, "documents:delete");

    const document = await ctx.db.get(args.documentId);
    if (!document) throw new Error("Document not found");
    if (document.organizationId !== args.organizationId) throw new Error("Document not found");

    // Capture the label BEFORE the delete — after, it no longer exists
    const documentTitle = document.title;

    await ctx.db.delete(args.documentId);

    await auditLog({
      ctx,
      organizationId: args.organizationId,
      actorId: user.kindeId,
      actorEmail: user.email,
      actorName: user.name,
      action: "document.deleted",
      resourceType: "document",
      resourceId: args.documentId,
      resourceLabel: documentTitle,
    });
  },
});

Member role change

This one captures a before/after diff in metadata. When someone reviews the log later, they see exactly what changed without querying another table.

// convex/organizations.ts
export const updateMemberRole = mutation({
  args: {
    organizationId: v.id("organizations"),
    membershipId: v.id("organizationMembers"),
    newRole: v.string(),
  },
  handler: async (ctx, args) => {
    const { user } = await requirePermission(ctx, args.organizationId, "members:manage");

    const membership = await ctx.db.get(args.membershipId);
    if (!membership) throw new Error("Member not found");
    if (membership.organizationId !== args.organizationId) throw new Error("Member not found");

    // Read the previous role before patching
    const previousRole = membership.role;

    await ctx.db.patch(args.membershipId, {
      role: args.newRole,
    });

    // Fetch the affected user's display info for the log label
    const affectedUser = await ctx.db.get(membership.userId);

    await auditLog({
      ctx,
      organizationId: args.organizationId,
      actorId: user.kindeId,
      actorEmail: user.email,
      actorName: user.name,
      action: "member.role_changed",
      resourceType: "member",
      resourceId: membership.userId,
      resourceLabel: affectedUser?.name ?? affectedUser?.email ?? "Unknown user",
      metadata: {
        previousRole,
        newRole: args.newRole,
      },
    });
  },
});

Settings update

// convex/settings.ts
export const update = mutation({
  args: {
    organizationId: v.id("organizations"),
    field: v.string(),
    value: v.any(),
  },
  handler: async (ctx, args) => {
    const { user } = await requirePermission(ctx, args.organizationId, "settings:manage");

    const settings = await ctx.db
      .query("organizationSettings")
      .withIndex("by_organization", (q) =>
        q.eq("organizationId", args.organizationId)
      )
      .unique();

    if (!settings) throw new Error("Settings not found");

    const previousValue = (settings as any)[args.field];

    await ctx.db.patch(settings._id, {
      [args.field]: args.value,
      updatedAt: Date.now(),
    });

    await auditLog({
      ctx,
      organizationId: args.organizationId,
      actorId: user.kindeId,
      actorEmail: user.email,
      actorName: user.name,
      action: "settings.updated",
      resourceType: "settings",
      resourceLabel: args.field,
      metadata: {
        field: args.field,
        previousValue,
        newValue: args.value,
      },
    });
  },
});

The metadata pattern is consistent across all mutations: capture what changed, what it was before, what it is now. The log entry is self-contained — a compliance auditor reading it does not need to cross-reference other tables or reconstruct state from timestamps.

Step #2: Query the Activity Log

Create the query functions in convex/activityLogs.ts. These are what the frontend subscribes to.

// convex/activityLogs.ts
import { query } from "./_generated/server";
import { v } from "convex/values";
import { requireOrganizationAccess } from "./lib/auth";

// All activity for an org, paginated, most recent first
export const list = query({
  args: {
    organizationId: v.id("organizations"),
    paginationOpts: v.object({
      numItems: v.number(),
      cursor: v.union(v.string(), v.null()),
    }),
  },
  handler: async (ctx, { organizationId, paginationOpts }) => {
    await requireOrganizationAccess(ctx, organizationId);

    return ctx.db
      .query("activityLogs")
      .withIndex("by_organization", (q) =>
        q.eq("organizationId", organizationId)
      )
      .order("desc")
      .paginate(paginationOpts);
  },
});

// Filtered by actor — "show me everything Alice did"
export const listByActor = query({
  args: {
    organizationId: v.id("organizations"),
    actorId: v.string(),
    paginationOpts: v.object({
      numItems: v.number(),
      cursor: v.union(v.string(), v.null()),
    }),
  },
  handler: async (ctx, { organizationId, actorId, paginationOpts }) => {
    await requireOrganizationAccess(ctx, organizationId);

    return ctx.db
      .query("activityLogs")
      .withIndex("by_org_and_actor", (q) =>
        q.eq("organizationId", organizationId).eq("actorId", actorId)
      )
      .order("desc")
      .paginate(paginationOpts);
  },
});

// Filtered by resource type — "show me all role changes"
export const listByResourceType = query({
  args: {
    organizationId: v.id("organizations"),
    resourceType: v.string(),
    paginationOpts: v.object({
      numItems: v.number(),
      cursor: v.union(v.string(), v.null()),
    }),
  },
  handler: async (ctx, { organizationId, resourceType, paginationOpts }) => {
    await requireOrganizationAccess(ctx, organizationId);

    return ctx.db
      .query("activityLogs")
      .withIndex("by_org_and_resource_type", (q) =>
        q.eq("organizationId", organizationId).eq("resourceType", resourceType)
      )
      .order("desc")
      .paginate(paginationOpts);
  },
});

// Used by the CSV export endpoint — fetches all entries within a time window
export const listAllForExport = query({
  args: {
    organizationId: v.id("organizations"),
    since: v.optional(v.number()), // Unix timestamp in ms
  },
  handler: async (ctx, { organizationId, since }) => {
    await requireOrganizationAccess(ctx, organizationId);

    const results = await ctx.db
      .query("activityLogs")
      .withIndex("by_organization", (q) =>
        q.eq("organizationId", organizationId)
      )
      .order("desc")
      .collect();

    if (since) {
      return results.filter((entry) => entry._creationTime >= since);
    }

    return results;
  },
});

Every query starts with requireOrganizationAccess. This is not optional. Audit log data is sensitive — the fact that it is read-only does not make it public. A user with access to Org A must not be able to call activityLogs.list with Org B's ID and receive results. The access check runs before any data is read.

Step #3: Build the Activity Feed UI

Add the page at /org/[slug]/activity. It shows all activity with filter pills for resource type, loads more entries on scroll, and updates in real time as new entries arrive.

// app/org/[slug]/activity/page.tsx
"use client";

import { usePaginatedQuery, useQuery } from "convex/react";
import { api } from "@/convex/_generated/api";
import { useState } from "react";
import { formatDistanceToNow } from "date-fns";

const ACTION_LABELS: Record<string, string> = {
  "document.created": "created a document",
  "document.updated": "updated a document",
  "document.deleted": "deleted a document",
  "document.shared": "shared a document",
  "document.unshared": "unshared a document",
  "member.invited": "invited a member",
  "member.removed": "removed a member",
  "member.role_changed": "changed a member's role",
  "invitation.accepted": "accepted an invitation",
  "invitation.revoked": "revoked an invitation",
  "role.created": "created a role",
  "role.updated": "updated a role",
  "role.deleted": "deleted a role",
  "settings.updated": "updated settings",
  "billing.plan_changed": "changed the billing plan",
  "org.created": "created the organization",
};

const RESOURCE_TYPE_FILTERS = [
  { value: "", label: "All activity" },
  { value: "document", label: "Documents" },
  { value: "member", label: "Members" },
  { value: "role", label: "Roles" },
  { value: "settings", label: "Settings" },
  { value: "billing", label: "Billing" },
];

export default function ActivityPage({ params }: { params: { slug: string } }) {
  const org = useQuery(api.organizations.getBySlug, { slug: params.slug });
  const [resourceTypeFilter, setResourceTypeFilter] = useState("");

  const { results, status, loadMore } = usePaginatedQuery(
    resourceTypeFilter
      ? api.activityLogs.listByResourceType
      : api.activityLogs.list,
    org
      ? resourceTypeFilter
        ? { organizationId: org._id, resourceType: resourceTypeFilter }
        : { organizationId: org._id }
      : "skip",
    { initialNumItems: 25 }
  );

  if (!org) {
    return <div className="p-8 text-sm text-gray-500">Loading...</div>;
  }

  return (
    <div className="max-w-2xl mx-auto py-8 space-y-6">
      <div className="flex items-center justify-between">
        <div>
          <h1 className="text-xl font-semibold">Activity</h1>
          <p className="text-sm text-gray-500 mt-0.5">
            A record of every action taken in this organization.
          </p>
        </div>
        <a
          href={`/api/activity/export?orgId=${org._id}`}
          className="text-sm text-gray-500 hover:text-gray-900 underline underline-offset-2"
        >
          Export CSV
        </a>
      </div>

      {/* Filter pills */}
      <div className="flex gap-2 flex-wrap">
        {RESOURCE_TYPE_FILTERS.map((filter) => (
          <button
            key={filter.value}
            onClick={() => setResourceTypeFilter(filter.value)}
            className={`px-3 py-1.5 rounded-full text-xs font-medium transition-colors ${
              resourceTypeFilter === filter.value
                ? "bg-black text-white"
                : "bg-gray-100 text-gray-600 hover:bg-gray-200"
            }`}
          >
            {filter.label}
          </button>
        ))}
      </div>

      {/* Log entries */}
      <div className="space-y-1">
        {results.length === 0 && status === "Exhausted" ? (
          <p className="text-sm text-gray-400 py-8 text-center">No activity yet.</p>
        ) : (
          results.map((entry) => (
            <div
              key={entry._id}
              className="flex items-start gap-3 py-3 border-b border-gray-100 last:border-0"
            >
              {/* Actor avatar */}
              <div className="w-7 h-7 rounded-full bg-gray-200 flex items-center justify-center flex-shrink-0 mt-0.5">
                <span className="text-xs font-medium text-gray-600">
                  {entry.actorName?.[0]?.toUpperCase() ?? "?"}
                </span>
              </div>

              <div className="flex-1 min-w-0">
                <p className="text-sm text-gray-900">
                  <span className="font-medium">{entry.actorName}</span>
                  {" "}
                  <span className="text-gray-600">
                    {ACTION_LABELS[entry.action] ?? entry.action}
                  </span>
                  {entry.resourceLabel && (
                    <>
                      {": "}
                      <span className="font-medium text-gray-900">
                        {entry.resourceLabel}
                      </span>
                    </>
                  )}
                </p>

                {/* Show before/after for role changes */}
                {entry.action === "member.role_changed" && entry.metadata && (
                  <p className="text-xs text-gray-400 mt-0.5">
                    {(entry.metadata as any).previousRole} → {(entry.metadata as any).newRole}
                  </p>
                )}

                {/* Show which field changed for settings updates */}
                {entry.action === "settings.updated" && entry.metadata && (
                  <p className="text-xs text-gray-400 mt-0.5">
                    Field: {(entry.metadata as any).field}
                  </p>
                )}

                <p className="text-xs text-gray-400 mt-0.5">
                  {formatDistanceToNow(entry._creationTime, { addSuffix: true })}
                  {" · "}
                  {entry.actorEmail}
                </p>
              </div>
            </div>
          ))
        )}
      </div>

      {status === "CanLoadMore" && (
        <div className="flex justify-center pt-2">
          <button
            onClick={() => loadMore(25)}
            className="text-sm text-gray-500 hover:text-gray-900 underline underline-offset-2"
          >
            Load more
          </button>
        </div>
      )}

      {status === "LoadingMore" && (
        <p className="text-center text-sm text-gray-400">Loading...</p>
      )}
    </div>
  );
}

The feed is reactive. Convex tracks the query's data dependencies and pushes updates to the component whenever a new log entry is written. An org member watching the activity page will see new entries appear in real time — without a page refresh, without polling, without any extra setup.

Step #4: Export as CSV for Compliance

When a compliance team or auditor asks for the activity history, they want a file — not a browser tab. Add a Next.js API route that fetches all logs for an org and returns them as a downloadable CSV.

// app/api/activity/export/route.ts
import { NextRequest, NextResponse } from "next/server";
import { getKindeServerSession } from "@kinde-oss/kinde-auth-nextjs/server";
import { ConvexHttpClient } from "convex/browser";
import { api } from "@/convex/_generated/api";
import { Id } from "@/convex/_generated/dataModel";

const convex = new ConvexHttpClient(process.env.NEXT_PUBLIC_CONVEX_URL!);

export async function GET(req: NextRequest) {
  const { isAuthenticated } = getKindeServerSession();

  const authenticated = await isAuthenticated();
  if (!authenticated) {
    return new NextResponse("Unauthorized", { status: 401 });
  }

  const orgId = req.nextUrl.searchParams.get("orgId");
  if (!orgId) {
    return new NextResponse("Missing orgId", { status: 400 });
  }

  // Optional: limit to last 90 days with ?since=<timestamp>
  const since = req.nextUrl.searchParams.get("since");

  const logs = await convex.query(api.activityLogs.listAllForExport, {
    organizationId: orgId as Id<"organizations">,
    since: since ? Number(since) : undefined,
  });

  const csvRows = [
    ["Timestamp", "Actor Name", "Actor Email", "Action", "Resource Type", "Resource", "Details"].join(","),
    ...logs.map((entry) =>
      [
        new Date(entry._creationTime).toISOString(),
        `"${entry.actorName.replace(/"/g, '""')}"`,
        entry.actorEmail,
        entry.action,
        entry.resourceType,
        `"${(entry.resourceLabel ?? "").replace(/"/g, '""')}"`,
        `"${entry.metadata ? JSON.stringify(entry.metadata).replace(/"/g, '""') : ""}"`,
      ].join(",")
    ),
  ].join("\n");

  return new NextResponse(csvRows, {
    status: 200,
    headers: {
      "Content-Type": "text/csv",
      "Content-Disposition": `attachment; filename="activity-${orgId}-${Date.now()}.csv"`,
    },
  });
}

getKindeServerSession from @kinde-oss/kinde-auth-nextjs/server verifies the user is authenticated before any data is touched. The ConvexHttpClient is the correct way to call Convex from a Next.js API route or server action — outside of a React component, useQuery is not available, so you use the HTTP client directly.

You now have a complete audit log — write path, read path, real-time feed, and CSV export in one clean pipeline.

Step #5: Guarantee Org Isolation

Org isolation is not automatic. You enforce it explicitly at every query boundary with requireOrganizationAccess. Here is what that helper looks like and why the order of checks matters.

// convex/lib/auth.ts
import { QueryCtx, MutationCtx } from "../_generated/server";
import { Id } from "../_generated/dataModel";

export async function requireOrganizationAccess(
  ctx: QueryCtx | MutationCtx,
  organizationId: Id<"organizations">
) {
  const identity = await ctx.auth.getUserIdentity();
  if (!identity) throw new Error("Not authenticated");

  const user = await ctx.db
    .query("users")
    .withIndex("by_kinde_id", (q) => q.eq("kindeId", identity.subject))
    .unique();

  if (!user) throw new Error("User not found");

  const membership = await ctx.db
    .query("organizationMembers")
    .withIndex("by_org_and_user", (q) =>
      q.eq("organizationId", organizationId).eq("userId", user._id)
    )
    .unique();

  // No membership record = no access. This check runs before any log data is read.
  if (!membership) throw new Error("Access denied");

  return { user, membership };
}

When activityLogs.list is called with an organization ID, requireOrganizationAccess checks for a membership record in that specific org before the log query runs. A member of Org A cannot call the query with Org B's ID and receive results — the check throws before any database read happens.

The isolation guarantee has two layers. First, the membership check in the query handler. Second, the organizationId field on every log entry — each query is scoped to one org's index range. Even if the membership check somehow failed, a query hitting by_organization would only return entries for that specific org.

Testing the System

Do not skip this. An audit log that silently misses entries is worse than no audit log — it creates false confidence. These five tests verify the critical paths.

Test 1: Transactional commit

Call documents.remove with a valid document ID. After it succeeds, open the Convex dashboard and check the activityLogs table — a document.deleted entry should exist with the correct resourceLabel. Now temporarily patch the mutation to throw an error after ctx.db.delete but before auditLog. Call it again. Both the deletion and the log entry should roll back together. If the document gets deleted but no log entry appears, your auditLog call is outside the mutation handler — move it inside.

Test 2: Actor identity per session

Sign in as two different users and each create a document in the same organization. Check activityLogs — the two entries should have different actorId, actorEmail, and actorName values. If both entries show the same actor, getCurrentUser is reading from a stale or shared identity source.

Test 3: Org isolation under direct API call

From the Convex dashboard, call activityLogs.list with the ID of an organization the currently authenticated user does not belong to. You should receive:

Error: Access denied

If the query returns data, requireOrganizationAccess is either missing or not throwing correctly.

Test 4: Resource label captured before deletion

Create a document titled "Q2 Vendor Report". Delete it. Find the document.deleted entry in activityLogs. The resourceLabel field should read "Q2 Vendor Report". If it is null or undefined, the delete is happening before the title is read. Reverse the order.

Test 5: Metadata correctness on role changes

Change a member's role from member to admin. Find the member.role_changed log entry and expand metadata. It should contain { "previousRole": "member", "newRole": "admin" }. If previousRole is null, the membership record is being read after the patch — capture the previous role before calling ctx.db.patch.

Common Mistakes to Avoid

Capturing resource labels after the mutation. Read everything you need from the affected resource before modifying or deleting it. After ctx.db.delete, the document is gone. After ctx.db.patch, the original field values are overwritten in the current context. Read first, write second, log third.

Calling a side-effect logging service after the mutation returns. If you call an external logging service after the Convex mutation completes, the log entry and the action are not transactionally coupled. A network failure or a crash between the mutation completing and the side-effect firing gives you a permanent inconsistency in your audit trail. Keep auditLog inside the Convex mutation.

Skipping requireOrganizationAccess on log queries. Audit log data is sensitive. The fact that it is read-only does not make it safe to skip the access check. Every query that reads activityLogs needs the membership check, no exceptions.

Storing a Convex document ID instead of the Kinde user ID as actorId. Convex document IDs change if you migrate or restructure data. Kinde user IDs are stable identifiers issued by the identity provider. Use the Kinde ID.

Not filtering by organizationId on every log query. A query that reads from activityLogs without an organizationId constraint is a full table scan that will slow down as the table grows and expose cross-org data. Every query goes through an index that starts with organizationId.

What This Enables

An enterprise customer's IT team can answer "who accessed what and when" directly from the activity feed — no support ticket, no engineering involvement.

Your compliance team can export a CSV of all activity within any date range and hand it to an auditor without writing a single SQL query.

When a user claims their settings were changed without their knowledge, you check the log and show them exactly who made the change and when — in under a minute.

Enterprise deals that stalled on the audit log question now have a concrete answer: every action is logged at write time, every entry is scoped to one organization, the data is exportable on demand, and the log is tamper-evident by design.

What Is Next

Retention policies. Add a scheduled Convex function that runs nightly and deletes log entries older than your configured retention window. Store the retention duration on the organization record so you can offer longer retention as a paid feature for enterprise tiers.

Admin-only visibility. Right now any org member who can reach the activity route can view the feed. Add a audit:read permission check inside the query handler — the membership check is already there, it is a small addition — and gate the page to admins and owners only.

Webhook delivery. Enterprise customers with SIEM (security information and event management) tools will ask for activity data pushed to them in real time. Add a Convex action that fires a webhook to a customer-configured URL after each log entry is written. The payload is the log entry itself.

Full-text search. For orgs with high activity volume, time-range and resource-type filters are not always enough. Convex supports full-text search indexes. Adding one on action and resourceLabel lets you support queries like "show all activity mentioning 'Q2 Report'".

How to Use Feature Flags to Safely Roll Out Features in Production With Kinde

Shola Jegede — Tue, 14 Apr 2026 14:28:29 +0000

In this article, you will learn:

What feature flags are and why they matter for production releases
The four flag types Kinde supports and when to use each one
How Kinde delivers flag values through the auth token — no extra SDK required
How to create your first feature flag in the Kinde dashboard
How to read flags in a Next.js application using the Kinde SDK
How to override flags per environment, per organization, and per user
How to use flags for gradual AI feature rollouts
How to use string flags for A/B testing UI copy
How to use integer flags to control per-user AI token limits
How to use JSON flags for complex feature configurations
The flag lifecycle: creation, rollout, cleanup

Let's dive in!

Why Feature Flags Exist

Every developer has shipped a feature to production and immediately wished they had not. Something works fine in staging. It breaks in production. Users are affected. A rollback means a redeployment — and redeployments take time, require coordination, and sometimes break other things in the process.

Feature flags decouple deployment from release. You merge the code, you deploy it, but the feature stays hidden behind a flag set to false. When you are ready to release — or when you want to release to just 10 users first — you flip the flag. No redeployment. No code change. Instant.

For AI products specifically, this matters more than for most software. AI features have a different risk profile. A new model might behave unexpectedly under production load. A new AI agent capability might produce output you did not anticipate. A new prompting strategy might increase latency. You want to be able to release these changes to a subset of users, monitor behavior, and either expand the rollout or kill the feature with a single dashboard toggle.

That is exactly what Kinde's feature flags give you — and unlike standalone feature flag tools, Kinde's flags live in the same auth token as your user's identity and permissions. No separate SDK. No separate API call. No synchronization problem between your auth state and your flag state.

How Kinde Feature Flags Work

Most feature flag services require you to install a separate SDK, make an API call at runtime to fetch flag values, and cache them in localStorage or memory. This adds latency, adds a dependency, and creates a potential desync between what your auth system knows about the user and what your flag system thinks.

Kinde takes a different approach. Flag values are embedded directly in the JWT access token under the feature_flags claim. Every time the user's token refreshes, their flag values refresh with it. No separate call. No extra SDK. The flags arrive with the auth token.

Here is what that claim looks like in a real Kinde access token:

{
  "sub": "kp_abc123",
  "email": "alice@example.com",
  "feature_flags": {
    "new_ai_model": { "t": "b", "v": false },
    "ai_token_limit": { "t": "i", "v": 1000 },
    "prompt_variant": { "t": "s", "v": "control" },
    "model_config": { "t": "j", "v": { "temperature": 0.7, "max_tokens": 500 } }
  },
  "permissions": ["reports:view"],
  "org_code": "org_xyz789"
}

The "t" field is the type ("b" = boolean, "i" = integer, "s" = string, "j" = JSON) and "v" is the value. The Kinde SDK wraps this cleanly so you never have to parse the raw token.

Note: Kinde feature flags are completely free on every plan, for every user.

The Four Flag Types

Kinde supports four flag types. The type is set at creation and cannot be changed later — the key also cannot be changed, so choose carefully before saving.

Boolean is the classic on/off switch. Use it for anything that is either enabled or disabled: a new feature, a beta programme, a kill switch for a misbehaving AI capability.

Flag key:     new_ai_model
Type:         Boolean
Default:      false
Use case:     Hide the new GPT-5 integration until ready for gradual rollout

String passes configuration values as text. Use it for A/B testing copy, selecting between variants of a feature, or setting environment-specific values.

Flag key:     prompt_variant
Type:         String
Default:      "control"
Use case:     Test different AI prompt strategies: "control" vs "chain_of_thought" vs "few_shot"

Integer passes numeric limits. Use it to set per-user or per-organization quotas, limits, or thresholds.

Flag key:     ai_token_limit
Type:         Integer
Default:      1000
Use case:     Control how many AI tokens each user can consume per session

JSON passes structured configuration objects. Use it for complex feature configurations that involve multiple related values.

Flag key:     model_config
Type:         JSON
Default:      { "temperature": 0.7, "max_tokens": 500, "model": "gpt-4o" }
Use case:     Send the full AI model configuration to the app without a redeployment

Type	SDK method	Best for
Boolean	`getBooleanFlag`	Feature on/off, kill switches, beta access
String	`getStringFlag`	A/B variants, copy testing, environment labels
Integer	`getIntegerFlag`	Rate limits, quotas, timeouts, seat counts
JSON	`getFlag` (with type)	Model configs, complex feature settings

Step #1: Create a Feature Flag in Kinde

Navigate to Releases → Feature flags → Add feature flag in your Kinde dashboard.

Fill in the flag details:

Name: A human-readable label, for example "New AI Model". This can be changed later.

Key: The identifier your code uses, for example new_ai_model. Use lowercase with underscores. This cannot be changed after creation.

Type: Select one of Boolean, String, Integer, or JSON. This also cannot be changed after creation.

Default value: The value every user gets unless overridden. For a new feature you are not ready to release, the default is false for Boolean.

Allow overrides: Select whether the flag value can be overridden per environment, per organization, or per user. Enable organizations — you will want the flexibility.

Select Save. The flag now exists with a global default of false. Every user in every organization gets false until you explicitly enable it somewhere.

Wonderful! The flag is created and safely off. Now wire it into your application.

Step #2: Read Flags in a Next.js Application

The Kinde Next.js SDK exposes flag methods through getKindeServerSession() on the server and useKindeBrowserClient() on the client. For most production use cases, read flags server-side.

// app/dashboard/page.tsx
import { getKindeServerSession } from "@kinde-oss/kinde-auth-nextjs/server";
import { redirect } from "next/navigation";

export default async function DashboardPage() {
  const {
    isAuthenticated,
    getUser,
    getBooleanFlag,
    getIntegerFlag,
    getStringFlag,
  } = getKindeServerSession();

  if (!(await isAuthenticated())) {
    redirect("/api/auth/login");
  }

  const user = await getUser();

  // Read each flag with a default value as fallback
  // The default value is used if the flag doesn't exist in the token
  const showNewAIModel = await getBooleanFlag("new_ai_model", false);
  const aiTokenLimit = await getIntegerFlag("ai_token_limit", 1000);
  const promptVariant = await getStringFlag("prompt_variant", "control");

  return (
    <main className="p-8">
      <h1>Dashboard</h1>

      {/* Only render the new AI section if the flag is on */}
      {showNewAIModel && (
        <section className="mt-6 rounded-lg bg-purple-50 p-6">
          <h2 className="font-semibold text-purple-900">
            ✨ New AI Model (Beta)
          </h2>
          <p className="text-sm text-purple-700 mt-1">
            You have early access to our upgraded AI model.
          </p>
          <AIModelInterface
            tokenLimit={aiTokenLimit}
            promptVariant={promptVariant}
          />
        </section>
      )}

      {/* Standard content visible to all users */}
      <section className="mt-6">
        <h2 className="font-semibold">Standard Features</h2>
        <StandardInterface tokenLimit={aiTokenLimit} />
      </section>
    </main>
  );
}

// Placeholder components
function AIModelInterface({
  tokenLimit,
  promptVariant,
}: {
  tokenLimit: number;
  promptVariant: string;
}) {
  return (
    <div className="mt-4">
      <p className="text-xs text-purple-500">
        Token limit: {tokenLimit} | Variant: {promptVariant}
      </p>
    </div>
  );
}

function StandardInterface({ tokenLimit }: { tokenLimit: number }) {
  return <p className="text-sm text-gray-500">Token limit: {tokenLimit}</p>;
}

Note: getBooleanFlag("new_ai_model", false) takes the flag key and a default value. If the flag does not exist in the user's token for any reason (flag not created yet, SDK version mismatch), the default value is returned. This makes your application safe to deploy before the flag exists in Kinde.

Step #3: Override Flags Per Environment

The most common override pattern: the new feature is false globally, but true in your staging environment so your team can test it before any users see it.

Navigate to Settings → Environment → Feature flags (make sure you are in your staging environment, not production).

Find new_ai_model and select Edit value. Switch it to true. Select Save.

Now everyone in your staging environment sees the new AI feature. Everyone in production still sees false. Your team tests it, confirms it works, and when ready you flip it on in production — no code change, no redeployment.

The cascade order for flag evaluation is:

Business default → Environment override → Organization override → User override

The most specific level wins. A user override takes precedence over everything. An organization override takes precedence over the environment. The business default is the fallback when nothing else is set.

Step #4: Override Flags Per Organization for Gradual Rollouts

For B2B AI products, you often want to enable a new feature for specific customer organizations before rolling it out globally. An org-level override is exactly how you do this.

Navigate to Organizations → select your pilot customer's org → Feature flags.

Select Edit value next to secondn_ai_model and set it to true. That organization's users now see the new AI feature. Every other organization still inherits the false default.

This is gradual rollout in practice. Your rollout sequence for a significant AI feature might look like this:

Week 1: Enable for your own organization (internal testing)

Week 2: Enable for 2-3 design partner organizations (trusted early adopters)

Week 3: Enable for 10% of organizations (broader beta)

Week 4: Set business default to true (full rollout) and remove org overrides

No deployments. No feature branches. No big-bang release. Each step is a toggle in the Kinde dashboard.

Step #5: Override Flags Per User for Beta Access

Sometimes you want to give specific individuals early access — a power user who has asked for beta features, a journalist reviewing the product, or your own test account.

Navigate to Users → select the user → Feature flags.

Find third_ai_model and select Edit value. Set it to true. This user now has the new AI feature regardless of which organization they belong to and regardless of the environment default.

Note: User-level overrides apply across all organizations and environments for that user. They are the most specific level and cannot be further scoped. If you want to give a user access in one org but not another, use org-level overrides instead.

Step #6: Use String Flags for AI Prompt A/B Testing

String flags unlock a particularly powerful pattern for AI products: testing different prompt strategies without redeployment.

Create a flag called ai_prompt_strategy of type String with a default value of "standard". Enable environment and organization overrides.

In your API route that calls the AI:

// app/api/ai/chat/route.ts
import { getKindeServerSession } from "@kinde-oss/kinde-auth-nextjs/server";
import { NextRequest, NextResponse } from "next/server";

// Prompt templates for each variant
const PROMPT_STRATEGIES = {
  standard: (userMessage: string) =>
    `You are a helpful assistant. User: ${userMessage}`,

  chain_of_thought: (userMessage: string) =>
    `You are a helpful assistant. Think step-by-step before answering.
    User: ${userMessage}
    Let me work through this carefully:`,

  few_shot: (userMessage: string) =>
    `You are a helpful assistant. Here are examples of good responses:
    Q: What is 2+2? A: 4. Q: What is the capital of France? A: Paris.
    Now answer: ${userMessage}`,
} as const;

type PromptStrategy = keyof typeof PROMPT_STRATEGIES;

export async function POST(request: NextRequest) {
  const { isAuthenticated, getStringFlag, getIntegerFlag } =
    getKindeServerSession();

  if (!(await isAuthenticated())) {
    return NextResponse.json({ error: "Unauthenticated" }, { status: 401 });
  }

  // Read the prompt strategy flag for this user
  const strategy = (await getStringFlag(
    "ai_prompt_strategy",
    "standard"
  )) as PromptStrategy;

  // Read the token limit flag for this user
  const maxTokens = await getIntegerFlag("ai_token_limit", 1000);

  const { message } = await request.json();

  // Build the prompt based on the user's assigned variant
  const promptBuilder = PROMPT_STRATEGIES[strategy] ?? PROMPT_STRATEGIES.standard;
  const prompt = promptBuilder(message);

  // Call your AI provider with the variant prompt and limit
  const aiResponse = await callAIProvider({
    prompt,
    maxTokens,
    // Log which variant was used for analytics
    metadata: { strategy, userId: "from_session" },
  });

  return NextResponse.json({
    response: aiResponse,
    // Optionally surface the variant in the response for debugging
    _variant: process.env.NODE_ENV === "development" ? strategy : undefined,
  });
}

async function callAIProvider({
  prompt,
  maxTokens,
  metadata,
}: {
  prompt: string;
  maxTokens: number;
  metadata: Record<string, string>;
}) {
  // Replace with your actual AI provider call
  console.log("Calling AI with strategy:", metadata.strategy);
  return "AI response placeholder";
}

To run the A/B test: set ai_prompt_strategy to "chain_of_thought" for half your organizations in Kinde's org overrides. The other half inherits "standard". Monitor which variant produces better outcomes in your analytics. When you have a winner, update the business default to the winning strategy and remove the overrides.

Step #7: Use Integer Flags for AI Token Limits

AI API costs are directly proportional to token consumption. Integer flags let you set per-user or per-plan token limits without redeploying when you need to adjust them.

Create a flag called ai_token_limit of type Integer with a default value of 1000. Enable all overrides.

Use it in your AI route handler:

// In your AI route handler — enforce the token limit before calling the AI
const maxTokens = await getIntegerFlag("ai_token_limit", 1000);

// Validate the requested tokens against the user's limit
const requestedTokens = body.max_tokens ?? 500;
const enforcedTokens = Math.min(requestedTokens, maxTokens);

if (requestedTokens > maxTokens) {
  console.log(
    `User requested ${requestedTokens} tokens, capped to ${maxTokens}`
  );
}

// Use enforcedTokens in your AI call
const response = await openai.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: prompt }],
  max_tokens: enforcedTokens,
});

Now adjust limits per organization without touching code:

Free plan orgs: set ai_token_limit to 500 via org override
Pro plan orgs: inherit the default of 1000
Enterprise orgs: set ai_token_limit to 5000 via org override
Your own internal org: set ai_token_limit to 10000 for testing

When your infrastructure changes and you need to globally reduce the default limit, change the business default in the Kinde dashboard. Every user's limit updates at their next token refresh — no deployment.

Step #8: Use JSON Flags for Complex AI Configurations

When multiple related configuration values need to change together, JSON flags keep them atomic. If you use separate flags for each value, you can end up in a state where some values have been updated and others have not, which can cause subtle bugs.

Create a flag called ai_model_config of type JSON with a default value:

{
  "model": "gpt-4o",
  "temperature": 0.7,
  "max_tokens": 500,
  "system_prompt": "You are a helpful AI assistant."
}

Enable environment and organization overrides. Now use it in your application:

// app/api/ai/generate/route.ts
import { getKindeServerSession } from "@kinde-oss/kinde-auth-nextjs/server";
import { NextRequest, NextResponse } from "next/server";

interface AIModelConfig {
  model: string;
  temperature: number;
  max_tokens: number;
  system_prompt: string;
}

const DEFAULT_CONFIG: AIModelConfig = {
  model: "gpt-4o",
  temperature: 0.7,
  max_tokens: 500,
  system_prompt: "You are a helpful AI assistant.",
};

export async function POST(request: NextRequest) {
  const { isAuthenticated, getFlag } = getKindeServerSession();

  if (!(await isAuthenticated())) {
    return NextResponse.json({ error: "Unauthenticated" }, { status: 401 });
  }

  // Read the JSON flag — use getFlag with type "j" for JSON
  const configFlag = await getFlag(
    "ai_model_config",
    DEFAULT_CONFIG,
    "j" // "j" = JSON type
  );

  // configFlag.value contains the parsed JSON object
  const config = (configFlag?.value as AIModelConfig) ?? DEFAULT_CONFIG;

  const { message } = await request.json();

  // Use the full config from the flag — one atomic update in Kinde
  // changes model, temperature, max_tokens, and system_prompt together
  const response = await callAI({
    model: config.model,
    temperature: config.temperature,
    maxTokens: config.max_tokens,
    systemPrompt: config.system_prompt,
    userMessage: message,
  });

  return NextResponse.json({ response });
}

async function callAI({
  model,
  temperature,
  maxTokens,
  systemPrompt,
  userMessage,
}: {
  model: string;
  temperature: number;
  maxTokens: number;
  systemPrompt: string;
  userMessage: string;
}) {
  // Your AI provider call using the flag-configured values
  console.log(`Using model: ${model}, temp: ${temperature}, max_tokens: ${maxTokens}`);
  return "AI response placeholder";
}

When you want to test a newer model with different parameters, update the JSON flag value for your staging environment. If it works well, update the production environment override. If there is a problem, revert the JSON flag — all four values revert atomically.

Putting It All Together

Here is a complete rollout lifecycle for a major AI feature using flags:

Phase 1 — Development (flag default: false):
Code is deployed behind the flag. Nothing changes for users. Your team iterates freely.

Phase 2 — Internal testing (environment override: staging true):
The feature is live in staging. Your team tests it thoroughly against real data. Production users are unaffected.

Phase 3 — Beta access (user overrides: specific users true):
You enable the flag for 5 power users and your own account. Collect feedback. Fix issues without touching code.

Phase 4 — Gradual rollout (org overrides: pilot orgs true):
Enable for 3 design partner organizations. Monitor AI token consumption, error rates, user satisfaction. Expand to 20% of orgs if metrics look good.

Phase 5 — Full release (business default: true):
Update the global default to true. All remaining users see the feature. Remove org-level overrides — they are no longer needed.

Phase 6 — Cleanup (delete the flag):
Once the feature is stable and you are confident you will not need to roll back, remove the flag from your code and delete it from Kinde. Temporary flags are technical debt. A flag that controls a permanent feature state can stay; a flag that was used to control a release should go.

Flag Naming Conventions

A flag library grows fast. Without conventions it becomes unmanageable. Use these patterns from the start:

Prefix by category:

ai_*        AI feature flags (ai_new_model, ai_token_limit, ai_prompt_strategy)
ui_*        UI and design flags (ui_dark_mode, ui_new_nav)
billing_*   Billing and plan flags (billing_annual_discount)
beta_*      Beta features (beta_voice_input, beta_export_pdf)

Use positive names for booleans: show_new_dashboard not hide_old_dashboard. Double negatives in code (if (!hideOldDashboard)) cause bugs.

Use descriptive names for strings and integers: ai_model_name not model, ai_max_tokens_per_request not limit.

Document the flag purpose in the description field. Kinde lets you add a description when creating the flag. Write what the flag does, what the rollout plan is, and when it should be deleted. Future you will appreciate it.

Conclusion

In this article, you learned how to use Kinde feature flags to safely roll out features in production — using all four flag types, managing overrides at the environment, organization, and user levels, and running a phased rollout from internal testing to full release without a single redeployment.

The key insight that makes Kinde's approach different: flags are delivered in the auth token, not fetched separately. The same token that authenticates your user also carries their flag values, their permissions, and their organization context. One integration. One token. Everything your application needs to make runtime decisions.

Kinde is free for up to 10,500 monthly active users, no credit card required. Feature flags are available on every plan. Create your account at kinde.com and start shipping code with confidence.

How to Add Enterprise SSO to Your AI App With Kinde: SAML, OIDC, and Beyond

Shola Jegede — Tue, 14 Apr 2026 12:47:33 +0000

Enterprise buyers will not deploy your AI app without SSO. Here is everything you need to know to pass that security review.

In this article, you will learn:

Why enterprise SSO is now non-negotiable for AI apps that sell to businesses
The difference between SAML and OIDC — and which one to use when
How Kinde models enterprise connections with organizations
How to configure a custom SAML connection in Kinde step by step
How to configure a Microsoft Entra ID (Azure AD) SAML connection
What home realm discovery is and why it makes the login experience seamless
How JIT (just-in-time) provisioning works in Kinde
How IdP-initiated SSO works (Kinde shipped this in February 2026)
How to let enterprise customers configure their own SSO via the self-serve portal
How to use Kinde's suspend organization feature when a customer churns or has a security incident

Let's dive in!

Why Enterprise SSO Is No Longer Optional for AI Apps

There is a question every AI founder building for enterprise customers will hear sooner or later, usually from IT security during a procurement review: "Do you support SSO?"

The wrong answer ends the deal. Not "we're working on it." Not "we have Google login." SSO — specifically SAML 2.0 or enterprise OIDC federated to the company's identity provider — is a hard requirement for any AI app that wants to handle company data at scale.

The reason is not bureaucracy. It is a genuine security need that AI tools make more acute than most SaaS products. When a 30-person team at a financial services firm deploys your AI app to analyze internal documents, every one of those 30 users needs to be automatically deprovisioned the moment they leave the company. With SSO, that happens instantly — their IdP account is deactivated and they cannot access your app, your AI's context, or your data. Without SSO, some offboarding ticket eventually gets filed and one of those users might still have access six weeks after their last day.

Enterprise IT teams also need your AI app to be visible in their identity governance stack. If your app lives outside their IdP's audit trail, it will not pass a SOC 2 or ISO 27001 review. SSO is what makes your app governable.

The good news: adding enterprise SSO no longer requires weeks of work. Kinde handles the SAML/OIDC infrastructure — you configure connections in a dashboard, your app code stays exactly as it is, and enterprise customers connect their Okta, Entra ID, or other IdP the same day they ask for it.

SAML vs OIDC: Choosing the Right Protocol

Before touching any configuration, understand which protocol your customer needs. Getting this wrong means starting over.

SAML 2.0 is the enterprise legacy standard. XML-based, widely supported by every major enterprise IdP including Okta, Microsoft Entra ID (Azure AD), Google Workspace, and Ping Identity. If your customer has been in business for more than 10 years or works in financial services, healthcare, or government, they almost certainly have SAML infrastructure. This is the protocol you will encounter most often in enterprise procurement reviews.

OIDC (OpenID Connect) is the modern standard, built on OAuth 2.0. JSON-based, simpler to implement, better suited for mobile and API-driven authentication. Increasingly preferred by newer enterprises and tech companies. If your customer uses Okta with OIDC configured, or runs a modern identity stack, OIDC is the cleaner choice.

Both are fully supported by Kinde. Here is a practical decision guide:

Scenario	Recommended protocol
Customer uses Okta, Ping, or ADFS	SAML 2.0
Customer uses Microsoft Entra ID (Azure AD)	SAML or Entra ID OIDC — both work
Customer is a modern tech company with Google Workspace	SAML (Google Workspace SAML)
Customer uses a modern cloud-native IdP	OIDC
Customer has no strong preference	OIDC — simpler to configure
Customer's IT team sends you XML metadata	SAML — that is their preference

Note: If a customer sends you an XML metadata URL, they are using SAML. If they send you a discovery endpoint URL ending in .well-known/openid-configuration, they are using OIDC. The format of what they provide tells you the protocol.

How Kinde Models Enterprise SSO

Kinde's SSO model is built around two concepts you need to understand before configuring anything.

Kinde acts as the Service Provider (SP). Your enterprise customer acts as (or connects to) the Identity Provider (IdP). This means the IdP owns the user identities — their Okta, Entra ID, or Google Workspace is the source of truth. Kinde receives the authentication assertion from the IdP and issues its own session token to your app. Your application code always talks to Kinde — never directly to the customer's IdP.

Enterprise connections live on organizations. In Kinde, each enterprise customer is a Kinde organization. Their SSO connection is attached to that organization. This is the right model for multi-tenant AI apps: one connection per customer, each isolated, each independently configurable. Acme Corp's Okta SAML setup has no effect on Globex Inc's Entra ID configuration.

Step #1: Create an Organization for Your Enterprise Customer

Each enterprise customer gets their own Kinde organization. If you already have organizations set up, skip to Step #2.

Navigate to Organizations in your Kinde dashboard and select Create organization. Give it the name of the enterprise customer — this is internal to your Kinde account, not visible to end users. Note the org code assigned; you will use it when scoping the connection.

For multi-tenant AI apps, each customer organization is also where you will attach billing, custom roles, and per-org MFA requirements. The enterprise connection is just one of many things scoped per organization.

Step #2: Configure a Custom SAML Connection

This is the generic SAML path that works with any SAML 2.0-compliant IdP. Go through this if your customer uses an IdP not covered by Kinde's named integrations (Okta, Entra ID, Google Workspace, Cloudflare, LastPass).

In your Kinde dashboard, navigate to Settings → Environment → Authentication and scroll to the Enterprise connection section. Select Add connection.

Select Custom SAML and click Next. You will now configure the connection:

Step 2a: Connection name. Enter a descriptive name like Acme Corp Okta SAML. This is internal — use whatever helps you identify it.

Step 2b: Entity ID. Generate a random alphanumeric string, for example hEb876ZZlkg99Dwat64Mnbvyh129. Copy it — you will add this to your customer's IdP configuration as the SP Entity ID (also called Audience URI in some IdPs).

Step 2c: ACS URL. Kinde generates this for you. It is the URL where the IdP will send the SAML response after authentication. It looks like:

# Without custom domain
https://your-subdomain.kinde.com/login/saml/callback

# With custom domain
https://auth.yourdomain.com/login/saml/callback

Copy the ACS URL — your customer's IT team needs this to configure their IdP.

Step 2d: IdP metadata URL. Your customer's IT team provides this. It is a URL that Kinde fetches to get the IdP's public certificate and endpoints. In Okta it is typically https://your-okta-domain.okta.com/app/your-app-id/sso/saml/metadata. In other IdPs it may be called the Federation Metadata URL.

Step 2e: Email attribute. This tells Kinde which SAML attribute contains the user's email address. The standard value is http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress for Entra ID or simply email for most others. If left blank, Kinde defaults to email.

Step 2f: Home realm domains. Enter the email domains that route to this connection, for example acmecorp.com. When a user enters their email during login and it matches this domain, Kinde silently routes them to the Acme Corp SAML IdP without showing an SSO button. This is home realm discovery — users experience seamless, invisible SSO.

Step 2g: JIT provisioning. Enable Create a user record in Kinde if you want users to be automatically created in Kinde on their first SSO login. This is almost always the right choice for enterprise customers — it means you do not have to pre-provision users manually. They sign in through their IdP and Kinde creates their account automatically.

Step 2h: Trust email addresses. Enable this if you want Kinde to match SSO users to existing Kinde users by email. For example, if a user already has an account in Kinde via email/password, enabling this merges them with the incoming SSO identity. If disabled, a new separate identity is created regardless.

Select Save. The connection is created. Now give your customer's IT team the following information:

SP Entity ID (Audience URI): [your Entity ID string]
ACS URL (Reply URL):          https://your-subdomain.kinde.com/login/saml/callback
Name ID format:               Email address (urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress)

That is all the IT team needs to configure their IdP. Once they complete setup and activate the connection on their side, test by having a user from their domain attempt to log in to your app.

A working SAML connection in about 10 minutes of configuration on each side.

Step #3: Configure Microsoft Entra ID (Azure AD) SAML

Microsoft Entra ID is the most common enterprise IdP for AI apps selling into corporate accounts. Kinde has a dedicated Entra ID connection type that handles Entra-specific quirks — including a note that older Entra tenants require the Entity ID to have a spn: prefix.

Navigate to Settings → Authentication → Add connection → Microsoft Entra ID (SAML).

The configuration is similar to custom SAML with a few Entra-specific fields:

Step 3a: Connection name. For example Acme Corp Entra ID.

Step 3b: Entity ID. Generate a random string as before. If your connection fails after setup, try prefixing it with spn: — this is an older Entra ID requirement some tenants still have.

Step 3c: IdP metadata URL. From the Microsoft Entra admin center, navigate to Enterprise applications → your app → Single sign-on → SAML → App Federation Metadata URL. Copy this URL and paste it into Kinde.

Step 3d: Email attribute. For Entra ID SAML, the email attribute is:

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress

Enter this value exactly. Getting this wrong is the most common cause of Entra ID SAML failures — Kinde receives the SAML assertion but cannot find the email claim.

Step 3e: Home realm domains. Enter the corporate domain(s), for example acmecorp.com, acmecorp.onmicrosoft.com.

On the Entra ID side, your customer's IT admin needs to create an Enterprise Application in the Azure portal with:

Reply URL (ACS URL): The ACS URL from Kinde
Identifier (Entity ID): The Entity ID string you created in Kinde
Sign on URL: Your app's login URL (optional)
Attributes & Claims: Ensure the email claim is mapped to the user's email attribute

Note: If you need additional Entra ID attributes in Kinde (like department, phone number, or group membership), you can sync them using a Kinde post-authentication workflow. The workflow reads the SAML assertion attributes and writes them to Kinde custom user properties.

Step #4: Enable IdP-Initiated SSO

Standard SAML flow is SP-initiated: the user starts at your app, clicks login, gets redirected to the IdP, authenticates, and comes back. This is the most common setup.

Kinde shipped IdP-initiated SSO in February 2026. With IdP-initiated flow, users start the login from their IdP portal — for example, clicking your app's tile in Okta or the Microsoft MyApps dashboard. They are authenticated at the IdP first, and Kinde handles the unsolicited SAML response when it arrives.

To enable IdP-initiated SSO for a connection, navigate to the connection in Kinde and toggle on Allow IdP-initiated SSO. When this is enabled, Kinde also uses the email from the SAML response to pre-fill the login screen if the user ends up being redirected back to an SP-initiated flow, reducing friction.

Enterprise customers who use a company intranet or application portal (like Okta's dashboard or Microsoft MyApps) often require IdP-initiated flow. Without it, they cannot tile your app in their portal — and tiling apps is how IT controls visibility and access across the company. Enabling this expands your deployment options inside enterprise accounts significantly.

Step #5: Set Up Home Realm Discovery for Seamless Login

Home realm discovery is what makes enterprise SSO feel invisible to end users. Instead of showing a generic "Sign in with SSO" button that users may not understand, Kinde detects the user's email domain and automatically routes them to the correct IdP.

You already set home realm domains in Step #2. Here is how the experience works once configured:

User navigates to your AI app and reaches the Kinde login page
User enters their email address: alice@acmecorp.com
Kinde matches the acmecorp.com domain to the Acme Corp SAML connection
Kinde silently redirects Alice to Acme Corp's Okta for authentication
Alice authenticates with Okta (likely already SSO'd from her device)
Okta sends the SAML assertion back to Kinde
Kinde issues a session token and Alice lands in your app

Steps 3 through 6 happen in under a second. From Alice's perspective, she typed her email and landed in the app. No separate SSO button. No understanding of SAML required.

Note: Home realm domains must be unique across all connections in your Kinde environment. If you add acmecorp.com to one connection, no other connection can also claim it.

Step #6: Let Enterprise Customers Configure Their Own SSO

For AI apps with many enterprise customers, having your team configure each SAML connection manually does not scale. Kinde supports self-serve SSO configuration (available on Scale plans) — enterprise customers can configure their own SSO connection through the Kinde self-serve portal.

When self-serve SSO is enabled for an organization, the customer's admin (a user with the appropriate role in your app) can visit the self-serve portal, navigate to Security or Connections, and configure their SAML or OIDC connection themselves.

They enter their IdP metadata URL, set their attribute mappings, and submit. Kinde validates the configuration and creates the connection. Your team gets notified but does not need to be involved in the data entry.

To enable this, navigate to Settings → Self-serve portal → and enable SSO self-management for the relevant organizations. You can control which organizations have this capability — you might enable it only for enterprise-tier customers.

This is the SSO motion that scales. Your enterprise sales team closes the deal and mentions SSO as a feature the customer can configure themselves on day one. No engineering ticket. No back-and-forth over Entity IDs. The customer's IT admin does the setup in your self-serve portal in 20 minutes.

Step #7: Read Enterprise Identity in Your App

Once enterprise SSO is configured, the user's Kinde session looks exactly the same as any other authenticated session. Your application code does not need to know or care whether the user authenticated via email OTP, Google login, or enterprise SAML. The same Kinde SDK methods work for all of them.

In a Next.js application:

// app/dashboard/page.tsx
import { getKindeServerSession } from "@kinde-oss/kinde-auth-nextjs/server";
import { redirect } from "next/navigation";

export default async function DashboardPage() {
  const { isAuthenticated, getUser, getOrganization } =
    getKindeServerSession();

  if (!(await isAuthenticated())) {
    redirect("/api/auth/login");
  }

  const user = await getUser();
  const org = await getOrganization();

  // user.email comes from the SAML assertion for SSO users
  // org.orgCode identifies which enterprise customer this is
  // No special handling needed for SSO vs non-SSO users

  return (
    <main className="p-8">
      <h1>Welcome, {user?.given_name}</h1>
      <p className="text-gray-500">
        Signed in via {org?.name ?? "your organization"}
      </p>
    </main>
  );
}

If you want to know which authentication method the user used (useful for audit logs or analytics), you can check the identities from the Kinde Management API. But for most application logic, you simply use getUser() and getOrganization() without worrying about the underlying auth method.

For AI apps that need to enforce that specific customers must use SSO and cannot fall back to email/password, configure an org-level access policy in Kinde. Navigate to Organizations → select the org → Access policies → enable Require enterprise connection. Users who try to log in to this organization via email/password will be blocked and prompted to use SSO instead.

// Verify the user is authenticated via enterprise SSO for sensitive AI operations
// This is an optional extra layer — Kinde's access policies handle the enforcement,
// but you can also check in your API routes for audit purposes
import { getKindeServerSession } from "@kinde-oss/kinde-auth-nextjs/server";
import { NextRequest, NextResponse } from "next/server";

export async function POST(request: NextRequest) {
  const { isAuthenticated, getOrganization } = getKindeServerSession();

  if (!(await isAuthenticated())) {
    return NextResponse.json({ error: "Unauthenticated" }, { status: 401 });
  }

  const org = await getOrganization();

  // Log the org for audit trail — critical for enterprise AI compliance
  console.log(`AI request from org: ${org?.orgCode}, user: ${(await getKindeServerSession().getUser())?.id}`);

  // Execute AI operation
  // ...

  return NextResponse.json({ result: "..." });
}

Step #8: Suspend an Organization Instantly

Enterprise contracts end. Security incidents happen. When either occurs, you need to cut off an entire organization's access immediately — not one user at a time.

Kinde added organization suspension in February 2026. When you suspend an org, every active token is revoked and every session is invalidated instantly. No user from that organization can log in to your app, regardless of how they authenticated.

Navigate to Organizations → select the org → Settings → Suspend organization. Select Suspend. Done.

Unsuspending restores access just as quickly — toggle the same setting off and all users can log back in at their next login attempt.

This feature is essential for enterprise AI apps for two reasons. First, when a customer churns or does not renew, you need access revocation to happen immediately, not when individual users try to log in and find their tokens expired. Second, if a customer reports a security incident (a compromised account, suspicious AI queries, a potential data breach), suspension gives you a one-click kill switch while you investigate.

Putting It All Together

Here is the full enterprise SSO setup checklist for your AI app:

In Kinde dashboard:

Organization created for each enterprise customer
SAML or OIDC connection configured and saved
Home realm domain(s) set for seamless routing
JIT provisioning enabled for automatic user creation
IdP-initiated SSO enabled (if customer uses an app portal)
Org-level access policy set to require enterprise connection (optional but recommended for security-sensitive customers)
Self-serve SSO enabled for enterprise-tier orgs (Scale plan)

What you give the customer's IT team:

SP Entity ID (Audience URI)
ACS URL (Reply URL)
Name ID format: urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress

What the customer's IT team gives you:

IdP metadata URL (or the XML metadata itself)
Email attribute name (if non-standard)
Home realm domains to register

In your application code:

No changes required to authentication logic
Use getUser() and getOrganization() as normal
Add org-level access policy enforcement in API routes if needed
Log orgCode in audit trails for all AI operations

SAML Troubleshooting Reference

These are the most common SAML configuration problems and how to fix them in Kinde:

Symptom	Likely cause	Fix
"Invalid assertion" error	Certificate mismatch or expired IdP cert	Re-fetch the IdP metadata URL in Kinde to refresh the certificate
User authenticated but no email	Wrong email attribute name	Check the Entra/Okta attribute configuration and update the email attribute field in Kinde
Loop between app and IdP	ACS URL misconfigured	Verify the ACS URL in the IdP exactly matches what Kinde shows (including protocol and path)
"Entity ID not found"	SP Entity ID mismatch	Confirm the Entity ID in your IdP matches the string you set in Kinde exactly
Users get separate accounts	Trust email not enabled	Enable "Trust email addresses" in the connection settings to merge existing users
Old Entra ID tenant fails	Entity ID format	Prefix the Entity ID with `spn:` — required by some older Entra tenants
SSO button shows for home realm users	Home realm domain not set	Add the email domain to the connection's home realm domains

Navigate to Settings → Logs → Authentication logs in Kinde to see detailed SAML assertion logs for failed authentication attempts. This is the fastest way to identify configuration issues.

Conclusion

In this article, you configured enterprise SSO for your AI app — custom SAML, Microsoft Entra ID SAML, home realm discovery, JIT provisioning, IdP-initiated flow, customer self-serve setup, and organization suspension. Your AI app can now pass enterprise security reviews, integrate with any major corporate identity provider, and automatically revoke access when users leave a customer's organization.

The entire configuration lives in Kinde. Your application code is completely unchanged — the same getUser() and getOrganization() calls that work for email login work for enterprise SAML. Kinde normalizes all authentication methods into the same session model.

Enterprise SSO used to be the feature that required a dedicated engineering sprint and an enterprise-tier contract with your auth provider. With Kinde, it is a configuration that takes an afternoon and is available on all paid plans.

Create a free Kinde account at kinde.com — 10,500 monthly active users, no credit card required — and have your first enterprise connection configured before your next security review.

How to Implement RBAC in a Next.js 16 App With Kinde: A Step-by-Step Guide

Shola Jegede — Tue, 14 Apr 2026 10:35:04 +0000

Next.js 16 ships with proxy.ts, React Compiler, and React 19.2. Your access control should be as modern as your stack.

In this article, you will learn:

What RBAC is and why it belongs in your auth layer, not your database
How Kinde models roles and permissions and why that maps cleanly to Next.js 16
How to set up the Kinde Next.js SDK in a Next.js 16.2 project
How to configure the auth handler and environment variables
How to protect routes using proxy.ts — the new Next.js 16 network boundary file
How to define roles and permissions in the Kinde dashboard
How to enforce permissions in React Server Components
How to enforce permissions in Route Handlers (API routes)
How to render conditional UI based on a user's role
How to handle the use cache directive safely alongside permission checks

Let's dive in!

Prerequisites

Before starting this tutorial, make sure you have:

Node.js 18.18 or later installed
A Kinde account — free at kinde.com, no credit card required
Familiarity with Next.js App Router fundamentals
Basic knowledge of TypeScript

What Is RBAC and Why Does It Belong in Auth?

Role-Based Access Control (RBAC) is the mechanism that decides what authenticated users are allowed to do. Authentication answers "who are you?" — RBAC answers "what can you do?"

The wrong place to implement RBAC is your database. Many teams check a role column on the user record mid-request, which means a round-trip to the database every time your application needs to make an access decision. That is slow, adds complexity, and couples your permission logic to your data layer.

The right place is your auth token. When a user logs in, Kinde issues a JWT that includes their roles and the exact permissions those roles grant. Your application reads from the token. No extra database query. No round-trip. The permission answer is cryptographically included at the start of every authenticated request.

This is what makes Kinde's RBAC model a natural fit for Next.js 16's Server Components architecture — every Server Component can check permissions synchronously from the session without adding a waterfall of database queries.

How Kinde's RBAC Model Works

Kinde structures access control in three layers that are worth understanding before you write any code:

Permissions are the granular capabilities your application checks: posts:create, posts:delete, users:manage, billing:view. You define these in the Kinde dashboard. They are the atoms of your access system — every access decision in your code should reference a permission key, not a role name.

Roles are named bundles of permissions. admin, editor, viewer are roles. You define roles and attach permissions to them in Kinde. Roles exist so you can assign a coherent set of capabilities to a user in one operation.

Users are assigned roles. When a user logs in, their JWT token contains both their roles and the expanded set of permissions those roles grant. Your code checks permissions — the role is just the management abstraction that groups them.

The access check in your Next.js components is always getPermission("posts:create"), never getRole() === "admin". This decoupling means you can restructure your roles in the Kinde dashboard without touching a line of application code.

What's New in Next.js 16 That Affects This Tutorial

Next.js 16 introduced proxy.ts as the new file for handling network boundary logic, replacing middleware.ts for most use cases. The middleware.ts file is deprecated in 16 and will be removed in a future version.

For RBAC, this matters in one specific way: proxy.ts runs before any route in your application and is where you redirect unauthenticated users. The Kinde withAuth helper plugs into this file just as cleanly as it did into middleware.ts.

Next.js 16 also stabilised the React Compiler, which automatically memoises components. You do not need to manually wrap permission-checking components in useMemo or memo — the compiler handles it.

One important note about use cache in Next.js 16: do not cache pages or components that render based on user-specific permission data. Cached outputs are shared across users. The code in this tutorial keeps permission-sensitive components outside of use cache boundaries.

Step #1: Create a Next.js 16 Project

Start a fresh Next.js 16.2 project with the App Router and TypeScript:

npx create-next-app@latest my-rbac-app \
  --typescript \
  --app \
  --tailwind \
  --src-dir

Navigate into the project directory and install the Kinde Next.js SDK:

cd my-rbac-app
npm install @kinde-oss/kinde-auth-nextjs

Step #2: Configure Kinde and Set Environment Variables

In your Kinde dashboard, navigate to Settings → Applications → Add application and select Back-end web. Give it a name like My Next.js 16 App. Once created, open the application details and copy the following values:

Create a .env.local file in the root of your project:

# Kinde application credentials
KINDE_CLIENT_ID=your_kinde_client_id
KINDE_CLIENT_SECRET=your_kinde_client_secret
KINDE_ISSUER_URL=https://your-subdomain.kinde.com

# Application URLs
KINDE_SITE_URL=http://localhost:3000
KINDE_POST_LOGOUT_REDIRECT_URL=http://localhost:3000
KINDE_POST_LOGIN_REDIRECT_URL=http://localhost:3000/dashboard

Replace your_kinde_client_id, your_kinde_client_secret, and your-subdomain with the values from your Kinde dashboard. The KINDE_ISSUER_URL is your Kinde domain, typically https://yourappname.kinde.com.

Next, add the callback URLs in Kinde. Still in your application's settings, find the Callback URLs section and add:

Allowed callback URLs: http://localhost:3000/api/auth/kinde_callback
Allowed logout redirect URLs: http://localhost:3000

Step #3: Set Up the Auth Route Handler

Create the Kinde auth handler at app/api/auth/[kindeAuth]/route.ts. This single file handles all of Kinde's auth endpoints — login, logout, register, and the callback:

// app/api/auth/[kindeAuth]/route.ts
import { handleAuth } from "@kinde-oss/kinde-auth-nextjs/server";

export const GET = handleAuth();

That is the entire auth route. Kinde handles the OAuth flow, token exchange, session management, and redirect logic. Your application does not need to implement any of this.

Step #4: Wrap the Root Layout with KindeProvider

Open app/layout.tsx and wrap the children with KindeProvider. This is a server component — import from the server path, not the client path:

// layout.ts
import type { Metadata } from "next";
import { Geist, Geist_Mono } from "next/font/google";
import "./globals.css";

const geistSans = Geist({
  variable: "--font-geist-sans",
  subsets: ["latin"],
});

const geistMono = Geist_Mono({
  variable: "--font-geist-mono",
  subsets: ["latin"],
});

export const metadata: Metadata = {
  title: "My RBAC App",
  description: "Built with Next.js 16 and Kinde",
};

export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  return (
    <html
      lang="en"
      className={`${geistSans.variable} ${geistMono.variable} h-full antialiased`}
    >
      <body className="min-h-full flex flex-col">{children}</body>
    </html>
  );
}

Step #5: Protect Routes Using proxy.ts

In Next.js 16, proxy.ts is the new file for network boundary logic. The middleware.ts file is deprecated — use proxy.ts instead for new projects.

Create proxy.ts in your project root (at the same level as app):

// proxy.ts
import { withAuth } from "@kinde-oss/kinde-auth-nextjs/middleware";
import type { NextRequest } from "next/server";

export default withAuth;

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

Note: If you have an existing project using middleware.ts, it continues to work in Next.js 16 for Edge runtime use cases. But for new projects, proxy.ts is the correct file. The withAuth import path and usage are identical between the two.

Any unauthenticated user who tries to reach a matched route is automatically redirected to Kinde's login page. Once they authenticate, Kinde redirects them back to the page they originally requested.

Step #6: Define Roles and Permissions in Kinde

Before writing any permission-checking code, set up your roles and permissions in the Kinde dashboard.

Navigate to Roles & Permissions → Permissions → Add permission. Create each permission with a resource:action naming convention:

For this tutorial, create these permissions:

Key	Description
`posts:create`	Create new posts
`posts:update`	Edit existing posts
`posts:delete`	Delete posts permanently
`posts:publish`	Publish or unpublish posts
`users:view`	View the user list
`users:manage`	Edit user details and roles

Now navigate to Roles & Permissions → Roles → Add role and create three roles:

Assign permissions to each role:

Permission	Admin	Editor
`posts:create`	✓	✓
`posts:update`	✓	✓
`posts:delete`	✓
`posts:publish`	✓	✓
`users:view`	✓
`users:manage`	✓

Assign a role to your own user for testing. Navigate to Users → select your user → Roles → assign admin. You will test the other roles by reassigning later.

Terrific! The permission model is ready. Time to use it in code.

Step #7: Check Permissions in Server Components

getKindeServerSession() is the main SDK helper for checking authentication state and accessing user data in Server Components. It reads directly from the server-side session — no network request, no database query.

Create a protected dashboard page at app/dashboard/page.tsx:

// app/dashboard/page.tsx
import { getKindeServerSession } from "@kinde-oss/kinde-auth-nextjs/server";
import { redirect } from "next/navigation";
import { PermissionGate } from "@/components/PermissionGate";

export default async function DashboardPage() {
  const { isAuthenticated, getUser } = getKindeServerSession();

  if (!(await isAuthenticated())) redirect("/api/auth/login");

  const user = await getUser();

  return (
    <main className="p-8">
      <h1 className="text-2xl font-bold mb-1">Dashboard</h1>
      <p className="text-gray-500 mb-8">
        Welcome back, {user?.given_name ?? "User"}
      </p>

      <div className="grid grid-cols-1 gap-4 md:grid-cols-3">
        {/* Visible to all authenticated users */}
        <div className="rounded-lg border p-6">
          <h2 className="font-semibold mb-2">Posts</h2>
          <p className="text-sm text-gray-500 mb-4">Manage your content</p>
          <PermissionGate permission="posts:create">
            <a
              href="/dashboard/posts/new"
              className="text-sm font-medium text-blue-600 hover:underline"
            >
              + New post
            </a>
          </PermissionGate>
        </div>

        {/* Only users with users:manage see this card */}
        <PermissionGate permission="users:manage">
          <div className="rounded-lg border p-6 bg-amber-50">
            <h2 className="font-semibold mb-2">Users</h2>
            <p className="text-sm text-gray-500 mb-4">
              Manage team members and access
            </p>
            <a
              href="/admin/users"
              className="text-sm font-medium text-amber-700 hover:underline"
            >
              View all users
            </a>
          </div>
        </PermissionGate>

        {/* Only users with posts:delete see this card */}
        <PermissionGate permission="posts:delete">
          <div className="rounded-lg border border-red-200 p-6 bg-red-50">
            <h2 className="font-semibold text-red-800 mb-2">
              Content Management
            </h2>
            <p className="text-sm text-red-600 mb-4">
              Delete and bulk-manage content
            </p>
            <a
              href="/admin/content"
              className="text-sm font-medium text-red-700 hover:underline"
            >
              Manage content
            </a>
          </div>
        </PermissionGate>
      </div>
    </main>
  );
}

Note: The isGranted property is what you check — not just whether canCreatePosts is truthy. getPermission() always returns an object; isGranted is false when the user does not have the permission rather than returning null. This makes the check explicit and safe.

Step #8: Enforce Permissions in Route Handlers

Client-side permission checks are for UX — they hide controls that would fail. Server-side checks in API routes are the real security gate. You need both.

Create a protected API route at app/api/protected/posts/route.ts:

// app/api/protected/posts/route.ts
import { getKindeServerSession } from "@kinde-oss/kinde-auth-nextjs/server";
import { NextRequest, NextResponse } from "next/server";

export async function POST(request: NextRequest) {
  const { isAuthenticated, getPermission, getUser } =
    getKindeServerSession();

  // Step 1: Check authentication
  if (!(await isAuthenticated())) {
    return NextResponse.json(
      { error: "Unauthenticated. Please sign in." },
      { status: 401 }
    );
  }

  // Step 2: Check the specific permission required for this action
  const canCreatePosts = await getPermission("posts:create");

  if (!canCreatePosts?.isGranted) {
    return NextResponse.json(
      {
        error: "Forbidden",
        message: "You do not have permission to create posts.",
      },
      { status: 403 }
    );
  }

  // Step 3: Parse the request
  const body = await request.json();
  const { title, content } = body;

  if (!title || !content) {
    return NextResponse.json(
      { error: "Title and content are required." },
      { status: 400 }
    );
  }

  // Step 4: Execute the action — safe to proceed
  const user = await getUser();

  // Replace this with your actual database logic
  const post = {
    id: crypto.randomUUID(),
    title,
    content,
    authorId: user?.id,
    createdAt: new Date().toISOString(),
  };

  return NextResponse.json({ post }, { status: 201 });
}

export async function DELETE(request: NextRequest) {
  const { isAuthenticated, getPermission } = getKindeServerSession();

  if (!(await isAuthenticated())) {
    return NextResponse.json(
      { error: "Unauthenticated." },
      { status: 401 }
    );
  }

  // Delete requires a more privileged permission than create
  const canDeletePosts = await getPermission("posts:delete");

  if (!canDeletePosts?.isGranted) {
    return NextResponse.json(
      {
        error: "Forbidden",
        message: "You do not have permission to delete posts.",
      },
      { status: 403 }
    );
  }

  const { searchParams } = new URL(request.url);
  const postId = searchParams.get("id");

  if (!postId) {
    return NextResponse.json(
      { error: "Post ID is required." },
      { status: 400 }
    );
  }

  // Your delete logic here
  return NextResponse.json({ deleted: true, postId });
}

Step #9: Build a Reusable Permission Guard Component

Checking permissions inline in every component gets repetitive. A PermissionGate component keeps the pattern clean and consistent:

// components/PermissionGate.tsx
import { getKindeServerSession } from "@kinde-oss/kinde-auth-nextjs/server";

interface PermissionGateProps {
  permission: string;
  children: React.ReactNode;
  // Optional: what to show if the user lacks the permission
  fallback?: React.ReactNode;
}

export async function PermissionGate({
  permission,
  children,
  fallback = null,
}: PermissionGateProps) {
  const { getPermission } = getKindeServerSession();
  const result = await getPermission(permission);

  if (!result?.isGranted) {
    return <>{fallback}</>;
  }

  return <>{children}</>;
}

Now any Server Component in your app can use it cleanly:

// app/dashboard/posts/page.tsx
import { getKindeServerSession } from "@kinde-oss/kinde-auth-nextjs/server";
import { redirect } from "next/navigation";
import { PermissionGate } from "@/components/PermissionGate";

export default async function PostsPage() {
  const { isAuthenticated } = getKindeServerSession();

  if (!(await isAuthenticated())) {
    redirect("/api/auth/login");
  }

  return (
    <main className="p-8">
      <div className="flex items-center justify-between mb-8">
        <h1 className="text-2xl font-bold">Posts</h1>

        {/* Only users with posts:create see this button */}
        <PermissionGate permission="posts:create">
          <a
            href="/dashboard/posts/new"
            className="rounded-md bg-blue-600 px-4 py-2 text-sm font-medium text-white hover:bg-blue-700"
          >
            New post
          </a>
        </PermissionGate>
      </div>

      {/* Post list visible to everyone */}
      <PostList />

      {/* Bulk delete only for users with posts:delete */}
      <PermissionGate
        permission="posts:delete"
        fallback={
          <p className="mt-8 text-sm text-gray-400">
            You have view-only access to this section.
          </p>
        }
      >
        <BulkDeleteControls />
      </PermissionGate>
    </main>
  );
}

// Placeholder components — replace with your real implementations
function PostList() {
  return <div className="space-y-4">{/* Post items */}</div>;
}

function BulkDeleteControls() {
  return (
    <div className="mt-8 rounded-lg border border-red-200 p-4">
      <p className="text-sm font-medium text-red-700">Bulk actions</p>
    </div>
  );
}

Wonderful! PermissionGate works as a clean wrapper everywhere. No repeated getPermission calls spread across components — just one consistent primitive.

Step #10: Add Sign In and Sign Out

With protection and permissions in place, add the authentication links. Kinde provides LoginLink, RegisterLink, and LogoutLink components that generate the correct Kinde auth URLs:

// app/page.tsx
import {
  LoginLink,
  RegisterLink,
} from "@kinde-oss/kinde-auth-nextjs/components";
import { getKindeServerSession } from "@kinde-oss/kinde-auth-nextjs/server";
import { redirect } from "next/navigation";

export default async function Home() {
  const { isAuthenticated } = getKindeServerSession();

  // If already authenticated, send to dashboard
  if (await isAuthenticated()) {
    redirect("/dashboard");
  }

  return (
    <main className="flex min-h-screen flex-col items-center justify-center p-24">
      <h1 className="text-4xl font-bold mb-4">My RBAC App</h1>
      <p className="text-gray-500 mb-8 text-center max-w-md">
        Sign in to access your dashboard. Your permissions are
        automatically loaded from your role.
      </p>
      <div className="flex gap-4">
        <LoginLink className="rounded-md bg-blue-600 px-6 py-2 text-sm font-medium text-white hover:bg-blue-700">
          Sign in
        </LoginLink>
        <RegisterLink className="rounded-md border border-gray-300 px-6 py-2 text-sm font-medium hover:bg-gray-50">
          Create account
        </RegisterLink>
      </div>
    </main>
  );
}

For sign out, create a simple server action or use the LogoutLink component anywhere in your authenticated layout:

// app/dashboard/layout.tsx
import { LogoutLink } from "@kinde-oss/kinde-auth-nextjs/components";
import { getKindeServerSession } from "@kinde-oss/kinde-auth-nextjs/server";
import { redirect } from "next/navigation";

export default async function DashboardLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  const { isAuthenticated, getUser, getRoles } = getKindeServerSession();

  if (!(await isAuthenticated())) {
    redirect("/api/auth/login");
  }

  const user = await getUser();
  const roles = await getRoles();

  // Show the first role for display purposes
  // Your app might show this differently
  const displayRole = roles?.[0]?.name ?? "User";

  return (
    <div className="min-h-screen bg-gray-50">
      {/* Navigation bar */}
      <nav className="border-b bg-white px-6 py-4">
        <div className="flex items-center justify-between">
          <span className="font-semibold">My RBAC App</span>
          <div className="flex items-center gap-4">
            <span className="text-sm text-gray-600">
              {user?.email}
            </span>
            {/* Role badge — for display only, never for access control */}
            <span className="rounded-full bg-blue-100 px-3 py-1 text-xs font-medium text-blue-800">
              {displayRole}
            </span>
            <LogoutLink className="text-sm text-gray-600 hover:text-gray-900">
              Sign out
            </LogoutLink>
          </div>
        </div>
      </nav>
      <main>{children}</main>
    </div>
  );
}

Note: The role badge in the nav is display-only. It tells the user what their role is, which is good UX. But your access decisions in code never read this display value — they always call getPermission("permission:key").

Putting It All Together

Here is the complete file structure for the RBAC setup you have just built:

my-rbac-app/
├── app/
│   ├── api/
│   │   └── auth/
│   │       └── [kindeAuth]/
│   │           └── route.ts       ← Kinde auth handler
│   │   └── protected/
│   │       └── posts/
│   │           └── route.ts       ← Permission-checked API route
│   ├── dashboard/
│   │   ├── layout.tsx             ← Nav with user/role display
│   │   ├── page.tsx               ← Permission-based UI
│   │   └── posts/
│   │       └── page.tsx           ← Uses PermissionGate
│   ├── admin/
│   │   └── users/
│   │       └── page.tsx           ← Admin-only page
│   ├── layout.tsx                 ← KindeProvider wrapper
│   └── page.tsx                   ← Login / register landing
├── components/
│   └── PermissionGate.tsx         ← Reusable permission guard
├── proxy.ts                       ← Next.js 16 route protection
└── .env.local                     ← Kinde credentials

The flow for every protected request:

Step 1: proxy.ts intercepts the request. If the route matches the matcher and the user is unauthenticated, Kinde redirects to login. Authenticated users pass through.

Step 2: The Server Component or Route Handler calls getKindeServerSession() and reads permissions from the token. No database query.

Step 3: getPermission("permission:key") returns { isGranted: boolean }. If false, the component renders the fallback or the route handler returns 403.

Step 4: The user sees exactly what their role allows them to see. The role definition lives in Kinde — change a role's permissions in the dashboard and every user with that role sees the updated access on their next session.

A Note on `use cache` in Next.js 16

Next.js 16 introduces use cache as a new opt-in caching primitive. You can add it to pages, components, and functions to cache their output.

Do not add use cache to any page or component that renders based on the authenticated user's permissions. Cached outputs are stored and reused across requests — if you cache a dashboard page that shows admin controls for one user, the next user to hit that route may see the cached admin UI regardless of their actual permissions.

Keep permission-checked components and pages entirely outside use cache boundaries. If you need to cache parts of a permission-protected page, use React's Suspense to split the cacheable sections from the permission-gated sections:

// ✓ Correct: cache the public section, NOT the permission-gated section
export default async function PostsPage() {
  const { isAuthenticated } = getKindeServerSession();
  if (!(await isAuthenticated())) redirect("/api/auth/login");

  return (
    <main>
      {/* This section is the same for all authenticated users — safe to cache */}
      <Suspense fallback={<p>Loading posts...</p>}>
        <PublicPostList />   {/* Has "use cache" inside */}
      </Suspense>

      {/* This section is specific to the user's permissions — never cache */}
      <PermissionGate permission="posts:delete">
        <BulkDeleteControls />
      </PermissionGate>
    </main>
  );
}

Testing Your RBAC Implementation

Verify your setup by testing these scenarios:

Test 1 — Unauthenticated access. Open an incognito window and navigate to /dashboard. You should be redirected to the Kinde login page.

Test 2 — Role-based UI. Log in as your admin user. Confirm the Users card and bulk delete controls are visible. Navigate to Users in Kinde, change your role to editor, and refresh. The Users card and delete controls should disappear.

Test 3 — API enforcement. Using a REST client like Postman or curl, send a DELETE request to /api/protected/posts?id=123 without an authenticated session. You should receive a 401. Log in with an editor-role user and try again — you should receive a 403, because editors have posts:create and posts:update but not posts:delete.

Test 4 — Permission updates. In Kinde, add the users:view permission to the editor role. Refresh the page while logged in as an editor — the Users section should now appear, with no code change on your part.

Conclusion

In this article, you built a complete RBAC system for a Next.js 16.2 application using Kinde. You used proxy.ts — the new Next.js 16 network boundary file — for route protection, getKindeServerSession() for server-side permission reads, getPermission() for granular access checks, and a reusable PermissionGate component for clean conditional rendering.

The most important thing you built is not the code — it is the separation. Roles and permissions live in Kinde. Code checks permissions. The two halves are cleanly decoupled. When your product evolves and you need to add a new role or change what an editor can do, you change a configuration in the Kinde dashboard. Your Next.js application does not need to be redeployed.

Kinde is free for up to 10,500 monthly active users, no credit card required. Get started at kinde.com.

How to Scope Permissions Per Tenant in a Multi-Tenant App

Shola Jegede — Sun, 22 Mar 2026 00:42:57 +0000

The same user, Sarah, is an admin at Acme Corp and a read-only viewer at Startup Inc. She should see completely different things in the same product depending on which tenant she is operating in. Here is how to build that correctly.

In this article, you will learn:

What "per-tenant permissions" actually means and why it is different from global RBAC
How Kinde models multi-tenancy with organizations, and how tenant context flows into every token
How to define roles and permissions in Kinde that scope per organization
How to read tenant-scoped permissions from the Kinde token in a Next.js API route
How to build a reusable permission guard that you can drop into any route
How to gate UI components in React based on the current tenant's permissions
How to isolate data at the database query level using the org code from the token
How to handle the user-switching-tenants scenario correctly
The two most common multi-tenant permission bugs and how to avoid them

Let's dive in!

The Problem With Global Permissions

Most developers reach for a simple RBAC model first: define some roles globally, assign users to roles, check roles in your code. Admin can do everything, member can do some things, viewer can only read.

This works fine for single-tenant apps. It falls apart the moment one user belongs to more than one tenant.

Consider Sarah. She joined Acme Corp as an admin — she manages billing, invites colleagues, and deletes stale projects. She was also invited to Startup Inc as an outside consultant — read-only access, she can view reports but touch nothing.

In a global RBAC model, you cannot express this. Sarah has one set of roles in your system. If she is an admin, she is an admin everywhere. If you restrict her globally to viewer, she loses the ability to manage Acme Corp.

The correct model is tenant-scoped permissions: Sarah's role and permissions are defined per organization. When she logs into Acme Corp, her token says admin with full permissions. When she logs into Startup Inc, the same user's token says viewer with read-only permissions. Same user identity, completely different permission set, determined by which tenant context she authenticated into.

This is exactly how Kinde handles multi-tenancy, and it is the right mental model for any B2B SaaS product.

How Kinde Models This

In Kinde, every customer of your SaaS product is an organization. Acme Corp is one org. Startup Inc is another. Each has its own isolated context — its own members, its own roles assigned to those members, its own feature flags, and optionally its own auth settings.

When a user logs in, they authenticate within an organization context. Kinde issues a JWT access token that includes the org_code — the unique identifier for the tenant they are currently operating in. Every permission, every role, every feature flag in that token is scoped to that specific organization.

The token for Sarah logged into Acme Corp looks like this:

{
  "sub": "kp_123abc",
  "email": "sarah@example.com",
  "org_code": "org_acme_corp",
  "roles": [
    { "id": "rol_001", "key": "admin", "name": "Admin" }
  ],
  "permissions": [
    "projects:create",
    "projects:read",
    "projects:delete",
    "billing:manage",
    "members:invite"
  ],
  "iss": "https://yourapp.kinde.com",
  "exp": 1740000000
}

The same Sarah logged into Startup Inc gets a new token:

{
  "sub": "kp_123abc",
  "email": "sarah@example.com",
  "org_code": "org_startup_inc",
  "roles": [
    { "id": "rol_003", "key": "viewer", "name": "Viewer" }
  ],
  "permissions": [
    "projects:read",
    "reports:read"
  ],
  "iss": "https://yourapp.kinde.com",
  "exp": 1740000000
}

Same sub. Different org_code, roles, and permissions. Your application reads these claims and enforces them. Kinde's job is to put the right claims into each token based on what role the user holds in each specific org.

Step #1: Define Roles and Permissions in Kinde

Before writing a single line of application code, configure the roles and permissions that express your access model in the Kinde dashboard.

Defining permissions

Navigate to Roles & Permissions → Permissions → Add permission.

Create one permission per discrete action in your product. The resource:action naming pattern keeps permissions readable as your product grows:

Permission key	Description
`projects:create`	Create new projects
`projects:read`	View projects and details
`projects:delete`	Permanently delete projects
`members:invite`	Invite new members to the organization
`members:remove`	Remove members from the organization
`billing:manage`	Manage subscription and billing
`reports:read`	View analytics and reports
`reports:export`	Export report data

Note: Permission keys must be defined centrally in Kinde before they can appear in any token. A permission that is not defined will never show up in the permissions array, regardless of what roles you assign.

Defining roles

Navigate to Roles & Permissions → Roles → Add role.

For the project management example, three roles cover most B2B SaaS access models:

Admin: projects:create, projects:read, projects:delete, members:invite, members:remove, billing:manage, reports:read, reports:export

Member: projects:create, projects:read, reports:read

Viewer: projects:read, reports:read

These role-to-permission mappings are what Kinde resolves when building the permissions array in the user's token. Assign a user the admin role within a specific org, and every permission attached to that role flows into their token for that org.

Assigning roles per organization

When a user joins an organization, they are assigned a role for that organization specifically. Navigate to an organization in Kinde → Members → select a member → assign their role.

This is the per-tenant scoping in action. Sarah's role in this specific organization is Viewer. Navigate to a different organization, find Sarah there, and she might have a completely different role assignment.

Terrific! Kinde is configured. Time to use these permissions in the application.

Step #2: Read Tenant-Scoped Permissions in a Next.js API Route

With the Kinde Next.js SDK installed and configured, reading tenant-scoped permissions server-side requires one import.

// app/api/projects/route.ts
import { getKindeServerSession } from "@kinde-oss/kinde-auth-nextjs/server";
import { NextResponse } from "next/server";

export async function GET() {
  const { isAuthenticated, getOrganization, getPermissions } =
    getKindeServerSession();

  // Step 1: Confirm the user is authenticated
  if (!(await isAuthenticated())) {
    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
  }

  // Step 2: Get the current tenant context from the token
  // org_code is the tenant identifier — comes from the signed JWT, not the request
  const org = await getOrganization();
  if (!org?.orgCode) {
    return NextResponse.json(
      { error: "No organization context" },
      { status: 403 }
    );
  }

  // Step 3: Get this user's permissions for this specific org
  // getPermissions() returns { permissions: string[], orgCode: string }
  const { permissions, orgCode } = await getPermissions();

  // Step 4: Check the required permission
  if (!permissions.includes("projects:read")) {
    return NextResponse.json(
      { error: "You do not have permission to view projects" },
      { status: 403 }
    );
  }

  // Step 5: Fetch data scoped to this tenant
  // ALWAYS use org.orgCode from the token — never a client-supplied tenant ID
  const projects = await db.projects.findMany({
    where: { orgCode: org.orgCode },
  });

  return NextResponse.json({ projects });
}

Two things to pay attention to here.

getPermissions() returns both the permissions array and the orgCode — confirming which org these permissions apply to. This is useful for logging and debugging: if a permission check fails unexpectedly, you can verify the org context is what you expected.

The database query filters by org.orgCode from the token, not a tenant ID from the request body or query string. The org code in the JWT is cryptographically signed — a client-supplied value is not. This is the fundamental data isolation guarantee of the multi-tenant model.

Step #3: Build a Reusable Permission Guard

Repeating the same auth and permission check logic in every route is tedious and error-prone. Extract it into a single reusable guard function.

// lib/permissions.ts
import { getKindeServerSession } from "@kinde-oss/kinde-auth-nextjs/server";
import { NextResponse } from "next/server";

// Enumerate all permissions in one place — catches typos at compile time
type Permission =
  | "projects:create"
  | "projects:read"
  | "projects:delete"
  | "members:invite"
  | "members:remove"
  | "billing:manage"
  | "reports:read"
  | "reports:export";

// What a successful auth context looks like
interface AuthContext {
  userId: string;
  orgCode: string;
  permissions: Permission[];
}

/**
 * Checks authentication, org context, and required permissions.
 * Returns AuthContext on success, NextResponse error on failure.
 *
 * Usage:
 *   const auth = await requirePermission("projects:read");
 *   if (auth instanceof NextResponse) return auth;
 *   // auth.orgCode and auth.permissions are now available
 */
export async function requirePermission(
  ...required: Permission[]
): Promise<AuthContext | NextResponse> {
  const { isAuthenticated, getOrganization, getPermissions, getUser } =
    getKindeServerSession();

  if (!(await isAuthenticated())) {
    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
  }

  const [user, org, { permissions }] = await Promise.all([
    getUser(),
    getOrganization(),
    getPermissions(),
  ]);

  if (!org?.orgCode) {
    return NextResponse.json(
      { error: "No organization context — authenticate within an organization" },
      { status: 403 }
    );
  }

  const hasPermission = required.some((perm) =>
    (permissions as string[]).includes(perm)
  );

  if (!hasPermission) {
    return NextResponse.json(
      {
        error: "Insufficient permissions",
        required,
        granted: permissions,
      },
      { status: 403 }
    );
  }

  return {
    userId: user?.id ?? "",
    orgCode: org.orgCode,
    permissions: permissions as Permission[],
  };
}

Every protected API route now becomes a clean two-step: check permissions, run logic.

// app/api/projects/route.ts
import { requirePermission } from "@/lib/permissions";
import { NextResponse } from "next/server";

// GET — requires projects:read
export async function GET() {
  const auth = await requirePermission("projects:read");
  if (auth instanceof NextResponse) return auth;

  const projects = await db.projects.findMany({
    where: { orgCode: auth.orgCode }, // tenant-scoped
  });

  return NextResponse.json({ projects });
}

// POST — requires projects:create
export async function POST(request: Request) {
  const auth = await requirePermission("projects:create");
  if (auth instanceof NextResponse) return auth;

  const body = await request.json();

  const project = await db.projects.create({
    data: {
      ...body,
      orgCode: auth.orgCode, // stamp the tenant from the token
      createdBy: auth.userId,
    },
  });

  return NextResponse.json({ project }, { status: 201 });
}

// DELETE — requires projects:delete
export async function DELETE(
  _request: Request,
  { params }: { params: { id: string } }
) {
  const auth = await requirePermission("projects:delete");
  if (auth instanceof NextResponse) return auth;

  // orgCode in the where clause prevents cross-tenant deletion
  // Even if a wrong ID is passed, this query will not find it
  // unless it belongs to the current user's tenant
  await db.projects.delete({
    where: {
      id: params.id,
      orgCode: auth.orgCode,
    },
  });

  return NextResponse.json({ deleted: true });
}

The orgCode filter on every write and delete is the data isolation layer. It is the database-level defense that ensures even a logic bug cannot cause cross-tenant data leakage.

Amazing!

Step #4: Gate UI Components by Permission

The API layer is the security boundary — it rejects unauthorized requests. The UI layer is the experience boundary — it hides controls the user cannot use, preventing confusion without exposing a wall of 403 errors.

Create a client-side permission hook:

// hooks/usePermissions.ts
"use client";

import { useKindeBrowserClient } from "@kinde-oss/kinde-auth-nextjs";

type Permission =
  | "projects:create"
  | "projects:read"
  | "projects:delete"
  | "members:invite"
  | "members:remove"
  | "billing:manage"
  | "reports:read"
  | "reports:export";

export function usePermissions() {
  const { getPermission, getOrganization } = useKindeBrowserClient();

  // getPermission returns { isGranted: boolean, orgCode: string }
  // isGranted is org-scoped — it reflects permissions for the current org context
  const can = (permission: Permission): boolean =>
    getPermission(permission)?.isGranted ?? false;

  const org = getOrganization();

  return {
    can,
    orgCode: org?.orgCode ?? null,
    orgName: org?.name ?? null,
  };
}

Use the hook in your components for conditional rendering:

// components/ProjectCard.tsx
"use client";

import { usePermissions } from "@/hooks/usePermissions";

export function ProjectCard({ project }: { project: Project }) {
  const { can } = usePermissions();

  return (
    <div className="project-card">
      <h3>{project.name}</h3>

      <div className="project-actions">
        {/* Members and admins can edit */}
        {can("projects:create") && (
          <button onClick={() => editProject(project.id)}>Edit</button>
        )}

        {/* Only admins can delete — not rendered at all for members/viewers */}
        {can("projects:delete") && (
          <button
            onClick={() => deleteProject(project.id)}
            className="destructive"
          >
            Delete
          </button>
        )}
      </div>
    </div>
  );
}

// components/Sidebar.tsx
"use client";

import { usePermissions } from "@/hooks/usePermissions";
import Link from "next/link";

export function Sidebar() {
  const { can, orgName } = usePermissions();

  return (
    <nav className="sidebar">
      {/* Show current org context at the top */}
      {orgName && <div className="workspace-name">{orgName}</div>}

      {/* Always visible to authenticated org members */}
      <Link href="/projects">Projects</Link>

      {/* Only visible if user has reports:read */}
      {can("reports:read") && <Link href="/reports">Reports</Link>}

      {/* Only visible if user can invite members (admin) */}
      {can("members:invite") && <Link href="/members">Team Members</Link>}

      {/* Only visible if user can manage billing (admin) */}
      {can("billing:manage") && (
        <Link href="/settings/billing">Billing</Link>
      )}
    </nav>
  );
}

The same component file produces three completely different outputs
depending on who is logged in:

Note: Conditional rendering hides controls but does not enforce access. A user can still call API routes directly with tools like curl. The requirePermission guard in the API layer is what enforces authorization — the UI gate is for experience, not security.

Step #5: Handle Tenant Switching Correctly

When Sarah switches from Acme Corp to Startup Inc, she needs a new token scoped to the new organization. The existing token's org_code is org_acme_corp — you cannot change a signed JWT's claims without issuing a new one.

The correct approach is to redirect the user through Kinde's authentication with the target org specified:

// components/OrgSwitcher.tsx
"use client";

import { useKindeBrowserClient } from "@kinde-oss/kinde-auth-nextjs";
import { LoginLink } from "@kinde-oss/kinde-auth-nextjs/components";

interface Org {
  code: string;
  name: string;
}

export function OrgSwitcher({ orgs }: { orgs: Org[] }) {
  const { getOrganization } = useKindeBrowserClient();
  const currentOrg = getOrganization();

  return (
    <div className="org-switcher">
      {orgs.map((org) =>
        org.code === currentOrg?.orgCode ? (
          // Already in this org — highlight it as current
          <div key={org.code} className="org-item current">
            {org.name} <span className="badge">Current</span>
          </div>
        ) : (
          // Switch to this org — triggers a new Kinde token for org.code
          <LoginLink
            key={org.code}
            authUrlParams={{ org_code: org.code }}
            className="org-item"
          >
            {org.name}
          </LoginLink>
        )
      )}
    </div>
  );
}

The org_code parameter in authUrlParams tells Kinde which organization to issue the token for. After the brief authentication redirect, the user's token contains the org_code, roles, and permissions for the switched-to org. Every permission check in both the API and the UI immediately reflects the new tenant context.

Putting It All Together

Here is the complete per-tenant permission system mapped across all layers:

Layer	What it does	Where it lives
Kinde (config)	Defines permissions globally, bundles them into roles, assigns roles per org	Kinde dashboard
JWT token	Carries `org_code` + `permissions` for the current org context	Issued by Kinde, verified by SDK
`requirePermission()` (API)	Rejects requests missing auth, org context, or required permissions	`lib/permissions.ts`
DB queries	Filter every read/write/delete by `auth.orgCode` from the token	All API route handlers
`usePermissions()` hook (UI)	Conditionally renders controls based on `getPermission(key).isGranted`	React components
`OrgSwitcher` (UI)	Issues a new token for the selected org via `LoginLink` + `org_code`	`OrgSwitcher` component

The Two Most Common Multi-Tenant Permission Bugs

Bug #1: Trusting the client-supplied tenant ID

// ❌ Wrong — org code from the request body is attacker-controlled
export async function GET(request: Request) {
  const { orgCode } = await request.json();
  const projects = await db.projects.findMany({
    where: { orgCode }, // a user can pass any org's code here
  });
}

// ✅ Correct — org code from the signed JWT cannot be forged
export async function GET() {
  const auth = await requirePermission("projects:read");
  if (auth instanceof NextResponse) return auth;
  const projects = await db.projects.findMany({
    where: { orgCode: auth.orgCode },
  });
}

A user controls what goes in a request body. They cannot forge a claim in a signed JWT. Always read the tenant context from the token.

Bug #2: Checking role names instead of permissions

// ❌ Wrong — brittle, breaks when roles are renamed or restructured
const roles = await getRoles();
const isAdmin = roles?.some(r => r.key === "admin");
if (!isAdmin) return forbidden();

// ✅ Correct — checks the specific action, decoupled from role names
const auth = await requirePermission("projects:delete");
if (auth instanceof NextResponse) return auth;

Role names can change. New roles can be created. A "super_admin" or "owner" role might need delete access too. When you check role names, you have to update every check site when your role structure evolves. When you check permissions, the mapping from roles to permissions is managed in Kinde's configuration and your code stays unchanged.

Conclusion

In this article, you built a complete per-tenant permission system for a multi-tenant Next.js app using Kinde organizations. The same user now has completely different permissions depending on which org they are operating in — because those permissions come from the org-scoped token claims, not from a global role attached to the user.

The model is clear: Kinde puts the right claims in the token for each org context (trust layer). Your API guard enforces permissions before any logic runs (security layer). Your UI hook hides controls the user cannot use (experience layer). Your database queries filter by the org code from the token (isolation layer).

Four layers, one source of truth: the token.

Kinde is free for up to 10,500 monthly active users, no credit card required. Create your account at kinde.com and have multi-tenant permissions running today.

Your Free Trial Isn't Converting Because Your Upgrade Flow Has Too Much Friction

Shola Jegede — Sun, 22 Mar 2026 00:27:29 +0000

A technical founder asked me why only 8% of their trial users were upgrading. We spent an hour going through their funnel. The product was good. The problem was everything around it.

In this article, you will learn:

Why most free trial conversion problems are not actually product problems
What the data says about where trial users actually drop off
The five friction points that kill conversion — and which ones founders keep building themselves
Why auth and upgrade flows are the worst place to build from scratch
How Kinde handles the login, onboarding, upgrade, and access layers so you do not have to
What your team should be spending its friction-reduction energy on instead
How to audit your own funnel in 30 minutes and find the leaks

Let's dive in!

The Conversation That Prompted This Article

A technical founder — building a SaaS tool for operations teams — reached out with a familiar problem. Their trial-to-paid conversion was hovering around 8%. They had good traffic, decent trial signups, and they knew from user interviews that people liked the product. But when the trial ended, most users just did not upgrade.

They had already done the obvious things. They had shortened the trial from 30 days to 14. They had added in-app upgrade prompts. They had set up reminder emails. The conversion number barely moved.

When we walked through their full funnel together, the product was not the problem. The product did what it promised. But surrounding it was a web of friction that accumulated across every touchpoint — friction that the founding team had built themselves, piece by piece, never stepping back to look at the whole thing from a new user's perspective.

The login flow asked for email, password, first name, last name, company name, and team size before the user saw a single feature. The upgrade page required re-entering credit card information even if the user had already paid for something. The "upgrade to Pro" button existed in exactly one place in the entire product. Inviting a team member required the admin to first create the team member's role, then generate an invite link, then email it externally, then wait for the user to set up their own password. None of these problems were product problems. They were infrastructure problems. And the founding team had built every one of them.

This article is about that category of friction: the stuff around your product that you probably built yourself and never had to build at all.

What the Data Actually Says

Before diagnosing where friction hides, it is worth grounding this in numbers.

Opt-in free trials — the model where users sign up without a credit card — convert to paid at around 18 to 25% on average. Freemium products, where users stay on a free tier indefinitely, convert around 2.6 to 5%. If your product is genuinely solving a real problem and your conversion rate is sitting well below these benchmarks, you almost certainly have a friction problem, not a product problem.

A few statistics that should make every technical founder uncomfortable:

Each additional field in a signup form reduces completion by an average of 5 to 7%. When one company dropped the credit card requirement from their signup, they immediately saw a 71% increase in users willing to start a trial. Removing just three form fields from a payment page lifted conversion by 8%. Users who experience core product value within the first 15 minutes are three times more likely to retain than those who wait 30 minutes or longer. Users who complete an onboarding flow are five times more likely to convert than those who do not.

The pattern is consistent: every second between a user's decision to try your product and the moment they experience its value is a second where they can change their mind. And the irony is that the friction accumulates most heavily in the parts of the product that have nothing to do with what makes your product valuable.

Nobody's aha moment is "I successfully created an account." Nobody upgrades to Pro because "the payment page was really elegant." But a bad login experience, a broken invite flow, or an upgrade page that sends the user off-site and back can absolutely stop a conversion that was about to happen.

The Five Friction Points That Kill Free Trial Conversion

These are the five places where trial conversion typically bleeds out. Two of them are product problems you genuinely need to solve. Three of them are infrastructure problems you should never have had to build.

Friction Point #1: The Signup Wall (Infrastructure)

The most common version of this: a new user lands on your product, decides they want to try it, and is immediately presented with a form. Email. Password. Confirm password. First name. Last name. Company. Team size. Job title. Use case. Newsletter opt-in. Terms checkbox.

This is not onboarding. This is interrogation. And it happens at exactly the wrong moment — before the user has experienced a single second of your product's value.

The right version of signup asks for as little as possible. An email address and a way to verify it is enough. Better yet, a single "Sign in with Google" button is one click. Users who have already experienced your product and then are asked for their email to save their work convert significantly better than users asked to commit before they have seen anything.

This is a pure infrastructure problem. It is not about your product. It is about how you authenticate users. And it is completely solved by not building your own auth system.

Friction Point #2: Email Verification Delay (Infrastructure)

The single most underestimated conversion killer in SaaS. User signs up, checks email, verification email is in spam or takes 90 seconds, user moves on and never comes back.

Email verifications that go to spam folders, that arrive late, or that require the user to leave the product and return to it introduce a break in momentum that most users never recover from. The user was ready to try your product. Now they are checking their spam folder.

The fix is passwordless authentication with email OTPs — users enter their email, get a short code, enter it, and they are in. No password to create, no verification link to chase, no spam filter to defeat. Kinde's default authentication is email + code, not a magic link. A six-digit OTP that the user enters manually. The user stays in the flow the entire time. No tab-switching.

Friction Point #3: The First-Run Empty State (Product)

This is a genuine product problem — and arguably the most important one to solve, because it sits right after the authentication friction that you have just removed.

A new user logs in for the first time and sees a completely blank dashboard. No data, no examples, no clear next action. The product looks empty because it is empty. This is the "blank canvas problem" and it is responsible for an enormous share of early churn.

The fix is not complex: pre-populate the user's account with example data, a sample project, or a guided first action that gets them to their aha moment within the first five minutes. Trello puts users directly into a pre-configured board. Figma opens a default file. Notion creates a sample workspace. None of them leave the user staring at an empty screen wondering what to do.

This is the friction point that is worth spending your engineering team's time on. It is specific to your product's value proposition and cannot be handled by any external tool.

Friction Point #4: The Upgrade Moment (Infrastructure)

This is where the founder I talked to lost most of their conversions. The user has been using the product for a week. They have hit a feature limit or they have decided the product is worth paying for. They look for the upgrade button.

It is not in the navigation. It is not in the settings. It is not in the feature they just hit the limit on. It is on a pricing page linked from the marketing site footer.

Even when users find the upgrade path, the friction continues: they are redirected to a separate page, asked to choose a plan, asked to enter payment details, redirected to a third-party checkout, and then redirected back to the product. At each hop, some percentage of users drop off.

The right upgrade flow is in-context: the upgrade prompt appears exactly where the user hits the limit, the payment is handled without leaving the product, and the new feature is unlocked immediately after payment with zero additional steps required.

This is almost entirely an infrastructure problem. Wiring together your auth system, your plan state, your billing provider, and your feature flags in a way that makes this experience seamless is weeks of engineering work. Or it is a Kinde configuration that takes an afternoon.

Friction Point #5: The Team Invite Friction (Infrastructure and Product)

Many SaaS products live or die on team adoption. A single user converts to paid, but the product is much stickier once teammates are inside it too. This is the expansion motion that drives net revenue retention above 100%.

But the invite flow in most early-stage products is brutal. Admin has to set up roles. Generate an invite link. Copy it. Email it manually. The invitee signs up, creates a password, and waits for an admin to approve. The teammate who signed up on Tuesday shows up in the admin's queue on Thursday. The admin gets an email notification, clicks through, approves, and the new user can finally access the product.

Three days of friction for what should be a one-minute experience.

The right invite flow sends an invitation email with a single link. The invitee clicks the link, authenticates in one step (social login or OTP), and is inside the product with the correct role already assigned. No manual queue. No password creation. No admin approval step for standard roles.

Again: this is infrastructure. The invitation, authentication, role assignment, and access provisioning are not features of your product. They are plumbing that most teams spend weeks building.

The Category of Friction You Should Stop Building

Notice the pattern across friction points #1, #2, #4, and #5. They are all infrastructure. They are all part of the login and access layer. And they are all things that the founding team of the product I described above had built themselves, from scratch, because that seemed like the right call at the time.

It was not the right call. Here is why.

When you build your own auth system, you are making a bet that your implementation of signup flows, email verification, social login, OTP delivery, password reset, session management, multi-tenant org logic, role assignment, invite flows, plan gating, and upgrade checkout will be good enough not to cost you conversions. That bet almost always loses, for a simple reason: none of these things are your product. You are not optimizing them. You are not testing them. You are not studying the best practices the way Stripe studied payment UX or the way Kinde has studied auth UX.

Every hour your team spends debugging email deliverability or adding a Google login button or wiring up a Stripe webhook to update a user's plan state in your database is an hour not spent on friction point #3 — the blank canvas problem, which is the one that is genuinely specific to your product and genuinely worth your team's engineering attention.

What Kinde Gets Right Out of the Box

Kinde is auth, user management, and billing in one platform. The reason this matters for free trial conversion is not because Kinde does those things — it is that Kinde does those things well, so you do not have to.

Here is what you get without writing any infrastructure code:

Passwordless authentication by default. Kinde's default auth method is email + OTP, not a password. Users enter their email and a six-digit code. No password to create, no verification link to follow, no confirmation email that might land in spam. Users stay in your product from the moment they decide to sign up.

Social login out of the box. Google, GitHub, Microsoft, Apple, and others can be enabled in the Kinde dashboard in under two minutes. One-click signup removes all the form-field friction from new user acquisition. Users who already have a Google account can be inside your product in a single click.

No credit card required for Kinde itself. Kinde's free plan supports up to 10,500 monthly active users — no credit card required to get started. This is important because it means you can mirror the same no-credit-card opt-in model for your own users that the data shows converts best, without paying anything for the auth infrastructure that enables it.

Upgrade flows that stay in-product. Kinde's billing integration puts the pricing table, plan selection, and Stripe checkout inside your product. When a user hits a feature limit and sees an upgrade prompt, they complete the upgrade without leaving the product. The new plan is active immediately. Feature flags tied to that plan update in the same request.

Feature flags tied to plan state. The moment a user upgrades, the feature flags attached to that plan activate without any webhook handling or database updates from your team. The user does not have to log out and back in. The feature is simply available. This is what makes in-context upgrade prompts work: "You've hit the limit on the free plan. Upgrade to Pro to unlock this." The user clicks, pays, and the feature unlocks in that same session.

Organization-based team management. For B2B products, Kinde organizations give every customer their own isolated workspace, with their own members, roles, and plan state. The invite flow sends a Kinde-powered email with a join link. The invitee authenticates (social login or OTP), and their role in the organization is already assigned. No admin queue, no password creation ceremony, no manual step for the inviting user after they send the invitation.

Roles and permissions that express in your product's UI. Using getPermissions() or feature flag checks from the Kinde SDK, your product can conditionally show or hide features based on a user's role and plan state. An admin on the Pro plan sees everything. A member on the free plan sees what they should see. This all comes from the Kinde token — no database query required to determine what a user can see.

Applying This to Your Own Funnel

The founder I described at the start ended up migrating to Kinde and rebuilding their auth and upgrade layer on top of it. The signup form went from six fields to one. Social login accounted for 60% of new signups within the first two weeks. The upgrade flow moved inside the product. The invite flow dropped from a five-step manual process to a single email.

Their trial-to-paid conversion went from 8% to 21% over the following 90 days.

That is not a product change. The product did not change. The friction around the product changed.

If you want to audit your own funnel, here is a 30-minute process:

Step 1 (5 min): Walk the signup flow yourself. Open an incognito window and sign up for your own product. Count every field, every click, every page navigation, every email you have to check. Every step is potential churn.

Step 2 (5 min): Measure time to first value. From the moment you complete signup to the moment you see something genuinely useful in the product — how long does that take? If it is more than five minutes, you have a problem.

Step 3 (5 min): Find the upgrade path. Without knowing where it is, try to find the upgrade button. Time yourself. If it takes more than 30 seconds, most users will not find it at the moment they are ready to pay.

Step 4 (5 min): Walk the invite flow. Go through the process of inviting a team member. Count every step the inviting user has to take. Then count every step the invited user has to take. Multiply both by the cognitive overhead of switching contexts and waiting for emails. That is your expansion friction.

Step 5 (10 min): Look at your drop-off data. Where in the funnel are users leaving? If the biggest drop is between signup and first meaningful action, you have an onboarding problem. If the biggest drop is at the end of the trial, you likely have an upgrade friction problem. If users activate but do not invite teammates, you have an expansion friction problem.

The Division of Labor That Works

The founders who convert at 20%+ typically have an implicit understanding of this division:

Kinde's job: Handle every interaction a user has with authentication, access, plan state, and team membership. Make these interactions fast, polished, and invisible. No friction that the user notices, no engineering hours that the team notices.

Your team's job: Handle every interaction a user has with your actual product. Make the first-run experience genuinely delightful. Get users to their aha moment in under five minutes. Build the features that make people want to upgrade because the product is worth it — not because the upgrade flow tricked them into it.

This is the right division. The user's experience of your auth layer is not a differentiator. Nobody upgrades to Pro because your login page was beautiful. But users will not upgrade at all if the upgrade path is hard to find, the payment flow is clunky, or the new features do not unlock immediately after payment.

Kinde handles the layer that should be invisible and frictionless. Your team handles the layer that should be delightful and differentiated.

Conclusion

In this article, you audited the five friction points that kill free trial conversion, identified which ones are infrastructure problems you should stop building from scratch, and saw how Kinde handles the login, onboarding, upgrade, and team access layers so that your engineering team can focus on what actually makes your product worth paying for.

The founder's 8% conversion rate was not a product failure. It was a resource allocation failure. Every hour spent debugging email verification or building invite flows is an hour taken from the blank canvas problem — the one genuine product problem that only your team can solve.

Free up those hours. Let Kinde handle the plumbing. Spend your engineering attention on the aha moment.

Kinde is free for up to 10,500 monthly active users, no credit card required. Create your account at kinde.com and have authentication running before lunch.

How to Build a Secure MCP Server for AI Agents

Shola Jegede — Sun, 22 Mar 2026 00:15:55 +0000

OpenClaw proved that millions of developers will build with MCP first and think about security second. Here is how to not be that developer.

In this article, you will learn:

What OpenClaw and Moltbook revealed about the state of agentic AI security
Why most MCP servers are architecturally insecure by default
What "tool-level auth" means and why it is the right mental model for MCP security
How Kinde's own MCP server (shipped January 2026) handles scoped access as a real-world reference
How to set up a Kinde M2M application as the authorization layer for your MCP server
How to issue and validate scoped JWT tokens per tool category
How to write a Node.js MCP server that enforces permissions at the tool boundary
How to test that your auth layer actually holds under adversarial conditions

Let's dive in!

OpenClaw, Moltbook, and the Security Wake-Up Call

In late January 2026, two things happened simultaneously that changed how the developer community thinks about agentic AI security.

OpenClaw — an open-source self-hosted AI agent formerly called Clawdbot and briefly Moltbot — crossed 180,000 GitHub stars in a week. It turned any messaging app (WhatsApp, Telegram, Discord, Signal) into an AI agent interface, extended by a Skills system built entirely on MCP servers. Security researchers scanning the internet found over 1,800 exposed OpenClaw instances leaking API keys, chat histories, and account credentials. Cisco's AI security team tested a third-party OpenClaw skill from the ClawHub marketplace and found it performed data exfiltration and prompt injection without user awareness. One of OpenClaw's own maintainers, known as Shadow, warned on Discord that the project was "far too dangerous" for anyone who could not understand command-line basics.

Moltbook — a Reddit-style social network built by Matt Schlicht exclusively for AI agents — launched on January 28 and hit 1.6 million registered agents by February. It was built via vibe coding and contained a misconfigured Supabase database that granted full read and write access to its data — exposing 1.5 million agents belonging to only 17,000 registered humans. Cybersecurity researchers at Vectra AI and PointGuard AI identified Moltbook as a vector for indirect prompt injection: a malicious post on Moltbook could cascade into every MCP tool an agent had access to. Moltbook was acquired by Meta on March 10, 2026.

The pattern that connected both incidents was the same: agents were granted sweeping, unscoped access to tools. No authentication. No per-tool permissions. No way to answer the question "which agent did this and what were they authorized to do?" A static API key — if there was one at all — gave full access to everything.

Security researcher Itamar Golan (founder of Prompt Security, now part of SentinelOne) put it plainly in a VentureBeat interview: treat agents as production infrastructure, not a productivity app — least privilege, scoped tokens, allowlisted actions, strong authentication on every integration, and auditability end-to-end.

This article is about building exactly that.

Why Most MCP Servers Are Architecturally Insecure

The MCP spec (finalized in late 2024, updated through 2025) mandates OAuth 2.1 with PKCE for public remote servers. But the ecosystem reality is starkly different. A 2026 survey of production MCP servers found that 53% rely on static API keys and only 8.5% use OAuth. The rest have no authentication at all.

This is not because developers are careless. It is because the default path is the insecure path. The most commonly copied MCP server examples use static bearer tokens or no auth. The "get something working" version of MCP has no concept of which agent is calling or what it is allowed to do. And when 180,000 developers adopt OpenClaw and start wiring up Skills, they inherit those insecure defaults at scale.

The specific problems with unscoped MCP access are worth naming precisely, because they map directly to what happened with OpenClaw and Moltbook:

No tool-level permissions. A token that grants access to your MCP server grants access to every tool on it. An agent authorized to read files can also delete them. An agent authorized to query a database can also drop tables. There is no granularity.

No agent identity. When five different OpenClaw instances connect to your MCP server, can you tell them apart? Can you see which user delegated authority to each one? With a static API key, the answer is no. All you know is that something with the key made a request.

Prompt injection cascades. Because agents are granted broad tool access, a successful prompt injection attack has a large blast radius. The Moltbook incident demonstrated this: a malicious post in an agent's context could instruct the agent to call tools it had no business calling — and because tools were unscoped, the agent could comply.

No revocation granularity. If you need to cut off one agent's access, you have to rotate the key for everyone.

What you need instead is a model where each agent has a cryptographically verified identity, each token carries specific scopes that enumerate exactly which tools the agent can call, and every tool call is validated against those scopes before execution. That is what Kinde's own MCP server — shipped in January 2026 — demonstrates in production.

The Kinde MCP Server as a Reference Model

Kinde shipped its own MCP server in January 2026. It lets AI assistants like Claude Code connect to your Kinde business and manage users, organizations, roles, and permissions through natural language — things like "create a new organization for Acme Corp" or "list all users with the admin role."

The security model it uses is the right reference for anyone building their own MCP server:

M2M (Machine-to-Machine) applications are the identity primitive for agents. Not user accounts. Not API keys. Dedicated M2M applications that have their own client ID and secret, exist as first-class entities in Kinde, and can be granted or revoked access independently of human users.

Scopes enumerate exact permissions. The Kinde MCP server defines specific scopes for each category of operation — scopes for reading users, different scopes for writing users, separate scopes for managing organizations. An M2M application that has not been granted a scope cannot call the tools that require it. The authorization decision happens at the token issuance level, not at runtime guesswork.

JWT validation on every request. Tokens are short-lived (one hour by default for M2M), signed with Kinde's private key, and verified against Kinde's public JWKS endpoint on every inbound request. A token cannot be forged, replayed beyond its expiry, or accepted by a different server than the one it was issued for.

Revocability. To cut off an agent's access, you revoke or remove the M2M application in Kinde. It stops working immediately. No key rotation, no impact on other agents.

This is the pattern you should apply to your own MCP server. The steps below show you exactly how to implement it.

Step #1: Create a Kinde M2M Application for Your MCP Server

Before writing any server code, set up the authorization layer in Kinde. This takes about three minutes.

Create a free Kinde account at kinde.com if you do not have one. Then navigate to Settings → Applications → Add application and select Machine to machine.

Give it a descriptive name like My MCP Server Agent. Once created, open the application details and note down:

Client ID — the agent's unique identity
Client Secret — the credential used to obtain tokens (treat this like a password)
Token endpoint — https://YOUR_DOMAIN.kinde.com/oauth2/token
JWKS endpoint — https://YOUR_DOMAIN.kinde.com/.well-known/jwks.json

Now register your MCP server as an API in Kinde. Navigate to APIs → Add API. Give it a name (e.g. My MCP Server) and an audience identifier (e.g. https://mcp.yourapp.com). This audience value will be embedded in every token issued for your server — your server checks it on every request to ensure the token was meant for it specifically, preventing token passthrough attacks.

Step #2: Define Scopes for Tool-Level Permissions

This is the step most MCP servers skip entirely, and it is the most important one.

In your Kinde API definition (under APIs → select your API → Scopes), define one scope per logical group of tools. Do not define one global scope — that defeats the purpose. Think about the categories of capability your MCP server exposes and create a scope for each.

For a hypothetical MCP server that manages a SaaS product's users and data, the scopes might look like this:

Scope	Tools it authorizes	Who gets it
`users:read`	`get_user`, `list_users`, `search_users`	Read-only agents, analytics pipelines
`users:write`	`create_user`, `update_user`, `invite_user`	CRM agents, onboarding automations
`users:delete`	`delete_user`, `suspend_user`	Admin agents only
`data:read`	`query_records`, `export_data`	Reporting agents
`data:write`	`create_record`, `update_record`	Integration agents
`admin`	All tools	Trusted internal agents only

Now grant your M2M application the scopes it actually needs. Navigate to your M2M application → APIs → select your API → check only the scopes this specific agent should have. An agent that only needs to read users gets users:read. It cannot request a token with users:delete even if it tries — Kinde will not issue it.

The authorization policy is now defined. Time to build the server.

Step #3: Build the MCP Server with Token Validation

Now write the MCP server itself. This is a Node.js server using the @modelcontextprotocol/sdk package. The key additions over a basic MCP server are the JWT validation middleware and the per-tool scope enforcement.

First, install the dependencies:

npm init -y
npm install @modelcontextprotocol/sdk jwks-rsa jsonwebtoken express

Create the server file:

// server.ts
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
import express, { Request, Response, NextFunction } from "express";
import jwt from "jsonwebtoken";
import jwksClient from "jwks-rsa";
import { z } from "zod";

// ─── Configuration ──────────────────────────────────────────────────────────

const KINDE_DOMAIN = process.env.KINDE_DOMAIN!; // e.g. "yourapp.kinde.com"
const MCP_AUDIENCE = process.env.MCP_AUDIENCE!;  // e.g. "https://mcp.yourapp.com"

// JWKS client — fetches Kinde's public signing keys
// Used to verify that incoming tokens were genuinely signed by Kinde
const jwks = jwksClient({
  jwksUri: `https://${KINDE_DOMAIN}/.well-known/jwks.json`,
  cache: true,
  cacheMaxEntries: 5,
  cacheMaxAge: 600_000, // 10 minutes
});

// ─── JWT Validation ──────────────────────────────────────────────────────────

interface TokenPayload {
  sub: string;           // agent identity (M2M app client ID)
  scp?: string;          // space-separated scopes
  permissions?: string[]; // Kinde also surfaces permissions here
  aud: string | string[];
  iss: string;
  exp: number;
}

async function validateToken(authHeader: string | undefined): Promise<TokenPayload> {
  if (!authHeader?.startsWith("Bearer ")) {
    throw new Error("Missing or malformed Authorization header");
  }

  const token = authHeader.slice(7);

  // Decode the header to find the key ID (kid)
  const decoded = jwt.decode(token, { complete: true });
  if (!decoded || typeof decoded === "string") {
    throw new Error("Invalid token format");
  }

  const kid = decoded.header.kid;
  if (!kid) {
    throw new Error("Token missing key ID (kid)");
  }

  // Fetch the public key from Kinde's JWKS endpoint
  const signingKey = await jwks.getSigningKey(kid);
  const publicKey = signingKey.getPublicKey();

  // Verify the token — this checks signature, expiry, issuer, and audience
  const payload = jwt.verify(token, publicKey, {
    algorithms: ["RS256"],
    issuer: `https://${KINDE_DOMAIN}`,
    audience: MCP_AUDIENCE, // prevents token passthrough attacks
  }) as TokenPayload;

  return payload;
}

// ─── Scope Enforcement ───────────────────────────────────────────────────────

function requireScope(requiredScope: string) {
  return (payload: TokenPayload): void => {
    // Kinde puts scopes in the `scp` claim as a space-separated string
    const tokenScopes = payload.scp?.split(" ") ?? [];

    // Also check the `permissions` array (Kinde's permission system)
    const permissions = payload.permissions ?? [];

    const hasScope =
      tokenScopes.includes(requiredScope) ||
      tokenScopes.includes("admin") ||
      permissions.includes(requiredScope) ||
      permissions.includes("admin");

    if (!hasScope) {
      throw new Error(
        `Insufficient permissions. Required: ${requiredScope}. ` +
        `Token has: ${tokenScopes.join(", ") || "none"}`
      );
    }
  };
}

// ─── Auth Middleware ──────────────────────────────────────────────────────────

// Store the validated token payload on the request object
// so tool handlers can access it without re-validating
declare global {
  namespace Express {
    interface Request {
      agentToken?: TokenPayload;
    }
  }
}

async function authMiddleware(req: Request, res: Response, next: NextFunction) {
  try {
    const payload = await validateToken(req.headers.authorization);
    req.agentToken = payload;
    console.log(`Agent authenticated: ${payload.sub} with scopes: ${payload.scp}`);
    next();
  } catch (err) {
    console.warn(`Auth failed: ${(err as Error).message}`);
    res.status(401).json({
      error: "unauthorized",
      message: (err as Error).message,
    });
  }
}

// ─── MCP Server Definition ────────────────────────────────────────────────────

const server = new McpServer({
  name: "secure-mcp-server",
  version: "1.0.0",
});

// Tool #1: get_user — requires users:read scope
server.tool(
  "get_user",
  "Retrieve a user by their ID",
  {
    user_id: z.string().describe("The unique identifier of the user to retrieve"),
  },
  async ({ user_id }, { _meta }) => {
    // Access the validated token from the request context
    // The token was validated and attached by authMiddleware before this handler runs
    const token = (_meta as any)?.agentToken as TokenPayload;
    requireScope("users:read")(token);

    // Your actual business logic here
    // This is a placeholder — replace with real data fetching
    return {
      content: [
        {
          type: "text" as const,
          text: JSON.stringify({
            id: user_id,
            email: "user@example.com",
            name: "Jane Smith",
            created_at: "2025-01-15T10:30:00Z",
          }),
        },
      ],
    };
  }
);

// Tool #2: create_user — requires users:write scope
server.tool(
  "create_user",
  "Create a new user account",
  {
    email: z.string().email().describe("Email address for the new user"),
    name: z.string().describe("Full name of the user"),
    role: z.enum(["admin", "member", "viewer"]).default("member"),
  },
  async ({ email, name, role }, { _meta }) => {
    const token = (_meta as any)?.agentToken as TokenPayload;
    requireScope("users:write")(token);

    // Log who created the user for audit purposes
    console.log(`User creation requested by agent: ${token.sub}`);

    // Your actual user creation logic here
    return {
      content: [
        {
          type: "text" as const,
          text: JSON.stringify({
            id: `usr_${Date.now()}`,
            email,
            name,
            role,
            created_by_agent: token.sub,
            created_at: new Date().toISOString(),
          }),
        },
      ],
    };
  }
);

// Tool #3: delete_user — requires users:delete scope (most restrictive)
server.tool(
  "delete_user",
  "Permanently delete a user account",
  {
    user_id: z.string().describe("ID of the user to delete"),
    reason: z.string().describe("Reason for deletion (required for audit trail)"),
  },
  async ({ user_id, reason }, { _meta }) => {
    const token = (_meta as any)?.agentToken as TokenPayload;

    // This scope is only granted to trusted admin agents
    // Read-only agents cannot call this tool even if they know it exists
    requireScope("users:delete")(token);

    console.log(
      `AUDIT: User ${user_id} deleted by agent ${token.sub}. Reason: ${reason}`
    );

    return {
      content: [
        {
          type: "text" as const,
          text: JSON.stringify({
            deleted: true,
            user_id,
            deleted_by: token.sub,
            reason,
            timestamp: new Date().toISOString(),
          }),
        },
      ],
    };
  }
);

// ─── HTTP Server ──────────────────────────────────────────────────────────────

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

// The auth middleware runs on every MCP request before the tool handlers
app.post("/mcp", authMiddleware, async (req, res) => {
  const transport = new StreamableHTTPServerTransport({
    sessionIdGenerator: undefined,
  });

  // Pass the validated token into the MCP request context
  // so tool handlers can access it via _meta.agentToken
  (req as any).agentToken = req.agentToken;

  await server.connect(transport);
  await transport.handleRequest(req, res, req.body);
});

// Protected resource metadata endpoint — required for OAuth 2.1 discovery
// MCP clients fetch this to learn where to get tokens
app.get("/.well-known/oauth-protected-resource", (_req, res) => {
  res.json({
    resource: MCP_AUDIENCE,
    authorization_servers: [`https://${KINDE_DOMAIN}`],
    scopes_supported: [
      "users:read",
      "users:write",
      "users:delete",
      "data:read",
      "data:write",
      "admin",
    ],
    bearer_methods_supported: ["header"],
  });
});

const PORT = process.env.PORT ?? 3000;
app.listen(PORT, () => {
  console.log(`Secure MCP Server running on port ${PORT}`);
  console.log(`Protected resource metadata: http://localhost:${PORT}/.well-known/oauth-protected-resource`);
});

Step #4: How Agents Obtain Tokens

Your MCP server is now a protected resource. To call it, an agent needs a token. Here is how an OpenClaw-style agent — or any MCP client — would obtain one using Kinde's client credentials flow:

// agent-token.ts
// This code runs in the AGENT (the MCP client), not in the MCP server

async function getAgentToken(): Promise<string> {
  const tokenResponse = await fetch(
    `https://${process.env.KINDE_DOMAIN}/oauth2/token`,
    {
      method: "POST",
      headers: { "Content-Type": "application/x-www-form-urlencoded" },
      body: new URLSearchParams({
        grant_type: "client_credentials",
        client_id: process.env.KINDE_M2M_CLIENT_ID!,
        client_secret: process.env.KINDE_M2M_CLIENT_SECRET!,
        audience: process.env.MCP_AUDIENCE!, // your MCP server's audience
        scope: "users:read data:read", // only request what this agent needs
      }),
    }
  );

  if (!tokenResponse.ok) {
    const error = await tokenResponse.json();
    throw new Error(`Token request failed: ${JSON.stringify(error)}`);
  }

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

// Then use the token in every MCP request
async function callMcpTool(tool: string, params: object) {
  const token = await getAgentToken();

  const response = await fetch("https://mcp.yourapp.com/mcp", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": `Bearer ${token}`, // Kinde-issued JWT
    },
    body: JSON.stringify({
      jsonrpc: "2.0",
      method: "tools/call",
      params: { name: tool, arguments: params },
      id: 1,
    }),
  });

  return response.json();
}

Note: Tokens issued via client credentials are valid for one hour by default in Kinde. Agents should cache the token and only request a new one when it is close to expiry — not on every tool call. Check the expires_in field in the token response and refresh when there are 60 seconds or fewer remaining.

Step #5: Configure an OpenClaw Skill With Proper Auth

To connect a properly authenticated MCP server to an OpenClaw agent, you configure the skill in openclaw.json with the token endpoint details. Here is what a secure skill configuration looks like:

{
  "plugins": {
    "entries": {
      "my-secure-tool": {
        "enabled": true,
        "type": "mcp",
        "transport": "streamable-http",
        "url": "https://mcp.yourapp.com/mcp",
        "auth": {
          "type": "oauth2",
          "flow": "client_credentials",
          "token_endpoint": "https://YOUR_DOMAIN.kinde.com/oauth2/token",
          "client_id": "your_m2m_client_id",
          "client_secret_env": "MY_TOOL_CLIENT_SECRET",
          "audience": "https://mcp.yourapp.com",
          "scopes": ["users:read", "data:read"]
        }
      }
    }
  }
}

Note: client_secret_env points to an environment variable rather than embedding the secret inline — critical for anyone publishing skill configurations or committing them to version control. The secret itself lives in the environment, not in the config file.

This configuration gives your agent the specific scopes it needs and nothing more. If someone performs a prompt injection attack via Moltbook and tries to get this agent to call delete_user, the token does not have the users:delete scope — the MCP server rejects the call before it can execute.

Putting It All Together

Here is the complete security architecture you have built:

┌─────────────────────────────────────────────────────────────────┐
│                         Kinde                                   │
│                                                                 │
│  M2M Application (Agent Identity)                               │
│  ├── Client ID: m2m_abc123                                      │
│  ├── Granted scopes: users:read, data:read                      │
│  └── NOT granted: users:write, users:delete, admin              │
│                                                                 │
│  JWKS Endpoint: /well-known/jwks.json (public key verification) │
│  Token Endpoint: /oauth2/token (client credentials flow)        │
└───────────────────────────────┬─────────────────────────────────┘
                                │ issues signed JWT (1hr TTL)
                                │ with scopes: users:read data:read
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                      Agent (OpenClaw)                           │
│                                                                 │
│  Holds JWT in memory (never stored on disk)                     │
│  Sends: Authorization: Bearer <JWT> on every MCP request        │
└───────────────────────────────┬─────────────────────────────────┘
                                │ HTTPS POST /mcp
                                │ Authorization: Bearer <JWT>
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Secure MCP Server                            │
│                                                                 │
│  1. authMiddleware: validates JWT signature via JWKS            │
│     → checks issuer, audience, expiry                           │
│                                                                 │
│  2. Per-tool scope check: requireScope("users:read")            │
│     → tools/get_user ✓ (scope present)                          │
│     → tools/delete_user ✗ (scope missing → 401)                 │
│                                                                 │
│  3. Audit log: agent ID, tool called, timestamp                 │
└─────────────────────────────────────────────────────────────────┘

The security properties you now have that OpenClaw's default Skills did not:

Property	Insecure MCP (OpenClaw default)	Secure MCP (with Kinde)
Agent identity	Anonymous / shared API key	Cryptographic JWT (`sub` claim = M2M app ID)
Token forgability	API key can be shared/leaked	RS256 JWT signed by Kinde — cannot be forged
Tool-level permissions	All tools accessible to all callers	Per-tool scope enforcement
Prompt injection blast radius	Agent can call any tool if injected	Injected instruction can only call scoped tools
Token expiry	API keys never expire	1-hour TTL — breach window is bounded
Revocation	Must rotate key for all agents	Revoke one M2M app, others unaffected
Audit trail	None	Agent ID + scope logged on every tool call

Testing Your Security Layer

Before deploying, verify these four scenarios:

Test 1 — Valid token, allowed scope. Call get_user with a token that has users:read. You should receive the user data. This confirms the happy path works.

Test 2 — Valid token, insufficient scope. Call delete_user with a token that only has users:read. You should receive a 401 with a message like "Insufficient permissions. Required: users:delete." This confirms scope enforcement works.

Test 3 — Expired token. Manually modify the exp claim of a token or wait for it to expire, then attempt a call. You should receive a 401 with a JWT expiry error. This confirms token lifecycle enforcement works.

Test 4 — Wrong audience. Use a token issued for a different API (different aud claim) and attempt a call to your MCP server. You should receive a 401 with an audience mismatch error. This confirms that token passthrough attacks are blocked.

# Test 2 example — calling a tool without the required scope
curl -X POST https://your-mcp-server.com/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $READ_ONLY_TOKEN" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "delete_user",
      "arguments": {
        "user_id": "usr_123",
        "reason": "Test deletion attempt"
      }
    },
    "id": 1
  }'

# Expected response:
# HTTP 401 Unauthorized
# { "error": "unauthorized", "message": "Insufficient permissions. Required: users:delete. Token has: users:read" }

Amazing! Your MCP server is now hardened against the attack patterns that took down OpenClaw deployments and turned Moltbook into a security incident.

Conclusion

In this article, you built a secure MCP server with scoped, tool-level authentication — the approach that the OpenClaw and Moltbook incidents showed was critically missing from most agentic AI deployments. Your server now knows who every connecting agent is, what they are allowed to do, and rejects anything outside those boundaries at the tool boundary before execution.

The key insight from Kinde's own MCP server — shipped in January 2026 as a working reference implementation — is that security for AI agents is not fundamentally different from security for any other kind of software. M2M identities, scoped tokens, short TTLs, and JWT validation are not new concepts. What is new is applying them consistently to MCP servers, which the ecosystem has been slow to do.

Agentic AI is not going away. OpenClaw proved that. The question is whether the infrastructure it runs on is built securely. That starts with the MCP server you control.

Kinde is free for up to 10,500 monthly active users, no credit card required. Create your account at kinde.com and start treating your agents as the production infrastructure they are.

Stop Treating AI Agents Like Users: Why Your Auth Model Needs a New Layer for Non-Human Identities

Shola Jegede — Sat, 21 Mar 2026 23:40:03 +0000

Your auth system was built for humans. AI agents are not humans. Something has to give.

In this article, you will learn:

Why the traditional user auth model breaks down for AI agents
What non-human identities are and why they need their own auth layer
The difference between global and org-scoped machine identity
How the OAuth 2.0 client credentials flow works for non-human callers
How to use Kinde M2M applications to authenticate AI agents properly
How to scope agent access to a specific tenant using org-scoped M2M apps
The biggest security mistakes developers make when adding agent auth and how to avoid them

Let's dive in!

The Problem Nobody Warned You About

You shipped auth. Users can sign up, sign in, and get sessions. You followed the OAuth flow, you set up JWTs, you protected your routes. Everything works.

Then someone on your team says: "We're adding an AI agent that acts on behalf of users."

And suddenly you have a question your auth system was never designed to answer: how do you authenticate something that has no browser, no session, no email address, and no ability to type in a password?

The lazy answer is to create a fake user account for the agent. Give it an email like agent@yourapp.com, hand it a password, and call it done. It works — until it becomes a security nightmare. You have an account with full user-level access, no MFA, credentials that never rotate, and no audit trail that distinguishes what the agent did from what a real user did. That is not an auth model. That is a ticking clock.

The real answer is that AI agents are not users. They are non-human identities. They need their own authentication layer, their own token type, their own scopes, and their own access boundaries. And in 2026, with AI agents becoming a core part of SaaS products, getting this right is no longer optional.

Here is what that looks like in practice, and how Kinde's M2M application system handles it properly.

What Is a Non-Human Identity?

A non-human identity (NHI) is any software principal that needs to authenticate and call APIs without a human being directly involved in the auth flow. In the context of modern SaaS products, non-human identities include things like backend services, CI/CD pipelines, scheduled jobs, microservices, and — increasingly — AI agents.

What all of these have in common is that they cannot participate in an interactive auth flow. There is no redirect. There is no browser. There is no one sitting at a keyboard to enter a verification code. A human auth flow is fundamentally the wrong tool for the job.

The problem is that most auth systems — and most developer mental models — were built around human identities first. Non-human auth was bolted on later, often improperly, as an afterthought.

Why the Fake User Approach Fails

Before getting into the right solution, it is worth being specific about why the fake user workaround is dangerous. These are not theoretical risks.

Over-permissioned by default. A user account typically has all the permissions of a regular user. For an AI agent that only needs to read data from one endpoint and write to another, that is massive over-permission. Least-privilege is the foundational principle of access control, and fake user accounts violate it immediately.

No credential rotation. User passwords are designed to be long-lived and human-memorable. They are not designed to be rotated on a schedule the way service credentials should be. In practice, the fake user's password never changes, which means a leaked credential is a permanent breach.

No audit trail separation. When an agent operating as agent@yourapp.com makes a write operation, your logs show a user action. You cannot distinguish agent activity from human activity. Debugging becomes a nightmare, compliance becomes impossible, and incident response becomes guesswork.

Sessions and cookies do not make sense. User auth produces sessions tied to browsers. Agents do not have browsers. They do not maintain state across requests the same way users do. Forcing them through a session-based flow creates fragile plumbing that breaks under load or on token expiry.

MFA breaks the whole thing. If you ever enforce MFA for user accounts — and you should — your fake agent account will be locked out the moment MFA is required. Either you exempt it, which creates a security hole, or you break your automation.

The Right Mental Model: Machine-to-Machine Authentication

The correct solution has existed in the OAuth 2.0 specification for years. It is called the client credentials flow, and it is specifically designed for non-human identities authenticating without user involvement.

Instead of a user logging in with credentials, a machine authenticates using a client_id and client_secret. It sends those credentials directly to the token endpoint and receives an access token in return. No redirects. No browser. No session. Just a token that the machine can use to call APIs on its own behalf.

The access token issued through the client credentials flow is structurally different from a user token. It does not have a sub claim representing a user. It does not expire into a refresh token cycle the way user sessions do. It is scoped to the capabilities of the machine application, not the permissions of a specific person. This distinction is crucial.

In Kinde, this pattern is implemented through M2M applications — Machine-to-Machine applications. An M2M application is a registered identity in Kinde with its own client_id and client_secret, its own set of API scopes, and its own token. It is the right primitive for any non-human caller: a CI/CD pipeline, a backend service, an automation script, or an AI agent.

Two Types of Machine Identity in Kinde

Kinde supports two types of M2M applications, and understanding the difference is important for building the right auth model for your product.

Global M2M Applications

A global M2M application is not tied to any specific organization in your Kinde setup. It operates across your entire tenant space. This makes it suitable for internal tooling, admin automation, infrastructure scripts, and anything that needs to operate at the system level rather than within a specific customer's context.

A typical use case is a CI/CD pipeline that needs to call the Kinde Management API to create users, update flags, or deploy configuration changes across all of your organizations. It does not need to be scoped to one tenant — it needs cross-tenant access, and a global M2M app provides exactly that.

Org-Scoped M2M Applications

An org-scoped M2M application is tied to a specific organization — a specific tenant — in your Kinde setup. Tokens issued to this app automatically include the org_code claim, which enforces that all API calls made by this machine identity are restricted to that organization's context.

This is the right pattern for AI agents acting on behalf of a specific customer. If Acme Corp has an AI agent that reads their data, writes to their workspace, and takes actions in their context, that agent should not have any access to the data or context of Beta Inc. Org-scoped M2M applications enforce this boundary at the token level — before your API even has to think about it.

Note: Org-scoped M2M applications are available on the Kinde Plus and Kinde Scale plans.

Global vs Org-Scoped M2M: At a Glance

Feature	Global M2M App	Org-Scoped M2M App
Org context in token	No	Yes (`org_code` claim)
Tenant data isolation	Manual (your API must enforce it)	Enforced at token issuance
Best for	Admin scripts, internal automation, infra	Per-tenant AI agents, scoped APIs
Token restrictions	None	Scoped to one organization
Credential rotation	Manual, in Kinde dashboard	Manual, in Kinde dashboard
Available on	All plans	Kinde Plus and Scale

How the Client Credentials Flow Works in Kinde

When an M2M application needs to call an API, it follows the OAuth 2.0 client credentials flow. Here is exactly what that looks like in code.

Step #1: Request a Token

The machine application sends a POST request to your Kinde domain's token endpoint. It authenticates with its client_id and client_secret and requests the scopes it needs.

curl --request POST \
  --url https://YOUR_KINDE_DOMAIN.kinde.com/oauth2/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data grant_type=client_credentials \
  --data client_id=YOUR_M2M_CLIENT_ID \
  --data client_secret=YOUR_M2M_CLIENT_SECRET \
  --data audience=https://YOUR_KINDE_DOMAIN.kinde.com/api \
  --data scope=read:users write:flags

Note: Replace YOUR_KINDE_DOMAIN, YOUR_M2M_CLIENT_ID, and YOUR_M2M_CLIENT_SECRET with the values from your Kinde dashboard.

Step #2: Receive the Access Token

Kinde responds with an access token:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 86400,
  "scope": "read:users write:flags"
}

For an org-scoped M2M app, the decoded token payload will also include the org_code claim:

{
  "iss": "https://YOUR_KINDE_DOMAIN.kinde.com",
  "sub": "YOUR_M2M_CLIENT_ID",
  "aud": ["https://YOUR_KINDE_DOMAIN.kinde.com/api"],
  "exp": 1234567890,
  "iat": 1234567890,
  "scope": "read:users write:flags",
  "org_code": "org_abc123"
}

The org_code claim is embedded at token issuance time and cannot be modified. Your API can trust it completely.

Step #3: Call Your API with the Token

The agent uses the access token as a Bearer token in subsequent API calls:

// Node.js example — calling your API as an M2M client
const response = await fetch("https://api.yourapp.com/v1/users", {
  method: "GET",
  headers: {
    // pass the M2M token as a Bearer token
    Authorization: `Bearer ${accessToken}`,
    "Content-Type": "application/json",
  },
});

const data = await response.json();

Step #4: Verify the Token on Your API

Your API receives the token and verifies it. For an org-scoped M2M app, you can trust the org_code claim directly from the verified token to enforce tenant isolation without any additional lookup:

// Express.js middleware — verifying and using the org_code from an M2M token
import jwt from "jsonwebtoken";
import jwksClient from "jwks-rsa";

const client = jwksClient({
  jwksUri: `https://YOUR_KINDE_DOMAIN.kinde.com/.well-known/jwks.json`,
});

function getKey(header, callback) {
  client.getSigningKey(header.kid, (err, key) => {
    const signingKey = key.getPublicKey();
    callback(null, signingKey);
  });
}

function verifyM2MToken(req, res, next) {
  const authHeader = req.headers["authorization"];
  const token = authHeader && authHeader.split(" ")[1];

  if (!token) {
    return res.status(401).json({ error: "No token provided" });
  }

  jwt.verify(
    token,
    getKey,
    {
      audience: "https://YOUR_KINDE_DOMAIN.kinde.com/api",
      issuer: "https://YOUR_KINDE_DOMAIN.kinde.com",
    },
    (err, decoded) => {
      if (err) {
        return res.status(403).json({ error: "Invalid token" });
      }

      // org_code is now trusted and available — no additional lookup needed
      req.orgCode = decoded.org_code;
      req.scopes = decoded.scope ? decoded.scope.split(" ") : [];
      next();
    }
  );
}

// Use in a route to enforce org isolation
app.get("/v1/users", verifyM2MToken, async (req, res) => {
  // All queries are automatically scoped to this organization
  const users = await db.users.findAll({
    where: { org_code: req.orgCode },
  });

  res.json({ users });
});

Wonderful! Your API now enforces tenant isolation based entirely on what is in the verified token — no additional queries, no custom middleware logic, no trust-but-verify gymnastics.

Setting Up an M2M Application in Kinde

Creating a Global M2M Application

In your Kinde dashboard, navigate to Settings → Applications.
Select Add application.
Give your application a name — something descriptive like "Reporting Pipeline" or "Internal Automation Agent".
Select Machine to machine as the application type.
Select Save.

Kinde generates a client_id and client_secret for your new application. Save the secret immediately — it is only shown once.

Assigning Scopes to the M2M Application

Before your M2M application can call any API, you need to assign the scopes it is permitted to request. Scopes define the boundaries of what the token can do.

Navigate to the APIs section of your M2M application and select the APIs the application needs access to. For each API, choose only the scopes genuinely required by the agent. A reporting agent that only reads data should have read:reports, not write:reports or delete:reports. Least privilege applies here just as much as it does for users.

Creating an Org-Scoped M2M Application

In your Kinde dashboard, navigate to Organizations.
Select the organization you want to scope the M2M app to.
Select the M2M apps tab.
Enter a name for the application — for example, "Acme Corp AI Agent".
Select M2M application as the type.
Select Save.

Kinde generates a client_id and client_secret tied specifically to that organization. Tokens issued with these credentials will automatically include the org_code claim set to that organization's code.

A Real-World Scenario: Per-Tenant AI Agent

Here is a concrete scenario to make this tangible. You are building a B2B SaaS product with an AI feature that automatically summarizes activity for each customer's workspace. The agent needs to read data from your API, process it, and write a summary back.

Without org-scoped M2M, your agent either has global access (dangerous) or you build custom tenant-checking middleware on every endpoint (fragile). With org-scoped M2M in Kinde, each customer's agent gets its own set of credentials that are cryptographically tied to their organization. The token tells your API exactly which tenant it belongs to, and your API can trust that claim without any additional work.

The full flow for this scenario looks like:

On onboarding, create an org-scoped M2M application for the new customer's organization in Kinde.
Store the client_id and client_secret securely (environment variables, secrets manager, etc.).
When the agent needs to act, it requests a token using the client credentials flow.
It calls your API with the token as a Bearer header.
Your API verifies the token, extracts org_code, and scopes all database queries to that organization.
The agent can never access another tenant's data, even if its credentials were somehow leaked — because the token itself is bound to one org.

What About Kinde's MCP Server?

In January 2026, Kinde shipped an MCP (Model Context Protocol) server. This lets AI agents and AI tools connect to Kinde directly using the MCP protocol — which is rapidly becoming the standard interface for AI-to-tool communication.

What this means in practice is that AI agents using MCP-compatible frameworks (like Claude Code, Cursor, or any agent built on an MCP client library) can interact with Kinde's management capabilities — creating users, managing organizations, checking permissions, and more — through a standardized tool interface rather than raw API calls.

For teams building AI-native products, this is a big deal. Instead of writing custom integration code to give your agent access to Kinde's capabilities, you can connect it via the MCP server and let it use those capabilities as native tools.

The MCP server and M2M applications complement each other. M2M handles the authentication layer — proving the agent's identity and authorizing its access. The MCP server handles the interface layer — giving the agent a structured way to use Kinde's functionality once it is authenticated.

Security Best Practices for M2M Auth

There are a few principles that are non-negotiable when running machine identities in production.

One M2M application per service. Do not share credentials across multiple agents or services. If one service is compromised, its credentials can be revoked without affecting anything else. Shared credentials mean shared blast radius.

Minimum necessary scopes. Every M2M application should be granted only the scopes it genuinely needs to do its job. An agent that reads data should not have write access. An agent that writes to one resource should not have write access to all resources. Define your API scopes granularly and assign them carefully.

Rotate client secrets on a schedule. Client secrets are long-lived credentials and they should be rotated periodically. Kinde provides secret rotation directly in the dashboard. Build secret rotation into your operational runbook and do not treat it as optional.

Never put client secrets in client-side code. M2M credentials authenticate a service, not a user. They must live server-side — in environment variables, in a secrets manager, in a secure deployment config. Putting them anywhere that gets shipped to a browser is an immediate credential leak.

Track client_id and org_code in your logs. When an M2M token is used to call your API, log the client_id alongside the org_code. This gives you a clean audit trail that distinguishes what each agent did, in which tenant's context, at what time. When something goes wrong — and eventually something will — this makes debugging and incident response dramatically faster.

Token expiry is your friend. M2M tokens expire. Do not try to cache them indefinitely. Let them expire and re-request as needed. Short expiry windows limit the blast radius of a leaked token significantly. Kinde issues M2M tokens with configurable expiry — keep it as short as your use case allows.

Conclusion

In this article, you learned why the traditional user auth model breaks down for AI agents, what non-human identities are and why they need their own auth layer, and how the OAuth 2.0 client credentials flow provides the right foundation for machine authentication. You also saw how Kinde's M2M applications implement this properly — with global apps for internal tooling and org-scoped apps for per-tenant AI agents that enforce isolation at the token level.

The shift to AI-native products is not slowing down. Every SaaS product built in 2026 is adding or planning to add agent capabilities. The teams that get non-human identity right from the beginning are the ones that avoid the security incidents, the audit nightmares, and the architectural rewrites that come from bolting fake user accounts onto a system that was never designed for them.

Kinde gives you the primitives to do this properly from day one. Create a free Kinde account and start building your M2M auth layer today.

Building a Live AI Market Research Terminal: How Bright Data and Convex Replace Polling With Real-Time Everything

Shola Jegede — Tue, 10 Mar 2026 08:14:08 +0000

Most AI tools fall apart at the same point: making sure the output is grounded in what's happening right now, not what the model was trained on months ago.

Bright Data built an open-source demo that solves this. It's called the Signal Terminal, a financial research tool built around that problem.

Why This Tool Exists

Meir Kadosh is an AI Engineer at Bright Data, and he kept noticing the same thing happening with financial customers. They would pull Google search results, pass them to an LLM, scrape the relevant pages for deeper context, and try to piece together why a stock had moved. The pipeline was almost identical every time. Different teams, same use case, everyone rebuilding from scratch.

So Meir built the canonical version — an open-source reference architecture that financial customers can use directly and developers can build on.

What Happens When You Ask a Question

Type "Why did Nvidia's stock drop today?" and the app runs a structured pipeline:

plan → search → scrape → extract → link → cluster → render

Each stage is visible and each source is attributed.

The planning stage comes first. The model generates specific search angles based on the question: what to look for, how recent, which categories of signals matter, things like macro events, earnings surprises, analyst actions, and news catalysts.

Then Bright Data's SERP API fires across Google and returns structured JSON for the most relevant sources in under a second. For pages that need deeper analysis, Bright Data's Web Unlocker fetches the full content as clean Markdown, handling the sites that block standard scrapers.

From there the LLM pulls named entities, causal relationships, and key figures from the content, those entities get connected into an evidence graph, related signals cluster into narrative themes, and everything surfaces in a live multi-panel dashboard.

The evidence map shows exactly which sources contributed which claims, how they connect to each other, and which narratives the evidence actually supports.

Two Paths, Depending on What You Need

Not every query needs the same depth.

The fast path uses SERP results only. Bright Data's SERP API returns structured JSON for each result (URL, description, position) and that passes directly to the LLM. Standard SERP delivers in 1-2 seconds, and with Bright Data's premium infrastructure, complete results come back in under one second. For real-time chat interfaces where latency is the whole point, this is the right path.

The deep path, which Meir calls "search and extract" internally, adds a second layer. After SERP identifies the relevant sources, Web Unlocker fetches each page's full content as clean Markdown, which then goes to the LLM for extraction and analysis. It takes longer, but for a full research run where completeness matters more than speed, that tradeoff makes sense.

The SERP route maps the incoming format param to Bright Data's format string and fires the request:

// app/api/serp/route.ts
const results = await brightDataSerpGoogle({
  query: parsed.data.q,
  format:
    format === 'full'     ? 'full_json_google'  :
    format === 'markdown' ? 'markdown'          :
                            'light_json_google',
  vertical, // 'web' | 'news'
  recency,  // 'h' | 'd' | 'w' | 'm' | 'y'
});

The token is BRIGHTDATA_API_TOKEN (with API_TOKEN as fallback). The SERP zone resolves through BRIGHTDATA_SERP_ZONE then BRIGHTDATA_SERP_ZONE_NAME, falling back to the Web Unlocker zone if neither is set. The Web Unlocker zone has its own resolution chain, defaulting to mcp_unlocker if nothing is configured.

Why Bright Data and Not Something Else

If you've built a scraper before, you already know how this story goes. It works locally. You deploy it. It gets blocked. You add proxy rotation and now some sites work, but LinkedIn doesn't, and Reddit doesn't, and when you look up how to handle TLS fingerprinting you're suddenly two weeks deep into a rabbit hole that has nothing to do with your actual product.

Getting clean data from LinkedIn, Reddit, X, and TikTok means solving years of adversarial engineering: TLS fingerprinting, browser fingerprinting, behavioral analysis, rotating CAPTCHAs. Web Unlocker handles all of that. The platforms that reliably block everything else.

Coverage spans seven major search engines and 195 countries with city-level targeting, so the results reflect what someone in a specific location actually sees.

The Part Most Developers Skip

There's a failure mode that shows up constantly in LLM pipelines built on web data. You fetch a full page, pass it to the model, and the output is worse than you expected. The instinct is to blame the model. Usually the model is fine. The context is the problem.

A full webpage is mostly noise. Navigation menus, cookie banners, author bios, related articles, advertisement slots. All of that lands in the context window alongside the three paragraphs that actually matter to your query. Flooding the model with irrelevant tokens makes the output worse, drives up token costs, and gives the model more surface area to hallucinate from.

The Signal Terminal handles this with a reflection stage that runs between fetching and analysing. Before the main analysis call, an extraction step strips everything irrelevant from the Markdown. Only the facts, named entities, causal statements, and figures directly related to the original query reach the analysis model.

Each stage has a dedicated prompt-builder function. The summarization stage looks like this:

// lib/prompts/signal-terminal.ts
export function buildSignalTerminalSummariesPrompt({ topic, evidenceExcerpts }) {
  const system = [
    'You are a market news summarizer for active traders.',
    'Use only the provided excerpts; do not invent facts.',
    'If an excerpt is low-signal (navigation/menus/price page), omit it.',
    'Return strict JSON only.',
  ].join('\n');

  const user = [
    `Topic: ${topic}`,
    'Evidence excerpts (JSON):',
    JSON.stringify(evidenceExcerpts),
    '',
    'Return JSON: { items: [{ id, bullets: string[2..5], entities?, catalysts?, sentiment?, confidence? }] }',
    '- Write for traders: prefer concrete nouns, numbers, and named actors.',
    '- Sentiment: "bullish" | "bearish" | "mixed" | "neutral" — reflect the excerpt, not your opinion.',
    '- Confidence: 0..1 based on excerpt specificity (dates/numbers/attribution increases confidence).',
  ].join('\n');

  return { system, user };
}

Every stage has its own function like this: planning, impact graph expansion, chat. The model never gets a freeform prompt and a wall of raw text. It gets a tightly scoped system instruction, a JSON payload of curated evidence, and a strict output schema. The analysis model cannot fabricate beyond what it's been given.

Where Convex Comes In

Once Bright Data has acquired the evidence, it needs somewhere to go that can stream each pipeline stage to the UI as it completes, persist the results for follow-up queries, and stay fast enough that the interface actually feels live.

Meir’s first choice for this layer was Supabase. He switched to Convex because the latency difference in the real-time chat experience was noticeable enough to change the stack.

Relational databases have no built-in reactivity. If you want to know when something changes, you build it yourself — polling, pub/sub servers, WebSocket management layered on top of your existing stack.

Convex tracks the data dependencies of every active query, and the moment any of those dependencies change, it reruns the affected query and pushes the updated result to every subscribed client over a persistent WebSocket. For a pipeline that executes in sequential stages, you want the frontend to reflect each stage as it lands, not on the next poll cycle.

Beyond reactivity, Convex brought two things that would have required separate infrastructure elsewhere: full-text search built into the database, and a transactional scheduler for TTL cleanup. No cron jobs, no external queue, no search service.

Convex ends up serving three distinct roles in the Signal Terminal.

Role 1: Streaming Pipeline Events in Real Time

Each stage of the pipeline writes its results to Convex the moment it completes, and the frontend subscribes with a single useQuery hook.

// convex/schema.ts
export default defineSchema({
  sessions: defineTable({
    sessionId: v.string(),
    topic: v.string(),
    status: v.string(),
    step: v.string(),
    progress: v.float64(),
    meta: v.optional(v.any()),
  })
    .index("by_sessionId", ["sessionId"])
    .searchIndex("search_topic", { searchField: "topic" }),

  sessionEvents: defineTable({
    sessionId: v.string(),
    type: v.string(),
    payload: v.any(),
  }).index("by_sessionId", ["sessionId"]),
});

The server writes an event every time a stage completes: search.partial, evidence, graph, clusters. The client sees it the moment it lands. No polling interval to tune, no missed transitions.

Role 2: Topic-Indexed Search for Follow-Up Chat (RAG Without Vectors)

After a research run completes, users can ask follow-up questions like "What did the Reuters article say about supply chain risk?" The app retrieves relevant past evidence without re-running the full Bright Data pipeline.

Convex handles this by indexing the topic field and enabling text-based search across historical sessions. No embeddings, no vector database, no additional infrastructure.

// convex/sessions.ts — search past sessions by topic keyword
export const list = query({
  args: {
    limit: v.optional(v.float64()),
    status: v.optional(v.string()),
    q: v.optional(v.string()),
  },
  handler: async (ctx, args) => {
    const limit = (args.limit ?? 50) as number;

    if (args.q && args.q.trim()) {
      // Full-text search across the topic field via searchIndex
      let results = await ctx.db
        .query("sessions")
        .withSearchIndex("search_topic", (q) => q.search("topic", args.q!.trim()))
        .take(limit);
      if (args.status) results = results.filter((s) => s.status === args.status);
      return results;
    }

    let results = await ctx.db.query("sessions").order("desc").take(limit);
    if (args.status) results = results.filter((s) => s.status === args.status);
    return results;
  },
});

No separate index on topic. Convex's searchIndex handles full-text retrieval.

The same mechanism that powers the follow-up chat also powers session history browsing. And because this is a Convex query, it's reactive: if a new session for the same topic completes while the user is in chat, the context updates automatically.

Role 3: Scheduled Cleanup

Convex's built-in scheduler handles cleanup without a cron job. When a session is created, a cleanup task is scheduled to run exactly 24 hours later.

// convex/sessions.ts — TTL scheduled at creation time
const TTL_MS = 24 * 60 * 60 * 1000;

export const create = mutation({
  args: { sessionId: v.string(), topic: v.string(), /* ... */ },
  handler: async (ctx, args) => {
    await ctx.db.insert("sessions", args);
    // Schedule cleanup for exactly this session, 24h from now
    await ctx.scheduler.runAfter(TTL_MS, internal.sessions.deleteExpired, {
      sessionId: args.sessionId,
    });
  },
});

export const deleteExpired = internalMutation({
  args: { sessionId: v.string() },
  handler: async (ctx, { sessionId }) => {
    const session = await ctx.db
      .query("sessions")
      .withIndex("by_sessionId", (q) => q.eq("sessionId", sessionId))
      .first();
    if (session) await ctx.db.delete(session._id);

    const events = await ctx.db
      .query("sessionEvents")
      .withIndex("by_sessionId", (q) => q.eq("sessionId", sessionId))
      .collect();
    for (const ev of events) await ctx.db.delete(ev._id);
  },
});

Each session cleans up after itself. The scheduler fires once per session, 24 hours after creation, and deletes that session and all its events. Because scheduling from a mutation is atomic, if the session creation succeeds, the cleanup is guaranteed to be scheduled, and because it's a mutation, it's guaranteed to execute exactly once.

On the Model Choice

The app runs on Gemini 3.0 Flash via OpenRouter. The architecture supports full model configurability: different models per stage, per speed mode. Each stage (planning, summaries, artifacts, chat) can be independently configured with a base model, a fast variant, and a deep variant.

At runtime, the selection logic works down a priority chain: explicit caller override first, then the stage-specific fast or deep model, then the stage base, then the provider default.

// lib/ai/model-selector.ts
export function selectStageModel({ stage, mode, requestedModel }) {
  const explicit = firstNonEmpty(requestedModel);
  if (explicit) return explicit; // caller override wins

  const profile = env.ai.openrouter;
  const stageProfile = stageModels(profile, stage); // plan | summaries | artifacts | chat
  const modeFallback = mode === 'fast' ? profile.modelFast : profile.modelDeep;

  if (mode === 'fast') {
    return firstNonEmpty(stageProfile.fast, stageProfile.base, modeFallback, profile.model);
  }
  return firstNonEmpty(stageProfile.deep, stageProfile.base, modeFallback, profile.model);
}

This matters in multi-stage pipelines because latency compounds. Planning, summarization, graph expansion, and chat all run in sequence, and a slow model at each step multiplies into a slow tool. A fast model at planning and summarization with a deeper model only for chat is a meaningful architectural choice.

What Bright Data and Convex Have in Common

Both solve the same class of problem in their respective layers. You could build what either one does yourself: proxy rotation and bot evasion on the data side, WebSocket management and pub/sub infrastructure on the persistence side.

Both are years of engineering work that exist so you don't have to do them. Bright Data delivers structured, fresh web data at the moment you ask for it. Convex delivers that data to every subscribed client the moment it lands in the database. The application code gets to be about the product, not the infrastructure.

The Architecture You Can Take With You

The Signal Terminal is a financial research tool, but the pattern applies anywhere you need an AI that reasons about what's happening now: competitive intelligence, news monitoring, lead research, price tracking, sentiment analysis, supply chain surveillance.

Bright Data handles the outside world — fresh, compliant web data at scale, with unlocking across platforms that block everything else. Convex handles the inside world: reactive persistence, streaming to the UI, querying without a vector database, housekeeping on a schedule. The LLM reasons only from what it's been given, because the reflection stage ensures it only receives what's relevant.

Try It, Fork It, Build With It

Go to demos.brightdata.com/market-terminal and ask it a real question about a company or market event you already know something about. Watch each pipeline stage complete. See the evidence map build. Ask a follow-up in the chat and see whether the output matches what you already know.

The code is at github.com/brightdata/market-terminal. Open source, contributions welcome.

The Convex community Discord is a strong resource for questions about the reactive database layer.

Thanks to Meir Kadosh at Bright Data for walking me through all of this and building something worth writing about.

How to Build Passwordless Auth That Doesn't Frustrate Users (Magic Links, One-Time Codes, and What Actually Works)

Shola Jegede — Tue, 27 Jan 2026 22:34:23 +0000

Passwordless auth is supposed to make signing in easier. Here is why most implementations make it worse — and how to get it right.

In this article, you will learn:

Why passwordless authentication exists and what problem it actually solves
The real difference between magic links and one-time codes — and why Kinde chose OTPs over magic links
The UX mistakes that turn passwordless into a frustration machine
What the full range of passwordless options looks like: email OTP, SMS OTP, username + code, and social login
How to enable and configure each method in Kinde
How to set per-app and per-org authentication rules
Attack protection settings you should configure before going live
What actually works and what to avoid

Let's dive in!

The Problem with Passwords (and Why Replacing Them Is Harder Than It Looks)

Passwords are a disaster. Users reuse them, forget them, choose weak ones, get phished with them, and abandon your signup flow because of them. The average person manages dozens of accounts, and the reality of password hygiene in 2026 is grim: most people use the same five passwords across everything they care about.

So the instinct to go passwordless is correct. Remove the password and you remove a huge class of security problems and UX friction at once. No "Forgot password?" flows. No "Password must contain one uppercase letter, one symbol, and the blood of a dragon." Just an identity and a verification step.

The problem is that most passwordless implementations trade one frustration for another. Instead of a forgotten password, users face a magic link that expired. Instead of a weak password, they face an OTP email that landed in spam. Instead of a clear error message, they face a confusing redirect loop across browser tabs.

Done right, passwordless is a dramatic improvement. Done poorly, it makes users nostalgic for the password box.

Here is how to do it right, and how Kinde structures its passwordless authentication options to actually serve users instead of annoying them.

Magic Links vs One-Time Codes: The Real Difference

Before getting into implementation, it is worth understanding the actual security and UX tradeoff between the two most common passwordless approaches, because they are not equivalent.

A magic link is a URL sent to the user's email that, when clicked, signs them in immediately. One click, no input required.

A one-time passcode (OTP) is a short code — typically 6 digits — sent to the user's email or phone. The user must actively type it into your sign-in page.

Magic links sound more convenient. Fewer steps, lower friction, just click. But Kinde deliberately does not support magic links as a password alternative. Here is the reasoning, and it is worth understanding because it shapes how you think about passwordless security.

Magic links have a single-click attack surface. Anyone with access to the user's email can click the link and be instantly signed in. If the user's email is open on a shared or unlocked device, a family member, colleague, or attacker can click the link without knowing anything else. There is no second factor implied by the act of clicking.

OTPs require active participation. To use an OTP, you have to have initiated the correct sign-in flow on the correct device, and then separately retrieve and type the code. If someone else has access to your email and they see an OTP, they cannot use it unless they are also sitting at the browser tab where the sign-in flow started. If the OTP arrives via SMS, they need the physical device and its unlock code.

This is a meaningful security distinction, especially for B2B and SaaS products where account compromise can have real consequences for the user's organization — not just their personal data.

Kinde's position is clear: OTPs are more secure and still offer a dramatically better user experience than passwords. The OTP flow is a bit more manual than a magic link click, but it is fundamentally more defensible. That is a trade-off worth making.

What Passwordless Options Does Kinde Support?

Kinde supports four passwordless authentication methods, covering email, phone, and username-based flows. Each method can be enabled independently and configured per application or per organization.

Email + code. The user enters their email address. Kinde sends a one-time passcode to that email. The user enters the code to complete sign-in. This is enabled by default in all new Kinde accounts — it is the recommended starting point for most products.

Phone + code (SMS OTP). The user enters their phone number. Kinde sends a passcode via SMS through Twilio. The user enters the code. This requires a Twilio account and a Kinde Pro plan or above. It is the right choice for products where users are more likely to have reliable phone access than email access, or where mobile-first UX is a priority.

Username + code. The user enters a username instead of an email as their sign-in identity. They still provide an email at signup, but sign in with a username and receive the OTP via that email. This is useful for products where usernames are part of the product identity — gaming platforms, community tools, and developer tools where GitHub-style handles matter.

Social connections. Google, GitHub, Microsoft, Apple, and 10+ other providers. Social login is a form of passwordless authentication — the user delegates the verification step to a provider they already trust. Kinde handles the OAuth flow and the token exchange. Social connections can be combined with email or phone OTP for fallback.

The Passwordless UX Mistakes That Frustrate Users

Before the implementation steps, a quick catalogue of the things that make passwordless authentication worse than passwords. These are avoidable if you know what to watch for.

Slow code delivery. If the OTP email takes 45 seconds to arrive, the user assumes something broke and refreshes or starts over. Target delivery under 5 seconds. Kinde delivers codes quickly, but your email sender reputation and deliverability setup affect this — see the section on custom email senders below.

Codes that expire too fast. Some implementations set 60-second or 90-second windows. That is often not enough time for the user to switch apps, unlock their phone, and type the code. Kinde's passcodes expire after 2 hours, which is a generous and sensible window that covers the common case of someone signing in, getting distracted, and returning to complete it.

No "resend code" option. Users will not receive their code sometimes. Spam filters, brief mail server delays, a typo in the email — all of these happen. Your sign-in page must have a clearly visible "Resend code" action. If users cannot find it, they assume the product is broken.

Too many authentication choices. Offering six different sign-in methods on one screen creates decision paralysis. Pick the one or two that match your users' context and present them cleanly. You can always add more later.

Unclear error messages. "Authentication failed" tells the user nothing. "That code has expired. Request a new one below." tells them exactly what happened and what to do next. Match the message to the actual failure mode.

Sending codes to a junk folder. This is the most common complaint about OTP-based auth. A code from an unknown sender ("noreply@kinde.com") is more likely to hit spam than a code from your own domain. Configure a custom email sender in Kinde so codes arrive from your domain, not Kinde's.

Enabling Passwordless Authentication in Kinde

Step #1: Access the Authentication Settings

In your Kinde dashboard, navigate to Settings → Environment → Authentication.

You will see three sections: Passwordless, Password, and Social connections. For each authentication type, there is a tile with a Configure button. Note that you cannot enable both passwordless and password authentication for the same application — they are mutually exclusive per app.

Step #2: Enable Email + Code

Email + code is the foundational passwordless method and the one most products should start with. Kinde enables it by default for new accounts, but here is how to confirm and configure it.

Select Configure on the Email tile in the Passwordless section.

In the modal that appears, you will see a list of your applications. Toggle email + code on or off for each application independently. This means you can have passwordless on your main app and password auth on a separate admin portal if you need to. Select Save.

Step #3: Enable Phone (SMS) Authentication

Phone authentication is ideal for mobile-first products and audiences where SMS is more reliable than email. It requires a Twilio account and Kinde Pro plan or above.

Select Configure on the Phone tile in the Passwordless section.

To complete the setup, you will need to connect your Twilio account. Navigate to Settings → Twilio and enter your Twilio account SID, auth token, and the phone number or messaging service SID you want to send from. Once connected, phone auth will work for the applications you toggled on.

Note: SMS delivery is subject to carrier filtering and regional regulations. For international products, test OTP delivery across your target markets before launch. Kinde has documentation on SMS deliverability worth reading before enabling this at scale.

Step #4: Enable Username + Code

If your product uses usernames as the primary identity — rather than email addresses — this method lets users sign in with their username while still receiving OTPs via their registered email.

Select Configure on the Username + code tile in the Passwordless section and toggle it on for the relevant applications.

Note: Username + code requires users to have provided an email at signup. The OTP is sent to that email, not displayed next to the username field. Make sure your sign-in page clearly communicates that the code will go to their registered email.

Step #5: Add Social Connections

Social sign-in is a seamless form of passwordless auth for many users. Google in particular is dominant — a large proportion of users will choose "Continue with Google" over any other option if it is available.

In the Social connections section, select Add connection.

Select the providers you want to add and select Save. After saving, each social connection you added needs to be configured with the provider's credentials — client ID and client secret from the provider's developer console. Select the individual provider tile and follow the setup steps. Kinde has dedicated setup guides for Google, GitHub, Microsoft, Apple, and all other supported providers.

For most consumer SaaS products, Google is the one social connection that should be there from day one. For developer tools, add GitHub. For B2B with Microsoft-heavy enterprise customers, add Microsoft.

Configuring a Custom Email Sender

This is not optional if you care about OTP deliverability. By default, Kinde sends OTPs from its own domain. Emails from unknown senders hit spam filters more often than emails from a sender the user's mail system recognizes.

To configure a custom sender, navigate to Settings → Email in your Kinde dashboard.

You can set:

From name: The display name users see in their email client (e.g. "YourApp")
From address: The email address the code comes from (e.g. auth@yourapp.com)

For the custom address to work, you need to verify the domain with Kinde by adding DNS records that Kinde provides. This typically takes a few minutes to propagate. Once verified, all OTPs sent from Kinde will use your domain.

This single change reduces OTP spam classification significantly. Do it before launch.

Setting Per-App and Per-Org Authentication

One of Kinde's most practical capabilities is the ability to set different authentication methods for different applications and different organizations. This matters more than it seems.

Per-App Authentication

Consider a product that has a standard user-facing application and a separate internal admin portal. The user-facing app should use email OTP for maximum conversion and ease. The internal admin portal should use a password (or even enterprise SSO) for tighter control. These are different risk profiles and different user populations.

In Kinde, every authentication method is configured per application via the toggles in the Configure modals you saw earlier. When you navigate to Settings → Authentication and open any method, you toggle it on or off independently for each registered application.

Per-Org Authentication

For B2B products, authentication requirements often differ by customer. An enterprise customer may have strict SSO requirements through Microsoft Entra ID. A startup customer may prefer the simplicity of Google social login. A particularly security-conscious customer may want to require MFA on top of OTP.

In Kinde, navigate to Organizations → select an organization → Authentication to see per-organization authentication overrides.

You can set custom authentication experiences per organization without changing the global defaults for other tenants. This is the right architecture for B2B products where customer requirements vary.

Configuring Attack Protection

Passwordless auth is not magic — OTP-based systems have their own attack surfaces. Without rate limiting and brute-force protection, an attacker could try to enumerate codes or flood your users with OTP requests.

Kinde provides built-in attack protection settings. Navigate to Settings → Security → Attack protection.

The settings you can configure include:

Maximum sign-in attempts: How many failed attempts before the account is temporarily locked
Lockout duration: How long the lockout lasts after the threshold is hit
IP-level throttling: Rate limiting on OTP requests per IP address to prevent OTP flooding

The right settings depend on your user base. A consumer app with millions of casual users needs more lenient lockout settings than a B2B tool with a small, known set of users who all know how to sign in. The defaults are reasonable starting points, but tune them based on your support tickets — if users are getting locked out unexpectedly, loosen the thresholds. If you are seeing OTP abuse, tighten them.

Implementing Passwordless in Your App: The Code Side

Once your Kinde settings are configured, your application needs to handle the authentication flow. Kinde's SDKs abstract away the OTP exchange entirely — you do not build the code-sending, code-verifying, or session-creating logic yourself.

For a Next.js application using Kinde's App Router SDK, passwordless login looks like this:

// app/page.tsx — sign-in page with passwordless entry point
import { LoginLink, RegisterLink } from "@kinde-oss/kinde-auth-nextjs/components";

export default function Home() {
  return (
    <main>
      <h1>Welcome to YourApp</h1>
      <p>Sign in to continue — no password required.</p>

      {/* Kinde handles the entire OTP flow on its hosted auth pages */}
      <LoginLink className="btn btn-primary">
        Sign in
      </LoginLink>

      <RegisterLink className="btn btn-secondary">
        Create account
      </RegisterLink>
    </main>
  );
}

When the user clicks "Sign in", Kinde redirects them to the hosted authentication page where they enter their email, receive their OTP, and complete verification. After successful authentication, Kinde redirects back to your application with a session.

To read the authenticated user's details in a server component:

// app/dashboard/page.tsx — protected page
import { getKindeServerSession } from "@kinde-oss/kinde-auth-nextjs/server";
import { redirect } from "next/navigation";

export default async function Dashboard() {
  const { isAuthenticated, getUser } = getKindeServerSession();

  // Redirect unauthenticated users to the sign-in page
  if (!(await isAuthenticated())) {
    redirect("/api/auth/login");
  }

  const user = await getUser();

  return (
    <div>
      <h1>Dashboard</h1>
      {/* user.given_name, user.email, user.picture are all available */}
      <p>Welcome back, {user?.given_name}.</p>
      <p>Signed in as: {user?.email}</p>
    </div>
  );
}

The route handler that manages the Kinde auth endpoints needs to exist in your project. Create it at app/api/auth/[kindeAuth]/route.ts:

// app/api/auth/[kindeAuth]/route.ts
import { handleAuth } from "@kinde-oss/kinde-auth-nextjs/server";

export const GET = handleAuth();

That single line handles login, logout, callback, and registration routes for your entire Kinde integration. No custom token verification, no session management, no OTP exchange logic — Kinde handles it all.

And the middleware that protects your routes:

// middleware.ts
import { withAuth } from "@kinde-oss/kinde-auth-nextjs/middleware";

export default withAuth(
  async function middleware(req) {
    // Optional: add custom logic using req.kindeAuth
  },
  {
    // Public routes that do not require authentication
    publicPaths: ["/", "/about", "/pricing"],
  }
);

export const config = {
  matcher: [
    "/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)",
  ],
};

With this setup, users who try to access protected routes are automatically redirected to Kinde's passwordless sign-in page. After authenticating with their OTP, they are brought back to the protected page they originally tried to reach.

Testing Your Passwordless Flow

Before going live, run through this checklist:

Test the happy path. Enter a valid email, receive the code, enter it, confirm you land on the right page post-login. Do this in an incognito window to avoid cached sessions.

Test OTP email delivery. Check whether codes arrive promptly (under 10 seconds). Check your spam folder with the default Kinde sender. Then configure your custom sender and check again.

Test code expiry. Wait more than 2 hours without using the code, then try to use it. Confirm the error message is clear and offers a way to get a new code.

Test invalid codes. Enter a wrong code several times. Confirm the error message is clear and the account lockout behaviour matches your attack protection settings.

Test on mobile. Auth flows behave differently on mobile — especially when switching between the email app and the browser. Confirm the redirect back to your app works correctly on iOS and Android.

Test the "Resend code" path. If a user requests a second code, the first code should be invalidated. Confirm this is the case.

Kinde has a dedicated testing section in the docs that covers testing passwordless flows specifically, including test user setup for development environments. Reference the testing documentation at docs.kinde.com before launch.

Passwordless Methods: Comparison

Method	Best for	Requires	Plan
Email + code	Most products, all audiences	Nothing extra	All plans
Phone + code	Mobile-first, SMS-comfortable users	Twilio account	Kinde Pro+
Username + code	Community/dev tools with usernames	Nothing extra	All plans
Social (Google, GitHub, etc.)	Consumer apps, developer tools	Provider app setup	All plans

Conclusion

In this article, you learned why passwordless authentication is worth doing, what separates a good implementation from a frustrating one, and why Kinde deliberately chose OTPs over magic links. You also saw how to enable and configure every passwordless option Kinde supports — email codes, SMS codes, username codes, and social login — along with attack protection, custom email senders, per-app settings, and per-org overrides.

The pattern that actually works is simple: pick the fewest methods that genuinely serve your users, configure custom email sending before launch, write clear error messages, and let Kinde handle the OTP exchange so you can focus on your product.

Passwords are yesterday's problem. Create a free Kinde account today and replace them with an authentication flow your users will actually enjoy.

How to Add Team Collaboration to Your AI-Generated App (v0, Lovable, Bolt, Base44) Without Writing Code

Shola Jegede — Tue, 27 Jan 2026 22:33:47 +0000

You built an app with v0, Lovable, Bolt, or Base44 in minutes. Now your team needs to use it with different access levels. Here is how to add the entire collaboration layer without touching a single line of code yourself.

In this article, you will learn:

Why AI-generated apps ship without user management and what that means for your team
What real multi-user collaboration actually requires under the hood
How to build an AI-powered changelog tool in v0 as the demo app
How to add Kinde auth, protected routes, roles, and organization workspaces through prompts alone
How to test that the collaboration layer actually works

Let's dive in!

What AI Builders Give You and What They Don't

v0, Lovable, Bolt, and Base44 are remarkable. You describe what you want, and in minutes you have a working, deployable application with UI, logic, and routes. This has genuinely changed what one person can ship in an afternoon.

What none of them give you by default is user management. When your AI builder generates an app, everyone who visits the URL sees the same thing. There is no concept of "Alice is an admin and can publish" or "Bob is a viewer and can only read." There are no team workspaces. There is no authentication.

Adding that layer after the fact is where most people get stuck, because it usually means diving into the generated code and understanding how it works, which defeats the whole point.

This article shows you how to do it entirely through prompts, using Kinde for auth, roles, and team management. The demo app is an AI changelog generator, a tool your team can use to turn raw GitHub commits or release notes into polished public changelogs. Admins publish. Members draft. The public reads.

What Real Team Collaboration Requires

Before you prompt anything, being clear on what collaboration actually means in a web app saves a lot of confusion later. Four things need to work together:

Layer	What it means	What Kinde provides
Authentication	Users can sign in and sign out	Login, sign-up, passwordless OTP, social login
Identity	The app knows who is logged in	User object with name, email, ID on every request
Roles	Different users can do different things	Roles (admin, member, viewer) attached to users
Organizations	Users belong to a team workspace	Orgs that group users with isolated data

You need all four for a real product. A lot of AI-generated apps nail authentication but skip the rest, and then wonder why every user sees every other user's data.

Kinde handles all four out of the box, free for up to 10,500 monthly active users, no credit card required.

What You Need Before You Start

A v0.app account. Sign up at v0.app. Free tier available. The prompts in this article are written for v0 but work in Lovable, Bolt, and Base44 with minor adjustments.

A Kinde account. Sign up at kinde.com. Free up to 10,500 monthly active users, no credit card.

Once you have your Kinde account, create an application for your project. Navigate to Settings → Applications → Add application. Give it a name, select Back-end web as the application type, and hit Save.

Then open the application you just created and navigate to View details to grab these values:

KINDE_CLIENT_ID
KINDE_CLIENT_SECRET
KINDE_ISSUER_URL (your Kinde domain, e.g. https://yourapp.kinde.com)

And two you define yourself:

KINDE_SITE_URL where your app runs locally (http://localhost:3000)
KINDE_POST_LOGIN_REDIRECT_URL where users land after login (http://localhost:3000/dashboard)
KINDE_POST_LOGOUT_REDIRECT_URL where users land after logout (http://localhost:3000)

Keep these open in a tab. You will paste them into v0 shortly.

Step #1: Build the Base App in v0

The demo app is an AI changelog generator. Teams paste in raw commit messages or release notes, the app uses an AI model to turn them into readable entries, and admins publish them to a public page.

Open v0.app and use this prompt:

Prompt:

Build an AI changelog generator for software teams. The app should have:

- A landing page with the product name "Changelog" and two buttons: "Sign in" and "Start free"
- A dashboard at /dashboard with:
  - A sidebar with: Dashboard, New Entry, Published, Team, Settings
  - A main area showing a list of changelog entries as cards, each with: version number, title, date, status badge (Draft / Published), and Edit + Delete buttons
- A "New Entry" page at /dashboard/new with:
  - A text area labeled "Paste your commits or release notes"
  - A "Generate with AI" button
  - A title field, version field, and content editor that populates after generation
  - A "Save as draft" and "Publish" button
- A public changelog page at /changelog showing only published entries in clean readable format

Use Next.js App Router with TypeScript. Clean, minimal design. Do not add any authentication yet.

Let v0 generate the app. Once the preview looks right, push it to GitHub using v0's built-in GitHub integration.

Step #2: Wire In Kinde Auth

Now prompt v0 to install Kinde and set up the auth infrastructure. One prompt handles everything.

Prompt:

Add Kinde authentication to this Next.js app using @kinde-oss/kinde-auth-nextjs.

Do the following:
1. Install the package
2. Create the auth route handler at app/api/auth/[kindeAuth]/route.ts using handleAuth from @kinde-oss/kinde-auth-nextjs/server
3. Wrap the root layout in app/layout.tsx with KindeAuthProvider from @kinde-oss/kinde-auth-nextjs/server
4. Create a .env.local file with these placeholder variables:
   KINDE_CLIENT_ID=
   KINDE_CLIENT_SECRET=
   KINDE_ISSUER_URL=
   KINDE_SITE_URL=http://localhost:3000
   KINDE_POST_LOGIN_REDIRECT_URL=http://localhost:3000/dashboard
   KINDE_POST_LOGOUT_REDIRECT_URL=http://localhost:3000
5. No UI changes yet — just the plumbing

Once v0 finishes, click on the Settings button in v0's editor and then go to Environment Variables tab to fill in your actual Kinde values. Do not commit this file to GitHub. It is gitignored by default.

Then add your callback URLs in the Kinde dashboard. Navigate to Settings → Applications → View details → Callback URLs and add:

Allowed callback URL: http://<your_v0_published_url>/api/auth/kinde_callback
Allowed logout redirect URL: http://<your_v0_published_url>

Step #3: Add Login and Sign-Up Buttons

Prompt:

Update the landing page and dashboard to use Kinde auth components.

Do the following:
1. On the landing page (app/page.tsx), replace the "Sign in" button with LoginLink and "Start free" with RegisterLink:

import { LoginLink, RegisterLink } from "@kinde-oss/kinde-auth-nextjs/components";

<LoginLink postLoginRedirectURL="/dashboard">Sign in</LoginLink>
<RegisterLink postLoginRedirectURL="/dashboard">Start free</RegisterLink>

2. In the dashboard sidebar, show the logged-in user's name and email using getKindeServerSession:

import { getKindeServerSession } from "@kinde-oss/kinde-auth-nextjs/server";

const { getUser } = getKindeServerSession();
const user = await getUser();

Show user.given_name and user.email in the sidebar footer.

3. Add a sign-out link at the bottom of the sidebar that links to /api/auth/logout

Step #4: Protect the Dashboard Routes

Right now anyone can navigate directly to /dashboard without logging in. The Kinde middleware fixes this with one file.

Prompt:

Add route protection using Kinde middleware.

Create a file at middleware.ts in the project root with exactly this content:

import { withAuth } from "@kinde-oss/kinde-auth-nextjs/middleware";
export default withAuth;
export const config = {
  matcher: ["/dashboard/:path*"]
};

This automatically redirects any unauthenticated request to /dashboard or any sub-route to the Kinde login page.

Also add an authentication check at the top of app/dashboard/page.tsx:

import { getKindeServerSession } from "@kinde-oss/kinde-auth-nextjs/server";
import { redirect } from "next/navigation";

const { isAuthenticated } = getKindeServerSession();
if (!(await isAuthenticated())) {
  redirect("/api/auth/login");
}

The public /changelog page stays open to anyone. Everything under /dashboard now requires a logged-in user.

Step #5: Add Roles for Admins, Members, and Viewers

This is where the collaboration layer becomes real. Not everyone on the team should be able to publish or delete changelog entries.

First, create the roles in Kinde. Navigate to Roles → Add role and create three:

admin — can publish, edit, delete all entries, and manage team
member — can create and edit drafts, cannot publish or delete
viewer — read-only access to the dashboard

Assign yourself the admin role: navigate to Users → select your user → Roles → assign admin.

Now prompt v0 to use those roles in the UI:

Prompt:

Add role-based access control to the dashboard using Kinde roles.

The roles are: admin, member, viewer. These are configured in the Kinde dashboard.

Do the following:
1. In app/dashboard/page.tsx, get the user's roles:

const { getRoles } = getKindeServerSession();
const roles = await getRoles();
const isAdmin = roles?.some(role => role.key === "admin");
const isMember = roles?.some(role => role.key === "member" || role.key === "admin");

2. On each changelog entry card:
   - Show "Edit" button for admins and members
   - Show "Delete" button only for admins
   - Show "Publish" button only for admins
   - Viewers see no action buttons

3. In the sidebar:
   - Show "New Entry" link for admins and members only
   - Show "Team" link for admins only
   - Viewers see Dashboard and Published only

4. On the "New Entry" page:
   - Show the "Publish" button only for admins
   - Members see "Save as draft" only

Use conditional rendering, not CSS visibility, so the DOM does not contain controls the user cannot access.

Step #6: Add Organization Workspaces

Roles tell your app what a user can do. Organizations tell your app what data they can see. Without organizations, every user shares every changelog entry, which means one company's unreleased changelog is visible to everyone else.

Kinde organizations are isolated team workspaces. Each organization has its own members and its own data.

Kinde allows organization creation by default when is_create_org is passed during sign-up. No dashboard setting needs to change. If you ever want to disable this behaviour, the toggle is at Settings → Environment → Policies → Allow organization creation on sign up.

Prompt:

Update the app to support Kinde organizations as team workspaces.

Do the following:
1. Update the "Start free" RegisterLink on the landing page to create an org on sign-up:

<RegisterLink
  authUrlParams={{ is_create_org: "true" }}
  postLoginRedirectURL="/dashboard"
>
  Start free
</RegisterLink>

2. In app/dashboard/page.tsx, get the current org:

const { getOrganization } = getKindeServerSession();
const org = await getOrganization();
const orgCode = org?.orgCode;

3. Show the organization name (org?.name) at the top of the sidebar above the navigation links so users always know which workspace they are in.

4. Add a "Switch workspace" link below the org name linking to /api/auth/login?prompt=select_account for users who belong to multiple organizations.

5. For all data queries (changelog entries), add a comment: // TODO: filter by orgCode so it is clear where the org scoping goes when a real database is connected.

Step #7: Add the AI Generation Feature

The "Generate with AI" button on the New Entry page should take raw commit messages and return a polished changelog entry. v0 can wire this up using the Vercel AI SDK.

Prompt:

Add AI-powered changelog generation to the New Entry page using the Vercel AI SDK.

Do the following:
1. Install the ai and @ai-sdk/openai packages
2. Create a server action at app/actions/generate.ts:

"use server";
import { generateText } from "ai";
import { openai } from "@ai-sdk/openai";

export async function generateChangelog(rawInput: string) {
  const { text } = await generateText({
    model: openai("gpt-4o-mini"),
    prompt: `You are a technical writer. Convert the following raw commit messages or release notes into a clean, professional changelog entry. Use plain language a non-technical reader can understand. Format it as a short paragraph followed by a bullet list of changes.

Raw input:
${rawInput}

Return only the changelog text, nothing else.`,
  });
  return text;
}

3. On the New Entry page, wire the "Generate with AI" button to call this action with the content of the text area. Show a loading state while generating. Populate the content editor with the result when done.

4. Add OPENAI_API_KEY= to .env.local as a placeholder — I will fill this in.

Putting It All Together

Here is every prompt in sequence and what each one adds:

Prompt	What it built	What Kinde provided
1 — Base app	Changelog dashboard shell	—
2 — Kinde install	Auth route handler, KindeAuthProvider	Session management, JWT
3 — Login UI	LoginLink, RegisterLink, user in sidebar	User identity
4 — Route protection	withAuth middleware	Unauthenticated redirect
5 — Roles	getRoles(), conditional UI rendering	RBAC — admin/member/viewer
6 — Organizations	getOrganization(), org name in sidebar	Team workspace isolation
7 — AI generation	generateChangelog server action	—

Seven prompts. A complete collaboration layer. No hand-written code.

Testing Your Collaboration Layer

Before sharing the app, verify these scenarios work:

Test 1 — Unauthenticated block. Open an incognito window and navigate to /dashboard. You should land on the Kinde login page.

Test 2 — Sign up with workspace. Click "Start free" and complete sign-up. You should land on the dashboard with your organization name visible in the sidebar.

Test 3 — Role-based UI. Sign in as your admin user and confirm you see Publish, Delete, and the Team link. Then change your role to viewer in the Kinde dashboard, refresh, and confirm those controls are gone.

Test 4 — AI generation. Paste a few commit messages into the New Entry page and click "Generate with AI." The content editor should populate with a polished changelog entry.

Test 5 — Workspace isolation. Create a second Kinde user and have them sign up with a different organization name. Log in as user one, create a draft entry. Log in as user two and confirm they cannot see user one's entries.

What Is Next

This article built the collaboration shell. The next steps to make it production-ready:

Connect a real database. Add Convex or Supabase and filter all queries by orgCode from getOrganization(). Every entry and every piece of data scoped to the team that created it.

Add team invites. Use the Kinde Management API to let admins invite colleagues by email directly from the Team settings page.

Make the public changelog live. The /changelog route is already public. Connect it to the published entries in your database and it becomes a real public-facing changelog page for your product.

The auth infrastructure is already in place. Everything else builds on top of it.

Create a free Kinde account if you have not already, and try this on whatever app you are building.

DEV Community: Shola Jegede

How to Add Device Authorization Flow to Your App With Kinde

The Problem With Browser-Based Auth

When to Use the Device Flow

Prerequisites

Step #1: Create a Device and IoT Application in Kinde

Step #2: Understand the Full Flow

Step #3: Request the Device Code

Step #4: Display the Code to the User

Step #5: Poll for the Token

Step #6: Store and Use the Token

Step #7: Validate the Token on Your API

Putting It All Together

Common Mistakes to Avoid

What This Enables

How to Audit Who Did What in Your Multi-Tenant App: Building an Activity Log With Convex and Kinde

The Audit Log Gap That Costs You Enterprise Deals

Why Convex Is the Right Database for Audit Logs

Schema

The auditLog Helper

Pulling Actor Identity From Kinde

Step #1: Call auditLog Inside Your Mutations

Document creation

Document deletion

Member role change

Settings update

Step #2: Query the Activity Log

Step #3: Build the Activity Feed UI

Step #4: Export as CSV for Compliance

Step #5: Guarantee Org Isolation

Testing the System

Common Mistakes to Avoid

What This Enables

What Is Next

How to Use Feature Flags to Safely Roll Out Features in Production With Kinde

Why Feature Flags Exist

How Kinde Feature Flags Work

The Four Flag Types

Step #1: Create a Feature Flag in Kinde

Step #2: Read Flags in a Next.js Application

Step #3: Override Flags Per Environment

Step #4: Override Flags Per Organization for Gradual Rollouts

Step #5: Override Flags Per User for Beta Access

Step #6: Use String Flags for AI Prompt A/B Testing

Step #7: Use Integer Flags for AI Token Limits

Step #8: Use JSON Flags for Complex AI Configurations

Putting It All Together

Flag Naming Conventions

Conclusion

How to Add Enterprise SSO to Your AI App With Kinde: SAML, OIDC, and Beyond

Why Enterprise SSO Is No Longer Optional for AI Apps

SAML vs OIDC: Choosing the Right Protocol

How Kinde Models Enterprise SSO

Step #1: Create an Organization for Your Enterprise Customer

Step #2: Configure a Custom SAML Connection

Step #3: Configure Microsoft Entra ID (Azure AD) SAML

Step #4: Enable IdP-Initiated SSO

Step #5: Set Up Home Realm Discovery for Seamless Login

Step #6: Let Enterprise Customers Configure Their Own SSO

Step #7: Read Enterprise Identity in Your App

Step #8: Suspend an Organization Instantly

Putting It All Together

SAML Troubleshooting Reference

Conclusion

How to Implement RBAC in a Next.js 16 App With Kinde: A Step-by-Step Guide

Prerequisites

What Is RBAC and Why Does It Belong in Auth?

How Kinde's RBAC Model Works

What's New in Next.js 16 That Affects This Tutorial

Step #1: Create a Next.js 16 Project

Step #2: Configure Kinde and Set Environment Variables

Step #3: Set Up the Auth Route Handler

Step #4: Wrap the Root Layout with KindeProvider

Step #5: Protect Routes Using proxy.ts

Step #6: Define Roles and Permissions in Kinde

Step #7: Check Permissions in Server Components

Step #8: Enforce Permissions in Route Handlers

Step #9: Build a Reusable Permission Guard Component

Step #10: Add Sign In and Sign Out

Putting It All Together

The `auditLog` Helper

Step #1: Call `auditLog` Inside Your Mutations

A Note on `use cache` in Next.js 16