DEV Community: Shola Jegede

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.

Terrific! 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.

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.

AI Generated 47% of My Code Last Month. Here's What I Actually Had to Fix (And Why I Didn't Trust It With Auth)

Shola Jegede — Tue, 27 Jan 2026 22:32:54 +0000

It was 3:47 AM when my phone lit up. "Error: Maximum call stack size exceeded." My SaaS app was down. Users were waking up to broken dashboards, and I was staring at a stack trace pointing to code I barely recognized.

Two weeks earlier, I'd been bragging about shipping features 3x faster with v0.app and GitHub Copilot. I'd generated entire components with a single prompt, scaffolded API routes in seconds, built what looked like a production-ready application in a fraction of the usual time. Now, at nearly 4 AM, I was debugging code I hadn't actually written.

The authentication middleware was calling itself recursively under specific edge cases. The AI had generated elegant-looking code that handled 99% of scenarios perfectly. It just created an infinite loop for that remaining 1%.

When I finally resolved the issue and analyzed my codebase, the numbers shocked me: 47% of my code was AI-generated. Not suggested and then heavily modified—actually written by AI tools with minimal changes from me.

This isn't just my story. 41% of all code is now AI-generated, with 76% of developers using or planning to use AI coding tools. But nobody talks about what happens after the code is generated, especially when it comes to security.

Over the past month, I catalogued every bug, every fix, every security hole. What I found falls into five distinct categories, and one critical decision: I chose Kinde for authentication because I refused to let AI touch my security layer.

The Tools and The Numbers

I used v0.app for frontend work and GitHub Copilot for everything else. Both are genuinely impressive. v0's composite pipeline catches errors in real-time. Copilot's autocomplete is exceptionally good at common patterns.

My final codebase: 8,500 lines of code. 4,000 lines came primarily from AI tools. But the distribution reveals what AI is actually good at:

Frontend Components: 65% AI-generated (v0.app)
API Routes: 40% AI-generated (Copilot)
Database Schema: 30% AI-generated (Copilot)
Auth Integration: 20% AI-generated (I wrote the rest myself with Kinde)
Utility Functions: 55% AI-generated (Copilot)

AI excelled at presentational code and struggled with business logic. The closer code got to security, data integrity, or domain-specific rules, the less I trusted AI—and the more dangerous it was to let it write anything unsupervised.

The 5 Categories of Bugs

1. Hallucinations: Code That References Things That Don't Exist

Early in development, Copilot suggested this for user registration:

import { validateEmail, sanitizeInput } from '@utils/email-validator';
import { checkPasswordStrength} from '@security/password-utils';

export function validateRegistrationForm(data: {
  email: string;
  password: string;
  name: string;
}) {
  if (!validateEmail(data.email)) {
    throw new Error('Invalid email address');
  }

  const sanitized = sanitizeInput(data.name);
  const passwordCheck = checkPasswordStrength(data.password);

  if (passwordCheck.score < 3) {
    throw new Error('Password too weak');
  }

  return { email: data.email, name: sanitized, password: data.password };
}

Professional variable names. Clear logic. Proper error handling. One problem: none of those imported functions existed. Not in my project, not in npm, not anywhere.

The research is alarming: a study of 576,000 code samples found 440,445 hallucinated packages. Nearly half a million references to things that don't exist. Worse, malicious actors can create packages with commonly hallucinated names containing malware.

Copilot also suggested Convex had an update method (it's patch) and a db.notifyUser method (complete fiction).

How to spot hallucinations:

IDE warnings are your friend. Investigate every red squiggly line.
If it sounds too convenient, verify it exists.
Before npm install, check the package registry.
Framework-specific methods need double-checking against docs.
Use TypeScript strict mode.

2. Context Blindness: Ignoring Your Architecture

My app used Convex for real-time data synchronization. When I asked v0 to create a task list component, it gave me classic REST-style React with useState, useEffect, manual fetching, and polling for updates every 5 seconds.

But we're using Convex. Here's what it should have been:

"use client";

import { useQuery } from "convex/react";
import { api } from "@/convex/_generated/api";
import { useKindeBrowserClient } from "@kinde-oss/kinde-auth-nextjs";

export function TaskList() {
  const { user } = useKindeBrowserClient();
  const tasks = useQuery(
    api.tasks.getUserTasks,
    user ? { userId: user.id } : "skip"
  );

  if (tasks === undefined) return <div>Loading...</div>;
  if (tasks.length === 0) return <div>No tasks yet.</div>;

  return (
    <div className="space-y-4">
      {tasks.map((task) => (
        <TaskCard key={task._id} task={task} />
      ))}
    </div>
  );
}

No useState, no useEffect, no manual fetching, no polling. Convex's useQuery handles all of that. When data changes, the component automatically re-renders. Simpler, more reliable, less code.

Copilot made similar mistakes with database queries, generating N+1 query problems. With 50 tasks, that's 51 database queries instead of 2.

How to prevent context blindness:

Provide explicit context in prompts
Create a CONVENTIONS.md file documenting your patterns
Use linters to enforce patterns
Build reusable abstractions that enforce conventions

3. "Almost Right": Subtle Logic Flaws

66% of developers say the biggest issue with AI tools is solutions that are almost right, but not quite. The code runs without errors. TypeScript is happy. But there's a logic flaw that only reveals itself under specific conditions.

When I asked Copilot for pagination, it generated code that calculated offsets wrong—page 1 showed items 10-19, not 0-9. It also loaded ALL tasks into memory before slicing, meaning with 10,000 tasks, we're loading all 10,000 to return 10.

Another example: Copilot generated date arithmetic for recurring tasks that worked perfectly for December 1st + 1 month, but January 31st + 1 month = March 3rd because JavaScript's setMonth() handles overflow by rolling into the next month.

The scariest bug was silent data loss. Copilot generated code that replaced an entire preferences object instead of merging it. The mutation succeeded, user got a success message, everything seemed fine—until they opened the app and wondered why their language and timezone settings were gone.

How to catch these:

Test edge cases explicitly (end-of-month, leap years, zero values, empty arrays)
Use property-based testing
Code review with skepticism
Add assertions liberally

4. Security Vulnerabilities: Why I Chose Kinde

This is where I drew the line. 48% of AI-generated code contains security vulnerabilities. After finding my first missing auth check, I made a decision: authentication would be the ONE thing I wouldn't let AI touch.

Here's what Copilot generated for a task deletion endpoint:

// Copilot's security hole
export async function DELETE(
  request: NextRequest,
  { params }: { params: { id: string } }
) {
  try {
    // No authentication check!
    await convex.mutation(api.tasks.deleteTask, {
      taskId: params.id,
    });
    return NextResponse.json({ success: true });
  } catch (error) {
    return NextResponse.json({ error: "Failed" }, { status: 500 });
  }
}

This code works. It deletes tasks. Anyone can call this endpoint and delete any task. No authentication required.

I initially missed two similar endpoints with the same vulnerability. They were exposed for three days before I found them during a security audit. That's when I decided: no more AI-generated auth code.

Why I Chose Kinde (Not AI) for Authentication

After finding security holes in AI-generated auth code, I made a critical decision: authentication would be handled by Kinde, a proven platform that I could trust—not by AI guessing at security patterns.

The moment that sealed it? I asked Copilot to generate middleware for route protection. It gave me code that looked professional but had three subtle vulnerabilities: it cached authentication state incorrectly, didn't handle token refresh, and had a race condition during session validation. These aren't bugs you catch in testing. They're production nightmares waiting to happen.

I chose Kinde because:

1. Pre-built security that AI can't hallucinate

Authentication, authorization, session management, and MFA all handled by Kinde. No AI making up phantom security methods. No missing auth checks. No subtle vulnerabilities that only surface under load.

Kinde provides everything you need out of the box:

OAuth integration (Google, GitHub, Microsoft, etc.)
Multi-factor authentication
Session management with automatic token refresh
Role-based access control
Organization management for B2B apps
Webhooks for user events

Most importantly, Kinde's SDK methods actually exist and do what they claim. When AI suggested getKindeServerSession().validateToken() (which doesn't exist), I could verify against Kinde's docs that the correct pattern is isAuthenticated().

2. Verifiable documentation I could trust

When AI generated incorrect Kinde code, I could verify against real docs. Every method exists. Every pattern works. Here's the correct pattern Kinde documents:

// app/api/tasks/[id]/route.ts - Verified Kinde pattern
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";

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

export async function DELETE(
  request: NextRequest,
  { params }: { params: { id: string } }
) {
  // CRITICAL: Kinde handles auth correctly
  const { getUser, isAuthenticated } = getKindeServerSession();

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

  const user = await getUser();

  try {
    // Pass user ID to Convex for ownership verification
    await convex.mutation(api.tasks.deleteTask, {
      taskId: params.id,
      userId: user.id,
    });

    return NextResponse.json({ success: true });
  } catch (error) {
    console.error("Delete error:", error);
    return NextResponse.json(
      { error: "Failed to delete task" },
      { status: 500 }
    );
  }
}

And the corresponding Convex mutation with authorization:

// convex/tasks.ts - Defense in depth with Convex
import { mutation } from "./_generated/server";
import { v } from "convex/values";

export const deleteTask = mutation({
  args: {
    taskId: v.id("tasks"),
    userId: v.string(),
  },
  handler: async (ctx, args) => {
    // Verify auth at Convex level too
    const identity = await ctx.auth.getUserIdentity();
    if (!identity) {
      throw new Error("Not authenticated");
    }

    // Verify user ID matches
    if (identity.subject !== args.userId) {
      throw new Error("User ID mismatch");
    }

    // Get task to verify ownership
    const task = await ctx.db.get(args.taskId);
    if (!task) {
      throw new Error("Task not found");
    }

    // CRITICAL: Verify ownership
    if (task.userId !== args.userId) {
      throw new Error("Not authorized to delete this task");
    }

    // Only now is it safe to delete
    await ctx.db.delete(args.taskId);
    return { success: true };
  },
});

This implements defense in depth: authentication at the API route level, authorization in the Convex mutation, and ownership verification before deletion. All three layers are necessary—and all three would have been compromised if I'd let AI write them.

3. Seamless integration with my stack

Kinde works perfectly with Convex and Next.js. Setting up the integration took 15 minutes:

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

export async function GET(request: Request, { params }: any) {
  const endpoint = params.kindeAuth;
  return handleAuth(request, endpoint);
}

That's it. One file handles login, logout, callbacks, and token refresh. Compare that to the 200+ lines of auth code Copilot generated that I had to debug.

The client-side integration is equally clean:

// app/tasks/page.tsx - Server-side with Kinde
import { getKindeServerSession } from "@kinde-oss/kinde-auth-nextjs/server";
import { redirect } from "next/navigation";

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

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

  return <TaskListClient />;
}

For client components, Kinde provides a dedicated hook:

// components/UserProfile.tsx - Client-side
"use client";

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

export function UserProfile() {
  const { user, isLoading } = useKindeBrowserClient();

  if (isLoading) return <div>Loading...</div>;
  if (!user) return null;

  return (
    <div>
      <img src={user.picture} alt={user.given_name} />
      <p>{user.email}</p>
    </div>
  );
}

And the Convex integration pattern:

// convex/tasks.ts - Server-side auth helper
async function getAuthUser(ctx) {
  const identity = await ctx.auth.getUserIdentity();
  if (!identity) throw new Error("Not authenticated");
  return identity;
}

export const getUserTasks = query({
  handler: async (ctx) => {
    const user = await getAuthUser(ctx);

    return await ctx.db
      .query("tasks")
      .withIndex("by_user", (q) => q.eq("userId", user.subject))
      .collect();
  },
});

4. Organizations and permissions built-in

My app needed team collaboration features. Copilot generated a custom permission system with 300+ lines of code. It had bugs in role inheritance, missing permission checks in mutations, and no audit trail.

Kinde's organization features handled this in 10 lines:

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

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

  // Kinde handles organization membership automatically
  if (!org) {
    return NextResponse.json(
      { error: "No organization" },
      { status: 403 }
    );
  }

  // Create task within organization context
  await convex.mutation(api.tasks.create, {
    ...body,
    organizationId: org.orgCode,
    userId: user.id,
  });
}

Would AI have generated this correctly? Based on the 48% vulnerability rate and the hallucinations I found, probably not. Kinde gave me production-grade auth I could trust, with patterns I could verify against documentation instead of hoping the AI got it right.

The security incident that never happened:

Two weeks after launch, I ran a security audit. Every auth check was in place. Every permission was verified. Every session was handled correctly. The reason? I didn't trust AI to write security code, and Kinde ensured I didn't have to.

Other vulnerabilities I found in AI-generated code:

Missing input validation (no length checks, no sanitization)
Information disclosure (error handlers exposing stack traces)
IDOR vulnerabilities (trusting client-provided IDs without ownership checks)

Key takeaway: Security vulnerabilities in AI-generated code are systemic, not accidental. Kinde solved this by giving me battle-tested authentication that I didn't have to second-guess at 3:47 AM.

5. Performance Killers: Code That Works But Performs Terribly

AI models optimize for correctness, not efficiency. Copilot loves N+1 queries:

// Copilot's N+1 disaster  
export const getProjectsWithTasks = query({
  handler: async (ctx) => {
    const projects = await ctx.db
      .query("projects")
      .withIndex("by_user", (q) => q.eq("userId", identity.subject))
      .collect();

    // One query for EACH project's tasks
    const projectsWithTasks = await Promise.all(
      projects.map(async (project) => {
        const tasks = await ctx.db
          .query("tasks")
          .filter((q) => q.eq(q.field("projectId"), project._id))
          .collect();
        return { ...project, tasks };
      })
    );

    return projectsWithTasks;
  },
});

With 10 projects, this runs 11 database queries. With 100 projects, 101 queries. During development with 3 test projects, it ran in 50ms. With a realistic dataset of 50 projects, it took 2.5 seconds.

The fix: batch everything into 2 queries and combine in memory using Convex's indexes and proper query patterns.

The Hidden Costs

Beyond bugs, there are costs that accumulate slowly:

Technical Debt: GitClear's 2025 report found duplicated code blocks increased eightfold. I found four different implementations of email validation scattered across my codebase, each slightly different.

Review Burden: Pre-AI, I reviewed 200 lines in 20 minutes. With AI code, that same 200 lines took 40-50 minutes. I had to verify everything was real, check for security issues, assess performance, and ensure consistency.

Learning Impediment: When AI writes the code, you skip the learning process. Three months later, when I needed to modify AI-generated presence tracking code, I realized I didn't understand how it worked. I had working code but no mental model.

What Actually Saved Time

Despite all this, AI saved me massive amounts of time. I shipped in 70 hours what would have taken 120 manually—a 40% time savings.

Where AI excelled:

Boilerplate and scaffolding (80% time savings)
Type definitions (90% time savings)
Test scaffolding (70% time savings)
API route ceremony (75% time savings)

Where human expertise was essential:

Architecture decisions (100% human)
Security implementation (90% human—Kinde handled the rest)
Business logic (85% human)
System integration (80% human)

The Real Math

The Promise: Generate code 3-5x faster.

The Reality: Generate 3-5x faster, but spend 2-3x longer reviewing and fixing. Net result: 30-40% faster overall.

That's still significant—but it's honest math accounting for review time, debugging, refactoring, and the decision to use Kinde instead of trusting AI with authentication.

Five Lessons That Matter Most

AI is a tool for iteration, not generation. Use it for starting points, then iterate with human judgment.
Treat every AI suggestion as a hypothesis. Verify everything—especially authentication, authorization, and business logic.
Security cannot be delegated to AI. Use proven platforms like Kinde. Every security decision requires human review.
Strong engineering practices are your safety net. TypeScript strict mode, linting, testing, and code review are essential with AI code.
Use AI strategically, not universally. Let AI handle boilerplate. Keep architecture, business logic, and security in human hands.

The Path Forward

256 billion lines of AI-generated code have been written as of 2024. The models will improve. But fundamentally, AI pattern-matches against massive datasets. It doesn't understand your business requirements, architectural constraints, or security needs.

The developers who thrive won't be the ones generating the most code. They'll be the ones who know exactly what to delegate to AI and what requires human expertise—or proven platforms like Kinde.

AI generated 47% of my code last month. It helped me ship faster than I could have alone. But every bug I fixed, every security hole I patched with Kinde, every performance optimization I made—those taught me more about software engineering than any AI-generated code could have.

The future isn't "AI writes all the code." It's AI and humans collaborating, each doing what they do best. AI generates patterns. Humans provide judgment. AI creates volume. Humans ensure quality. And platforms like Kinde handle security so you don't have to trust AI with the parts that matter most.

Use AI. But use it wisely. Choose Kinde for auth. Review carefully. Test thoroughly. Ship confidently.

And maybe invest in a better notification sound for your production monitoring.

Ready to build with confidence? Check out Kinde's documentation for production-ready authentication that you can trust—no AI guessing required. And explore Convex's guides for type-safe, real-time databases that integrate seamlessly with Kinde's battle-tested security.

Why Your SaaS Can't Charge Per-Seat Anymore (And What Replaces It)

Shola Jegede — Tue, 27 Jan 2026 22:32:25 +0000

Your biggest customer just emailed. The one paying $5,000/month for 50 seats.

"We're scaling down to 10 seats next month. Your AI assistant automated 40 positions. Reducing our plan to $1,000/month."

You just lost 80% of revenue from your best customer because your product worked too well.

This isn't rare anymore. It's happening every week to SaaS companies that bundle AI features into per-seat pricing. Meanwhile, companies switching to hybrid models are seeing 38% higher revenue growth. The gap between those who adapt and those who don't is widening fast.

Per-seat pricing made perfect sense for twenty years. Value scaled with headcount. Charge $50 per user monthly, serve them for $2, pocket $48 in gross profit per seat. Clean economics that investors loved.

Then AI changed everything. When your customer deploys an AI agent that does the work of five people, they get 5x the value but only pay for one seat. Your revenue drops 80% while their value increases 400%. You've built the classic innovator's dilemma: your best feature destroys your business model.

The costs are worse than anyone expected. 84% of enterprises saw gross margin erosion exceeding 6% from unmetered AI infrastructure costs. Some companies watched margins collapse from 75% to 40% overnight after bundling unlimited AI features. Mid-market enterprises now spend $85,521 monthly on AI, up 36% from 2024, and that number keeps climbing.

When you offer unlimited AI at a flat per-seat price, you're not just being generous. You're creating adverse selection. The customers who choose your "unlimited" plan are precisely the ones who plan to use it heavily. Your pricing model attracts the customers who will destroy your margins.

A document analysis company learned this the hard way. They offered unlimited AI processing at $20/seat. One customer with 100 seats processed 50,000 documents monthly. At $0.08 per document in LLM costs, that's $4,000 in expenses against $2,000 in revenue. They lost $2,000 every month on their "best" customer.

This article walks through the three pricing models that actually work in 2026: pure usage-based, credit-based hybrid, and outcome-based. Then I'll show you exactly how to implement hybrid pricing with Kinde, which handles authentication, billing, metering, and customer portals in one platform.

The Math That Broke Per-Seat Pricing

Let's look at what made per-seat pricing so beautiful, and why AI shattered it.

Traditional B2B SaaS in 2020 had economics that belonged in a textbook. Revenue per seat: $100/month. Cost to serve one additional user: about $2/month. Gross margin: 98%. Scale that to 1,000 customers with 20 seats each and you're looking at $2M in monthly revenue against $40K in costs. Pure profit of $1.96M. Investors poured money into SaaS because the marginal cost of serving another customer was basically zero.

Then you add AI document analysis. Marketing loves it, customers love it, so you bundle it into existing plans as "unlimited AI processing." It becomes your main differentiator.

Here's a typical customer scenario: 50 employees at $100/seat gives you $5,000/month in revenue. Each employee processes 20 documents daily, which means 21,000 documents monthly.

Your cost per document breaks down like this: GPT-4 API call ($0.06), vector database lookup ($0.01), Claude API summary ($0.04), PDF generation ($0.01). Total: $0.12 per document.

Monthly AI costs: 21,000 × $0.12 = $2,520.

Now look at your new economics. Revenue: $5,000/month. Traditional COGS: $100/month. AI COGS: $2,520/month. Your gross margin just dropped to 47.6%.

You went from a 98% margin business to a 48% margin business overnight.

But it gets worse because not all customers use AI features equally. Look at three customers on the exact same plan:

Customer A processes 2,000 documents/month. AI costs: $240. Margin: 95%. Still great.

Customer B processes 21,000 documents/month. AI costs: $2,520. Margin: 48%. Painful but viable.

Customer C processes 85,000 documents/month. AI costs: $10,200. Margin: -104%. You're paying them $5,200 every month to be their customer.

I've seen this play out in real companies. An AI writing assistant charged $50/seat/month for unlimited generation. They expected 500 generations per user monthly. One customer with 30 marketing team members hit 4,200 generations per user. That's 126,000 total generations.

At $0.14 per generation, their monthly AI cost was $17,640. Revenue from that customer: $1,500. They were losing $16,140 every month. Three months later, 18% of their customer base showed similar usage patterns. Revenue was growing 15% month-over-month while margins collapsed from 89% to 31%.

And here's the other problem nobody talks about: AI doesn't just cost more, it also reduces the seats customers need. A customer success platform adds AI ticket resolution. Before: 10 reps handling 300 tickets daily, paying you $750/month. After: AI handles 80% of tickets, they only need 2 reps, paying you $150/month.

The customer saves 80% while maintaining the same service level. You lose $600/month from a customer who's getting more value than ever.

If you haven't audited this yet, run these queries tonight: Your top 10% of customers by AI feature usage. Actual cost to serve them (LLM calls, vector DB, GPU compute). Gross margin per customer.

I guarantee at least 3-5 of your top AI users have negative margins. You're subsidizing them with revenue from other customers.

The solution isn't to remove AI features or limit usage arbitrarily. AI costs are variable and usage-dependent, so your revenue model needs to match. Companies using hybrid pricing models are seeing 21% median growth rates while pure per-seat models are struggling.

The Three Pricing Models That Actually Work

So if per-seat pricing is broken, what replaces it? Three models are working in 2026, each suited for different types of products.

Pure Usage-Based Pricing

The simplest model: you pay for exactly what you consume. No base fees, no seat minimums. Just usage multiplied by a unit price.

Common metrics include API calls per 1,000, tokens processed, compute minutes, outputs generated, or gigabytes processed. Clay built their entire pricing model around this. Their credits directly correlate with costs from underlying data providers. A LinkedIn email lookup costs more credits than a domain lookup because it costs Clay more to provide.

This works well when you're building infrastructure or platforms, selling to developers, usage varies 100x+ between customers, or you have sophisticated technical buyers who understand consumption-based pricing.

The upside: Perfect cost alignment, fair for customers, enables natural product-led growth, and captures all the upside from AI adoption.

The downside: Budget unpredictability scares away some customers, implementation is complex, can slow initial adoption, and requires excellent tooling to pull off well.

Credit-Based Hybrid Pricing

This is where most B2B SaaS companies are landing. You charge a base subscription fee for platform access, then layer on usage-based pricing using credits as the currency.

The structure looks like this: base subscription of $X/month covers platform access, seats, core features, and support. Z credits are included each month. Different actions cost different amounts of credits. If you exceed your included credits, you pay $Y per additional credit.

Out of 500 companies in the PricingSaaS 500 Index, 79 now offer credit models, up from just 35 at the end of 2024. That's 126% year-over-year growth.

Here's a typical setup:

STARTER - $99/month
- 5 seats
- 1,000 credits/month
- Standard features
- Overage: $0.15/credit

PROFESSIONAL - $299/month
- 20 seats
- 5,000 credits/month
- Advanced features
- Overage: $0.12/credit  
- 25% credit rollover

This works well when you're B2B SaaS with AI features, need predictable revenue, customers need budget certainty, you have a mix of light and heavy users, or you're transitioning away from per-seat pricing.

The upside: Predictable base revenue, captures usage upside, psychologically easier for customers than pure usage-based, simpler enterprise sales, and creates natural expansion paths.

The downside: Credits can confuse customers, requires sophisticated metering infrastructure, determining credit valuation is tricky, and you need clear rollover policies.

According to Maxio's 2025 Pricing Trends Report, hybrid models outperformed pure models with a 21% median growth rate.

Outcome-Based Pricing

The most sophisticated model: charge for results, not usage. Instead of charging per seat or per API call, you charge $0.99 per ticket autonomously resolved by AI.

Examples in the wild: customer support at $0.99 per autonomous resolution, sales automation at $50 per qualified meeting booked, content generation at $5 per published article, fraud detection at $0.10 per transaction prevented.

Gartner projected that 30% of enterprise SaaS would incorporate outcome-based components by 2025, up from 15% in 2022. Companies like Intercom and Zendesk are pioneering this shift.

This works well when outcomes are clearly measurable, your AI is mature and reliable (90%+ success rates), you're selling to risk-averse buyers, or the outcome value is 10x+ your delivery cost.

The upside: Perfect value alignment, removes adoption friction, commands premium pricing, enables natural expansion, and creates a strong competitive moat.

The downside: Hard to implement, requires mature AI, contracts get complex, revenue can be volatile, and audit overhead is significant.

For most B2B SaaS companies reading this, credit-based hybrid pricing is your best bet. It balances revenue predictability with fair usage-based pricing, makes sales easier, and gives you clear paths to expand revenue over time.

How to Implement Hybrid Pricing with Kinde

Here's where most founders hit a wall. You need to track usage, manage subscriptions, sync with Stripe, build customer portals, handle feature flags, and somehow keep it all in sync. Most companies end up duct-taping together 3-4 different services.

Kinde built everything you need in one platform: metered features for usage-based billing, fixed charges for base subscriptions, organization-level billing for B2B multi-tenancy, automatic Stripe sync, self-serve customer portals, feature flags tied to billing tiers, and pricing table builders.

You configure it in Kinde's dashboard, and it handles the rest.

Step 1: Define Your Value Metrics

Before you touch Kinde, you need to answer three questions about your AI features.

First: What does your AI actually do? Be specific. Not "AI analysis" but "generates 500-word article from bullet points" or "extracts structured data from invoice PDF" or "analyzes sentiment across 1,000 reviews."

Second: What's the customer value? An article might save 2 hours of writing time, which equals $100+ in value. Invoice extraction saves 15 minutes, maybe $10 in value. You need to understand the time or money your AI saves customers.

Third: What does it cost you? Break down your real infrastructure costs: GPT-4 API calls, Claude API usage, vector database queries, embedding generation, storage. Get specific numbers.

Here's an example from a document intelligence platform:

EXTRACT_TEXT
- Customer value: Saves 5-10 minutes of manual data entry
- Your cost: $0.035
- Credits you charge: 5 credits

SUMMARIZE_SHORT  
- Customer value: Saves 15-20 minutes of reading
- Your cost: $0.19
- Credits you charge: 10 credits

GENERATE_REPORT
- Customer value: Saves 2-3 hours of analysis  
- Your cost: $1.58
- Credits you charge: 50 credits

Target a 70% gross margin minimum. If your average cost per credit is $0.035 and you want 70% margin, you'd charge $0.12 per credit.

Step 2: Set Up Plans in Kinde

In Kinde, you'll create plans that combine fixed charges (your base subscription fees), metered features (AI credits with included allowances and overage pricing), and unmetered features (access gates for premium features).

When you publish plans, Kinde automatically syncs everything to Stripe. You don't touch Stripe's dashboard.

For complete setup instructions, see Kinde's billing setup guide and creating plans documentation.

Step 3: Integrate Kinde Into Your App

Install the Kinde SDK for your stack:

npm install @kinde-oss/kinde-auth-nextjs

Follow the Kinde Next.js SDK documentation for complete setup.

You'll need these environment variables:

KINDE_CLIENT_ID=your_client_id
KINDE_CLIENT_SECRET=your_client_secret
KINDE_ISSUER_URL=https://yourdomain.kinde.com
KINDE_SITE_URL=http://localhost:3000
KINDE_POST_LOGOUT_REDIRECT_URL=http://localhost:3000
KINDE_POST_LOGIN_REDIRECT_URL=http://localhost:3000/dashboard

Step 4: Display Your Pricing Table

Kinde automatically generates pricing tables from your plans. Use the pricing table builder to customize the look and feel, then embed it in your registration flow.

Step 5: Track and Consume Credits

This is where the rubber meets the road. When a user performs an AI action, you need to check their organization's plan, perform the action, then report usage back to Kinde.

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

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

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

  if (!user || !org) {
    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
  }

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

  // Define credit costs per action
  const CREDIT_COSTS = {
    EXTRACT_TEXT: 5,
    SUMMARIZE_SHORT: 10,
    GENERATE_REPORT: 50,
  };

  const creditsNeeded = CREDIT_COSTS[action as keyof typeof CREDIT_COSTS];

  // Perform the AI operation
  const result = await performAIAction(action);

  // Report usage to Kinde via Management API
  await reportUsageToKinde(org.orgCode, creditsNeeded);

  return NextResponse.json({
    success: true,
    result,
    creditsUsed: creditsNeeded,
  });
}

async function reportUsageToKinde(orgCode: string, credits: number) {
  // Kinde Management API: https://docs.kinde.com/kinde-apis/management/
  // Note: You'll need to get the customer_agreement_id from the organization's 
  // billing record in Kinde. This is the unique subscription ID in Stripe.
  // You can fetch this via the Kinde Management API or store it when the org subscribes.

  const response = await fetch(
    `https://yourdomain.kinde.com/api/v1/billing/meter_usage`,
    {
      method: "POST",
      headers: {
        "Authorization": `Bearer ${process.env.KINDE_MANAGEMENT_API_TOKEN}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        customer_agreement_id: "agreement_xxx", // Replace with actual agreement ID
        billing_feature_code: "ai_credits",
        meter_value: credits.toString(),
        meter_type_code: "delta",
      }),
    }
  );

  return response.json();
}

Kinde handles the rest. It tracks usage across billing cycles, calculates overages at the end of each month, and automatically bills customers through Stripe. You don't build credit tracking, billing cycle management, or invoice generation.

Step 6: Gate Features Based on Plan

You'll want to restrict certain features to higher-tier plans. Maybe "Advanced AI" only works for Professional and Enterprise customers.

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

export async function GET() {
  const { getFlag } = getKindeServerSession();
  const hasAdvancedAI = await getFlag("advanced_ai");

  if (!hasAdvancedAI?.value) {
    return Response.json({
      error: "Requires Professional plan",
      upgradeUrl: "/billing",
    }, { status: 403 });
  }

  return Response.json({ success: true });
}

When someone upgrades from Starter to Professional, the advanced_ai flag flips to true instantly. No code deployments, no database migrations, no manual updates.

Step 7: Let Customers Manage Their Own Billing

The last thing you want is a flood of support tickets asking "How do I upgrade?" or "Where's my invoice?" Kinde provides a hosted portal where customers handle everything themselves: subscription management, usage tracking, payment updates, plan changes.

// app/billing/page.tsx
export default function BillingPage() {
  return (
    <a href="https://yourdomain.kinde.com/billing">
      Manage Subscription
    </a>
  );
}

That's it. Link to Kinde's portal and your customers can upgrade, downgrade, update cards, view invoices, and monitor their credit usage without ever contacting support.

For setup instructions, see the self-serve portal documentation.

Step 8: Handle Billing Events with Webhooks

When customers upgrade, downgrade, hit usage limits, or cancel, you need to know about it. Kinde sends webhooks for all major billing events.

// app/api/webhooks/kinde/route.ts
export async function POST(request: Request) {
  const event = JSON.parse(await request.text());

  switch (event.type) {
    case "subscription.updated":
      await handlePlanChange(event.data);
      break;
    case "usage.limit_reached":
      await notifyCustomer(event.data);
      break;
    case "subscription.canceled":
      await handleCancellation(event.data);
      break;
  }

  return Response.json({ received: true });
}

Set up webhooks to trigger emails, update internal dashboards, or flag high-value customer changes for your sales team.

Avoiding Common Pitfalls

I've watched companies implement hybrid pricing dozens of times. Three mistakes keep showing up.

Pitfall 1: Making Credits Too Abstract

Finance teams love credits because they're a clean abstraction. Customers hate them because "50 credits" means nothing until they've used your product for weeks.

Don't just show the number. Show the value:

<button>
  Generate Report
  <span>50 credits • 2% of monthly allowance • ~$150 value</span>
</button>

Build a calculator on your pricing page. "2,500 credits = 250 summaries or 50 reports." Let people see exactly what they're buying.

Pitfall 2: Underestimating Your Costs

Every founder I've talked to underestimates AI costs in the first three months. They price credits based on average usage, then get destroyed by the 95th percentile.

Always add a 40% buffer to your cost calculations:

const calculateCredits = (pessimisticCost: number) => {
  const bufferedCost = pessimisticCost * 1.4;  // 40% safety buffer
  const targetMargin = 0.70;                    // 70% gross margin
  const pricePerCredit = 0.12;

  return Math.ceil(bufferedCost / (pricePerCredit * (1 - targetMargin)));
};

Track your actual costs every week. Not monthly, weekly. LLM pricing changes, usage patterns shift, and new features launch. Adjust your credit prices quarterly based on real data, not assumptions.

Pitfall 3: Unclear Rollover Policies

"Do my credits expire?" is the second most common support question after "How do I upgrade?" Define rollover rules upfront and make them tier-specific:

Starter: No rollover. Credits expire monthly. Clear and simple.
Professional: 25% rollover for one month. Rewards consistent usage without gaming.
Enterprise: 50% rollover with no expiration. Enterprise customers expect flexibility.

Don't make this complicated. Pick clear rules, document them on your pricing page, and stick to them.

Migrating Existing Customers Without Losing Them

Changing pricing on existing customers is how you destroy trust and tank retention. I've seen companies lose 20% of their customer base in a single quarter by forcing immediate migration. Don't do that.

Here are three strategies that actually work.

Strategy 1: Grandfather Existing Customers (12-18 Months)

Let existing customers stay on per-seat pricing. New customers get the hybrid model. At renewal time, offer migration with 90 days notice and clear communication about why.

In Kinde, create two plan groups:

"Legacy Plans" - Hidden from the pricing table, only visible to grandfathered customers
"Current Plans" - Shown to all new signups

This gives you time to prove the new model works, gather data on usage patterns, and build confidence before asking customers to switch.

Strategy 2: Show Them the Math (The "You'll Save Money" Approach)

Run historical usage analysis on each customer. If someone on a $750/month per-seat plan actually uses 1,800 credits/month, show them the numbers:

"Current plan: $750/month. Professional plan: $299 base + $0 overage = $299/month. You save $451/month."

Send personalized emails with their specific numbers. About 60-80% of customers will voluntarily migrate when you can prove they'll save money. The rest are either high users who know hybrid will cost them more, or they just want stability.

Strategy 3: Guarantee No Increase (The Safety Net)

For customers who must migrate, offer a guarantee: "You'll move to the new pricing at your next renewal. If your costs are higher in the first six months, we'll credit you the difference."

Track this via Kinde webhooks and issue manual credits through the Management API when needed. In practice, fewer than 5% of customers ever claim this guarantee, but offering it reduces churn from 15% to under 3%.

The key principle: never surprise customers, never change pricing mid-contract, and always give them a clear path forward.

What's Coming Next

Three trends will reshape SaaS pricing over the next 18 months.

Outcome-based pricing goes mainstream. By mid-2027, expect at least half of AI-native SaaS products to incorporate outcome-based components. The companies building this capability now will have an 18-month head start when customers start demanding it. Start tracking outcomes using Kinde's custom properties on organizations, even if you're not charging for them yet.

The simplicity backlash is coming. As more companies adopt credit models, customers will get fatigued by complexity. Every SaaS tool having its own credit system with different values and rules creates cognitive overhead. The winners will combine usage-based fairness with crystal-clear communication. Make your pricing so simple a finance person can explain it in 30 seconds.

AI cost deflation forces quarterly reviews. Building a top AI model cost $100M in 2022, $5M in 2024, and under $30 in early 2026. As costs drop 90%+ every 18 months, your pricing needs to evolve or you'll be overcharging customers by 10x within two years. Schedule quarterly pricing reviews. Bake this into your roadmap now.

Your Next Steps

Run these queries in your database tonight:

Top 20 customers by revenue
Actual AI infrastructure costs per customer (LLM calls, vector DB, GPU)
Gross margin per customer

If three or more of your top 20 customers are below 40% gross margin, you have an urgent problem. Every month you wait costs you money you'll never recover.

Here's your timeline:

This week: Create a free account at kinde.com. Spend an hour exploring the billing features. See how plans work, how metered features get configured, how the pricing table builder works. Don't try to build anything yet, just understand what's possible.

This month: Design your complete pricing structure. Map every AI action to a credit cost with real numbers from your infrastructure costs. Configure all your plans in Kinde. Connect to Stripe in test mode. Run through the entire customer journey from signup to billing portal to webhook handling.

This quarter: Launch hybrid pricing for new customers only. Keep existing customers on legacy plans with a clear migration timeline. Monitor your margins daily. Watch for patterns in who upgrades, who churns, and who uses way more than you expected.

Per-seat pricing built the SaaS industry for twenty years because it aligned perfectly with how software delivered value. AI fundamentally changed that equation. Value no longer scales with headcount. It scales with outcomes, with processing power, with intelligent work completed autonomously.

The companies that recognize this and adapt will capture enormous value. The companies that stick with per-seat pricing will watch margins erode quarter after quarter while competitors eat their lunch with better-aligned pricing.

Your competitors are already making this transition. The question isn't whether to change, but whether you'll lead or follow.

Start today: kinde.com → billing setup guide.

Build a Production-Ready MCP Server in TypeScript

Shola Jegede — Wed, 15 Oct 2025 22:03:10 +0000

What is the Model Context Protocol (MCP)?

The Model Context Protocol (MCP) is a framework that allows AI assistants like Cursor or Claude to interact with external tools, APIs, and databases. Think of it as a bridge that lets your AI assistant actually do things in the real world: fetch data, update records, process payments, or manage authentication.

With MCP servers, you can:

Handle user authentication and sessions
Work with databases (queries, migrations, CRUD)
Manage billing flows (free tiers, upgrades, subscriptions)
Connect to external APIs (emails, third-party data, integrations)
Bundle multiple tools into a single AI-accessible server

Why Use the MCP Starter Kit?

Building an MCP server from scratch means setting up all of the above — authentication, database connections, billing, APIs, error handling, and deployment pipelines. That’s a lot of moving parts.

The MCP Starter Kit simplifies the process by giving you:

Instant Setup

One command bootstraps an MCP server
Preconfigured authentication with Kinde
Database setup via Neon PostgreSQL
Built-in billing system
Multiple ready-to-go templates (blog, ecommerce, CRM, todo)

Production-Ready Features

Secure auth flows
Database migrations & schema management
Error handling and logging
Rate limiting & security headers
Testing setup out of the box

Developer Experience

TypeScript support
Hot reloading for dev
Cursor AI integration
Deployment-ready config

What You'll Build

By the end of this tutorial, you'll create a complete MCP application with:

Authentication System → User login, registration, and session management
Database Integration → PostgreSQL with automatic schema setup
CRUD Operations → Create, read, update, and delete functionality
Billing System → Freemium model with upgrade flows
AI Integration → Seamless Cursor AI integration
Production Deployment → Ready-to-deploy application

Prerequisites

Before starting, ensure you have:

Node.js 18+ (download)
npm or yarn
Cursor IDE (download)
Git
Basic TypeScript knowledge (helpful but optional)

Setting Up Your Development Environment

Step 1: Install Node.js and npm

node --version
npm --version

If missing, download and install from nodejs.org.

Step 2: Install Cursor IDE

Visit cursor.sh
Download and install Cursor
Sign up for a free account

Step 3: Create Development Accounts

You'll need accounts for:

Neon Database (Free Tier)

Visit neon.tech
Sign up for a free account
Create a new database
Copy your connection string

Kinde.com (Free Tier)

Visit kinde.com
Sign up for a free account
Create a new application
Note your client credentials

Creating Your First MCP Application

Step 1: Generate Your Application

npx mcp-starter-kit

You'll see an interactive prompt:

🚀 MCP Starter Kit
Create MCP applications with authentication, database, and billing

📝 What would you like to name your application? my-awesome-app
📋 Choose your template:
  1. blog      - Blog management system (posts, comments)
  2. ecommerce - E-commerce system (products, orders)
  3. crm       - Customer relationship management (contacts, deals, tasks)
  4. todo      - Simple todo management system

🎯 Enter your choice (1-4): 1
🚀 Creating my-awesome-app with blog template...
✅ Application created successfully!

Step 2: Install Dependencies

npm install

Step3: Understand the Project Structure

Your generated project will have this structure:

my-awesome-app/
├── package.json              # Dependencies and scripts
├── tsconfig.json             # TypeScript configuration
├── .env.example              # Environment template
├── README.md                 # Project documentation
└── src/
    ├── app-config.ts         # Application configuration
    ├── universal-server.ts   # Main MCP server
    ├── setup-db.ts          # Database setup script
    ├── kinde-auth-server.ts  # Authentication server
    └── core/                 # Core MCP modules
        ├── auth/             # Authentication manager
        ├── database/         # Database manager
        ├── server/           # MCP server core
        └── tools/            # Tool factory

A brief explanation of key files:

universal-server.ts → your main MCP server that handles all AI interactions
kinde-auth-server.ts → authentication server for user login/logout
setup-db.ts → database schema creation and migration script
app-config.ts → configuration for your specific application template
core/ → MCP modules

Configuring Authentication with Kinde

Step 1: Set Up Kinde Application

Log into your Kinde dashboard
Create a new application (if you haven’t)
Configure the following settings:

Application Name: Your MCP App
Redirect URLs: http://localhost:3000/callback
Logout URLs: http://localhost:3000

Step 2: Configure Environment Variables

cp .env.example .env

Edit your .env file:

# Kinde Authentication
KINDE_ISSUER_URL=https://your-domain.kinde.com
KINDE_CLIENT_ID=your_client_id
KINDE_CLIENT_SECRET=your_client_secret
JWT_SECRET=super_secret

Setting Up Your Database with Neon

Step 1: Update your .env file

Grab the with the connection string you copied from your Neon console and paste it in your .env file:

# Database Configuration
DATABASE_URL=postgresql://username:password@host:port/database

Your complete .env file should look like this:

# Database Configuration
DATABASE_URL=postgresql://username:password@host:port/database

# Kinde Authentication
KINDE_ISSUER_URL=https://your-domain.kinde.com
KINDE_CLIENT_ID=your_client_id
KINDE_CLIENT_SECRET=your_client_secret

# JWT Configuration
JWT_SECRET=your_super_secret_jwt_key_here

# Server Configuration
NODE_ENV=development
PORT=3000

Step 2: Initialize Database Schema

npm run setup-db

This command will:

Connect to your Neon database
Create all necessary tables
Set up indexes and relationships

Building Your MCP Server

Step 1: Start the server:

npm run dev

Step 2: Start the authentication server:

npm run auth-server

Visit http://localhost:3000 to test the login flow.

Step 3: Understand the MCP Tools

Your MCP server provides these tools:

Authentication Tools:

login → Get authentication URL
save_token → Save authentication token
logout → Log out current user
refresh_billing_status → Check billing status

CRUD Tools (Blog Template):

create_post → Create new blog post
list_posts → List all blog posts
get_post → Get specific blog post
update_post → Update existing post
delete_post → Delete blog post
create_comment → Add comment to post
list_comments → List post comments

Step 4: Integrating with Cursor AI

Create or edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "my-awesome-app": {
      "command": "node",
      "args": ["dist/universal-server.js"],
      "cwd": "/path/to/your/my-awesome-app",
      "env": {
        "DATABASE_URL": "your_database_url",
        "KINDE_ISSUER_URL": "your_kinde_issuer_url",
        "KINDE_CLIENT_ID": "your_kinde_client_id",
        "KINDE_CLIENT_SECRET": "your_kinde_client_secret",
        "JWT_SECRET": "your_jwt_secret"
      }
    }
  }
}

After configuring MCP settings, restart Cursor to load the new configuration.

Step 5: Test AI Integration

In Cursor, you can now use natural language to interact with your MCP application:

"Create a new blog post titled 'Getting Started with MCP' with content about building AI applications"
"List all my blog posts"
"Update the post with ID 1 to change the title to 'Advanced MCP Techniques'"

Understanding the Billing System

The MCP Starter Kit includes a comprehensive billing system:

Free Tier Limits

Each template has configurable free tier limits:

Blog Template:

10 posts (free tier)
50 comments (free tier)
Unlimited reads

E-commerce Template:

5 products (free tier)
10 orders (free tier)
Unlimited customers

Upgrade Flow

Usage Tracking → Automatic tracking of free tier usage
Limit Warnings → Notifications when approaching limits
Upgrade Prompts → Seamless redirect to billing portal
Plan Management → Check current plan and usage

Billing Integration

// Check billing status
const billingStatus = await checkBillingStatus(userId);

// Redirect to upgrade
if (billingStatus.needsUpgrade) {
  return redirectToBillingPortal(userId);
}

Available Templates Deep Dive

Blog Template

Perfect for content creators and writers:

Entities:

Posts - Title, content, author, published date
Comments - Text, author, post relationship

Features:

Rich text content support
Comment moderation
Author management
Publication scheduling

Use Cases:

Personal blogs
Company blogs
Documentation sites
News websites

E-commerce Template

Ideal for online stores and marketplaces:

Entities:

Products - Name, description, price, inventory
Orders - Customer, items, total, status
Order Items - Product, quantity, price

Features:

Inventory management
Order tracking
Customer management
Payment integration

Use Cases:

Online stores
Digital marketplaces
Subscription services
Product catalogs

CRM Template

Perfect for sales teams and businesses:

Entities:

Contacts - Name, email, company, status
Deals - Title, value, stage, contact
Tasks - Description, due date, contact

Features:

Lead management
Sales pipeline
Task automation
Contact segmentation

Use Cases:

Sales teams
Customer support
Lead generation
Business development

Todo Template

Great for personal productivity and task management:

Entities:

Todos - Title, description, completed, due date

Features:

Task prioritization
Due date management
Completion tracking
Category organization

Use Cases:

Personal productivity
Project management
Team coordination
Goal tracking

Advanced Features and Customization

Custom Entity Creation

You can extend any template with custom entities:

// Add a new entity to your template
const customEntity = {
  name: 'custom_entity',
  fields: {
    title: 'string',
    description: 'text',
    created_at: 'timestamp'
  },
  relationships: {
    user_id: 'users.id'
  }
};

Custom MCP Tools

Create custom tools for your specific needs:

// Custom tool example
const customTool = {
  name: 'send_email',
  description: 'Send email to user',
  parameters: {
    to: 'string',
    subject: 'string',
    body: 'string'
  },
  handler: async (params) => {
    // Your custom logic here
    return { success: true };
  }
};

API Rate Limiting

Configure rate limiting for your MCP server:

// Rate limiting configuration
const rateLimitConfig = {
  windowMs: 15 * 60 * 1000, // 15 minutes
  max: 100, // limit each IP to 100 requests per windowMs
  message: 'Too many requests from this IP'
};

Deployment and Production Considerations

Once your MCP server is running locally, the next step is to think about deploying it in a secure and production-ready way. Here are the key areas to cover:

Environment Configuration

Keep separate environment files for development and production.

Development (.env.local):

NODE_ENV=development
DATABASE_URL=your_dev_database_url
KINDE_ISSUER_URL=your_dev_kinde_url

Production (.env):

NODE_ENV=production
DATABASE_URL=your_prod_database_url
KINDE_ISSUER_URL=your_prod_kinde_url

Security Considerations

When moving to production, follow these best practices:

Environment Variables → Never commit secrets or .env files to version control.
HTTPS → Always serve your app over HTTPS in production.
CORS → Configure CORS to only allow requests from your domain.
Rate Limiting → Protect your endpoints from abuse with rate limiting.
Input Validation → Validate all incoming requests to prevent injection attacks.

Deployment Options

There are several ways to host your MCP server. Here are three common approaches:

1. Vercel (Recommended)
Vercel makes deployment easy with automatic builds and scaling.

# Install Vercel CLI
npm i -g vercel

# Deploy your application
vercel --prod

2. Railway
Railway provides a simple GitHub integration:

# Connect your GitHub repository
# Railway will automatically build and deploy your app

3. Docker
For more control, you can containerize your app with Docker:

FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
RUN npm run build
EXPOSE 3000
CMD ["npm", "start"]

Which One Should You Choose?

Option	Pros	Cons
Vercel	Zero-config, fast deploys, free tier, great for TypeScript apps	Less control over server environment
Railway	Easy GitHub integration, supports background jobs	Free tier more limited than Vercel
Docker	Full control, portable across any cloud provider	More setup and maintenance required

For most developers, Vercel is the fastest way to go live. If you want more flexibility or need background jobs, Railway is a good choice. For enterprise-grade control, Docker is the way forward.

Troubleshooting Common Issues

MCP Server Not Detected in Cursor

Symptoms:

Cursor doesn't recognize your MCP server
Tools don't appear in Cursor interface

Solutions:

Check ~/.cursor/mcp.json syntax
Verify environment variables are set
Restart Cursor completely
Ensure MCP server is running
Check Cursor logs for errors

Authentication Issues

Symptoms:

Login redirects fail
Tokens not being saved
Authentication errors

Solutions:

Verify Kinde credentials in .env
Check redirect URLs in Kinde dashboard
Ensure auth server is running on port 3000
Clear browser cookies and try again
Check JWT secret is set correctly

Database Connection Issues

Symptoms:

Database connection errors
Schema creation fails
Query timeouts

Solutions:

Verify Neon database URL
Check database permissions
Run npm run setup-db to create schema
Test connection with npm run test-db
Check network connectivity

Performance Issues

Symptoms:

Slow response times
High memory usage
Timeout errors

Solutions:

Optimize database queries
Add database indexes
Implement caching
Use connection pooling
Monitor resource usage

Best Practices and Tips

Development Workflow

Use Version Control → Always use Git for your projects
Environment Management → Use different environments for dev/staging/prod
Testing → Write tests for your MCP tools
Documentation → Document your custom tools and configurations
Monitoring → Set up logging and monitoring

Security Best Practices

Secrets Management → Use environment variables for all secrets
Input Validation → Validate all inputs from AI and users
Rate Limiting → Implement rate limiting to prevent abuse
Authentication → Always verify user authentication
HTTPS → Use HTTPS in production

Performance Optimization

Database Indexing → Add indexes for frequently queried fields
Connection Pooling → Use connection pooling for database connections
Caching → Implement caching for frequently accessed data
Lazy Loading → Load data only when needed
Monitoring → Monitor performance metrics

AI Integration Tips

Clear Descriptions → Write clear descriptions for your MCP tools
Error Handling → Provide meaningful error messages
Context → Include relevant context in responses
Validation → Validate AI inputs before processing
Logging → Log all AI interactions for debugging

Conclusion and Next Steps

You’ve just built a production-ready AI-Native MCP server in TypeScript using a Starter Kit. Along the way, you added authentication, database integration, billing, and even connected it to Cursor AI.

With this foundation, you can now extend your server with custom tools, new entities, and additional integrations to fit your use case.

Ready to build your own MCP application? Run:

npx mcp-starter-kit

and start experimenting today.

If you found this guide helpful, I’d love your support, check out the MCP Starter Kit GitHub repo and give it a ⭐.

Every star helps others discover the project and keeps me motivated to build more resources for the community.

One Small UX Fix That Actually Helps

Shola Jegede — Mon, 04 Aug 2025 15:00:41 +0000

When I build software, I try to make the app remember things. So the user doesn’t have to do the same stuff over and over.

Most apps reset everything on refresh or when you come back later. That gets annoying fast.

Here’s what I mean:

You click the same tab again
You re-select your filter or sort
You retype the same input or prompt
You toggle dark mode every single time
You expand the same panel again and again

It’s small stuff, but it adds up. And it makes your app feel worse.

Use `localStorage` to remember things

I now save small bits of state in localStorage. Just enough so the app feels more stable and consistent.

Here’s what I usually save:

Last open tab
Dark or light mode
Draft input or prompt
Filters or sort settings
Collapsed/expanded sidebar
Dismissed modals or popups (usually the ones that require immediate action)
Recently used colors
Preview mode (mobile/desktop)
Selected language

Nothing too deep or serious, just the things that help someone continue where they left off.

Example: Save and Load Dark Mode

Here’s a basic example using localStorage to save the dark mode setting:

// Save mode
localStorage.setItem('theme', 'dark'); 

// Load mode
const savedTheme = localStorage.getItem('theme'); 
if (savedTheme === 'dark') {
    document.body.classList.add('dark');
}

Or in React:

useEffect(() => {
    const saved = localStorage.getItem('theme');
    if (saved) {
        setTheme(saved);
        // assume setTheme updates UI
    }
}, []);

const toggleTheme = () => {
    const newTheme = theme === 'dark' ? 'light' : 'dark';
    setTheme(newTheme);
    localStorage.setItem('theme', newTheme);
};

Quick Tips

Only store things that make the app easier to use
Don’t save sensitive info (like auth tokens or personal data)
Give users a way to reset preferences if needed
Use a small wrapper or custom hook if you’re using this a lot

That’s It

This isn’t a big feature. But it makes your app feel smoother. People don’t notice it when it works — they just stop getting annoyed.

If you’re building something people will use more than once, this matters.

What else are you saving with localStorage that improves UX? Drop your own patterns below. I’m always curious what others are doing.

Why Building with Voice Is a UX Design Challenge, Not Just a Tech One

Shola Jegede — Mon, 04 Aug 2025 03:09:13 +0000

When people think about building with voice, they think about hard problems:

Real-time transcription
Latency management
GPT inference pipelines
Audio quality, noise filtering, etc

All valid. All difficult.

But none of them are what truly broke my first version of Learnflow AI, a voice-first tutor platform powered by Vapi.

The real challenge? UX.

Because when your user isn't looking at a screen — when they're speaking instead of typing — you lose most of the affordances we've come to rely on.

No hover states. No tooltips. No loading spinners.

And as I learned the hard way: No clarity.

This is a breakdown of what went wrong when I first shipped a real-time voice app and how I reworked it to be understandable, usable, and even delightful.

Voice Tech Is Easy (When Vapi Handles It)

I built the first version of Learnflow AI over a weekend.

Vapi handled the entire voice loop: speech-in, text-to-GPT, voice-out
Convex tracked sessions, user data, and credits
Kinde managed auth, billing, and plan-based access control

Thanks to Vapi, I didn’t need to stitch together Whisper, GPT-4, ElevenLabs, and a WebSocket architecture. One agent definition and a vapi.start() call handled it all.

Sample flow agent session start:

const assistantOverrides = {
  variableValues: { subject, topic, style },
  clientMessages: ["transcript"],
  serverMessages: [],
};

vapi.start(configureAssistant(voice, style), assistantOverrides)

But that just gave me the plumbing.

It didn’t solve what my users were facing.

What Actually Went Wrong

1. No Clarity on When the Session Was Active

Vapi is fast — the session starts within seconds. But users had no idea.

They’d click "Start Session"...

Then wait.

Then say, "Hello?"

Then say it again.

Why? Because I didn’t give them visual cues.

There was no feedback that their voice was being heard, transcribed, and responded to. For a voice interface, that’s a dealbreaker.

2. Muted Mic Confusion

Vapi offers a setMuted toggle, but I didn't expose that clearly.

One user turned off the mic thinking it was ending the session.

Another forgot it was off and kept talking. Silence.

3. No Transcript = No Confirmation

Even though I was getting real-time transcripts from Vapi, I didn't display them at first.

Result? Users didn’t know what was being heard, understood, or ignored.

They didn’t trust the app.

Before: The Broken Voice UX

How I Fixed It

Voice UI Is Feedback UI

I rebuilt the voice session component from scratch with one goal:

Always show users what’s happening.

Design Fix 1: Real-Time Transcript Feed

As Vapi emits transcript messages, I append them to a rolling transcript UI.

vapi.on('message', (message) => {
  if (message.type === 'transcript' && message.transcriptType === 'final') {
    const newMessage = { role: message.role, content: message.transcript };
    setMessages((prev) => [newMessage, ...prev]);
  }
});

The transcript appears like a conversation thread. This helps users feel heard.

Design Fix 2: Speaking Animation (Lottie)

When the assistant is speaking, I show a wave animation using Lottie.

vapi.on('speech-start', () => setIsSpeaking(true));
vapi.on('speech-end', () => setIsSpeaking(false));

This became the signal for active state.

Users now intuitively know:

When it's listening
When it's thinking
When it's speaking

Design Fix 3: Microphone Toggle That Makes Sense

I added a visible mic toggle button:

<button onClick={toggleMicrophone}>
  {isMuted ? "Mic Off" : "Mic On"}
</button>

Plus a tooltip: "Turn this off if you want silence. Your session continues."

After: Fixed UX Flow

Real User Flow Example

Let’s say Joy signs up for Learnflow AI.

She picks the free plan (10 voice sessions)
Lands on the dashboard and clicks “Start Session”
A Lottie animation appears
She says: “Hey, what’s a HTML?”
Sees: “You: Hey, what’s a HTML?”
Hears: “The Hypertext Markup Language is the standard markup language for documents designed to be…”
Credit drops from 10 → 9 in real-time

Then a nudge appears: “You have 9 sessions left. Upgrade for 100/month.”

She clicks “Upgrade”, gets routed to Kinde’s billing page, and instantly returns as a Pro user.

Convex + Kinde: Infra That Made My App’s UX Better

Convex: Session + Credit Logic

Every time a session begins, I log it in Convex and deduct a credit:

// schema.ts
export const users = defineTable({
  credits: v.number(),
  plan: v.string(),
});

export const sessions = defineTable({
  userId: v.id("users"),
  startedAt: v.number(),
});

// mutation.ts
export const startSession = mutation(async (ctx, args) => {
  const user = await ctx.db.get(args.userId);
  if (!user || user.credits <= 0) throw new Error("Out of credits");

  await ctx.db.insert("sessions", {
    userId: args.userId,
  });

  await ctx.db.patch(args.userId, {
    credits: user.credits - 1,
  });
});

If credits hit 0:

The user is unable to create a new session with Vapi
Full-screen upgrade modal appears

Kinde: Role Gating + Plan Sync

I use Kinde’s hosted pricing page.

After signup, users are assigned free or pro roles via metadata:

const user = await getUser();

let plan: "starter" | "pro" | "plus" = "pro";

const plans = entitlements?.data?.plans ?? [];
console.log("Plans:", plans);

if (plans.some((p: any) => p.key === "pro")) {
  plan = "pro";
} else if (plans.some((p: any) => p.key === "starter")) {
  plan = "starter";
} else if (plans.some((p: any) => p.key === "plus")) {
  plan = "plus";
}

console.log("Plan:", plan);

Then I sync that in Convex for backend enforcement.

Edge Cases I Had to Handle

User hits 0 credits mid-session: Block next attempt with modal
User mutes mic, thinks session is paused. Solution: copy + mic color state
User switches tabs mid-session. Solution: session timer auto-ends after 60s idle
User upgrades mid-session. Solution: full reload refreshes plan + credit count

Final UX Checklist Before Launch

Real-time transcript feed ✅
Visual signal for when assistant is speaking ✅
Sticky credit counter ✅
Mic toggle with explanation ✅
Upgrade nudge after session ✅
Kinde role sync across backend ✅

What I Learned

Building voice is not just about latency and speech quality
Voice-first UX is not like chatbot UX
UX clarity is everything when there are no visual anchors
Trust comes from visibility: show the transcript, show the state
Feedback loops build confidence

And most of all:

If your user isn't sure whether they're being heard, they won't speak again.

Takeaways If You’re Building Voice AI Apps

Don’t launch voice without a feedback loop
Show users their words (transcript)
Show agent activity (Lottie or animation)
Use a backend like Convex to gate usage in real time
Use Kinde's roles to simplify access control
Let something like Vapi handle the hard infra
Don't assume your user will "figure it out" — measure their hesistation and guide them
Build with latency in mind, but design for confidence

Your Turn

Have you tried building voice-first UX?

Did you run into any of these challenges?

Drop a comment, let’s compare notes below.

Written by Shola Jegede, building Learnflow AI

Built with:

Vapi (voice agent abstraction)
Convex (real-time backend)
Kinde (auth + billing)

Late nights, live feedback, and lots of learning.

See you in the comments.

The Unseen Cost of Speed: What I’d change if I rebuilt my AI SaaS today

Shola Jegede — Mon, 04 Aug 2025 00:54:42 +0000

When you build fast, you feel unstoppable. Weekend sprints. Prototype by Friday, live by Sunday. That was my entire approach with Learnflow AI.

And on the surface? It worked.

People signed up. Voice sessions ran smoothly. The tech stack (Next.js + Convex + Kinde + Vapi) held its own.

But a few weeks in, the cracks started to show.

Not in the UI. Not in the feature set.

But underneath.

In the assumptions I baked into my backend. In the flows I hardcoded to get a "demo" feel. In how little room I left for edge cases, upgrades, re-authentications, and returning users.

This is the post I wish I read before shipping that MVP.

It’s not about the speed. It’s about what gets left behind.

How It Started: Learnflow AI in One Weekend

The idea was simple:

Let anyone create a voice-based AI tutor that felt custom and responsive.

Stack

Vapi: voice-to-transcript + agent logic
Convex: backend DB + real-time mutations
Kinde: authentication + hosted pricing page
Next.js App Router: frontend + routes

Within 48 hours, I had it working:

Sign up
Pick plan (via Kinde)
Land on dashboard
Click "Create Tutor"
Click "Start Session"

It worked. Mostly.

What I Didn't See Coming

There’s a cost to optimizing for "works now."

Here were the blind spots that crept up:

1. Onboarding State Wasn't Persistent

I had a stepper for onboarding users through their first tutor creation. It showed once. But if they refreshed or came back later?

They started from scratch.

2. Upgrade Logic Was Too Far Removed

Kinde hosted my pricing table, and plan info was saved to user metadata. But in-app logic had to manually read and check that. I had upgrade prompts that didn’t appear at the right time, or sometimes, not at all.

3. Session Tracking Wasn’t Modular

I tracked session starts and deducted credits... but not always consistently. Retry flows, dropped connections, or users switching devices would cause edge case issues.

How I Fixed It: Layer by Layer

1. Onboarding State Tracking via Convex

Instead of local state or front-end-only logic, I moved onboarding step tracking to the backend.

export const setOnboardingStep = mutation({
  args: { userId: v.id("users"), step: v.string() },
  handler: async (ctx, args) => {
    await ctx.db.patch(args.userId, { onboardingStep: args.step });
  },
});

Now, no matter where a user logs in from, I can:

Resume onboarding
Branch logic based on their last seen step
Trigger upgrade nudges at the right moment

Diagram: Before vs After - Onboarding Flow

2. Credit Enforcement as Middleware

Before:

I checked user credits manually inside button click handlers
Edge cases like double calls or dropped sessions weren’t covered

Now:

I wrapped credit checks inside a dedicated mutation
That mutation runs before any session can start

export const canStartSession = query({
  args: { userId: v.id("users") },
  handler: async (ctx, args) => {
    const user = await ctx.db.get(args.userId);
    const isPro = user?.plan === "pro";
    const hasCredits = user?.credits > 0;
    return isPro || hasCredits;
  },
});

Used in frontend:

const allowed = await api.sessions.canStartSession({ userId });
if (!allowed) return showUpgradeModal();

Diagram: Credit Check Flow

3. Modular Session Tracking

Old pattern:

startSession just updated credits
But didn’t store metadata: which tutor, when, from which device

New pattern:

export const addSession = mutation({
  args: {
    userId: v.id("users"),
    companionId: v.id("companions"),
    timestamp: v.optional(v.string()),
  },
  handler: async (ctx, args) => {
    await ctx.db.insert("sessions", {
      userId: args.userId,
      companionId: args.companionId,
    });
  },
});

This lets me:

See per-user history
Trigger upgrade nudges based on behavior
Visualize usage per tutor

Better Architecture Patterns I Adopted

Feature Flags

Instead of if (user.plan === "pro"), I now use:

function hasFeature(user, feature) {
  if (user.plan === "pro") return true;
  return freePlanFeatures.includes(feature);
}

Cleaner. Easier to maintain. Centralized.

Event Hooks

I wanted better separation between action and reaction.

Instead of hardcoding showUpgradeModal() after every failed session start, I used an event emitter pattern:

events.on("session-blocked", () => {
  showUpgradeModal();
});

That means I can swap UI reactions later without touching business logic.

Composable Logic: Credit + Plan

Rather than spreading plan logic in dozens of places, I now compose it.

function canUseFeature(user, feature) {
  if (user.plan === "pro") return true;
  if (!user.credits || user.credits <= 0) return false;
  return freePlanFeatures.includes(feature);
}

Kinde: What Worked, What Didn't

✅ What Worked

Hosted pricing pages = instant flow
Metadata sync (plan info in session)
Easy plan switching between free and pro

⚠️ What Needed Work

Kinde metadata isn’t real-time (had to sync manually on plan switch)
No built-in usage enforcement
Needed my own gating via Convex queries

Still, Kinde handled the identity layer well. I just had to build the enforcement layer.

What I'd Do Differently (If Starting Today)

Design credit flows from day one
- Users don’t read docs
- If usage isn’t visible, no one upgrades
Track onboarding + session state in backend
- Frontend-only state is fragile
Make upgrade logic reactive, not static
- Trigger prompts based on what users do, not what page they’re on
Modularize credit checks
- Never rely on frontend logic alone
Plan for role-based UI early
- Gating with plan tiers helps prevent overuse

Final Thoughts

MVP speed is great.

But every speed-up becomes a tradeoff you’ll have to clean up.

That’s not a failure. It’s just how startups work.

If you're where I was a few weeks ago:

Launching something fast
Trying to stay lean
Unsure how deep to go in pricing logic

Just remember:

Ship fast, but make space for your future self.

Make credit systems, upgrade prompts, and session enforcement composable.

Make onboarding state persistent.

And make it so that your second-time users aren’t starting from scratch.

Got questions or shipping your own AI MVP?

Drop a comment or DM me. I'm building Learnflow AI in public, powered by Kinde, Convex, Vapi, and lessons like these.

How I Designed a Credit System That Actually Makes Users Upgrade

Shola Jegede — Mon, 04 Aug 2025 00:28:17 +0000

In the first 24 hours after launching Learnflow AI, I was quietly optimistic. Users signed up. Sessions were started. Feedback was decent.

But something felt off.

No one upgraded.

Despite building a clean onboarding flow, embedding Kinde's hosted pricing tables, and giving users 10 free credits to try the platform, conversion sat at 0%.

I didn’t just need a payment integration. I needed a pricing model that matched user behavior — and a credit system that made value feel tangible.

This post is about the system I built, broke, rebuilt, and finally shipped to convert confused trial users into paying customers. It's also about how I used Convex, Kinde, and Vapi to make it all happen.

The Problem With Invisible Usage

When I launched Learnflow AI, I decided to make usage credit-based: 1 session = 1 credit. Every user got 10 free credits. Pro plans included 100/month.

It sounded clean. Scalable. Friendly.

But my first users weren’t behaving like they understood any of it.

Here's what I observed:

Users would start a session, then bounce.
Some never used more than 1 credit.
A few returned days later and seemed surprised that their credits were gone (initially, I made it available for 14 days to ramp up usage).

The credit system existed. It was tracked. But it wasn’t felt.

That’s when I realized:

Abstract usage doesn’t drive upgrades. Visible, valuable usage does.

Step 1: Define Usage as a Business Layer

I built Learnflow AI in a single weekend using:

Convex for backend + real-time reactivity
Kinde for auth + billing logic
Vapi to abstract the entire voice session loop

Credits became the first real business abstraction I needed to enforce.

Convex Schema:

users: defineTable({
  email: v.string(),
  plan: v.optional(v.string()), // 'free' or 'pro'
  credits: v.optional(v.number()),
});

Every time a session started, I ran a mutation:

const creditCost = user.plan === 'pro' ? 0 : 1;
if (user.credits < creditCost) {
  throw new Error('Out of credits. Please upgrade.');
}

await db.patch(user._id, {
  credits: user.credits - creditCost,
});

This enforced usage. But it still didn’t communicate usage.

Step 2: Surface Usage in the UI

The first iteration of Learnflow showed no credit balance. Just a dashboard of public tutors and a "Start Session" button.

Users were flying blind.

So I shipped three changes:

1. Sticky Header Counter

<Badge>Credits Left: {user.credits}</Badge>

This sat in the global header. No tabs. No modals. It was always visible.

2. Session Recap Modal

After each session:

<p>"You've used 1 credit. You have {user.credits} remaining."</p>

3. Tutor Card Labels

<Label>{plan === 'free' ? 'Free Access' : 'Pro Feature'}</Label>

Each of these made the system tangible. Users began associating credits with action.

Step 3: Build Pricing Into the Journey

Kinde handles pricing at the account level. When users signed up, they hit a hosted pricing table.

Flow:

User signs up
→ Lands on Kinde-hosted pricing table
→ Picks plan (Free or Pro)
→ Metadata stored on user
→ Redirect to Learnflow dashboard

I extracted plan and credit info from Kinde like this:

const { profile } = useUserContext();
const { isAuthenticated, getAccessTokenRaw } = useKindeAuth();
const [entitlements, setEntitlements] = useState<EntitlementsData | null>(null);

if (!isAuthenticated) {
  return <div>You are not logged in, please log in.</div>;
}

useEffect(() => {
  const fetchEntitlements = async () => {
    const accessToken = await getAccessTokenRaw();
    try {
      const res = await fetch(`${process.env.NEXT_PUBLIC_KINDE_ISSUER_URL}/account_api/v1/entitlements`, {
        headers: {
          Authorization: `Bearer ${accessToken}`,
        },
        cache: "no-store",
      });
      const data = await res.json();
      console.log("Entitlements payload:", data);
      setEntitlements(data as EntitlementsData);
    } catch (error) {
      console.error("Error fetching entitlements:", error);
    }
  };

  fetchEntitlements();
}, [getAccessTokenRaw]);

let plan: "free" | "pro" = "free";

const plans = entitlements?.data?.plans ?? [];
console.log("Plans:", plans);

if (plans.some((p: any) => p.key === "pro")) {
  plan = "pro";
} else if (plans.some((p: any) => p.key === "free")) {
  plan = "free";
}

console.log("Plan:", plan);

I used this plan field to gate features on the frontend and inside Convex mutations.

But here's the catch:

Once the user is inside the product, they rarely revisit the pricing table on the billing page.

So I brought pricing to them.

Key UX Prompts:

If user is out of credits: full-screen modal with "Upgrade to Pro"
If user clicks a Pro-only tutor: inline modal explaining Pro perks
If user is on their last credit: banner warning them

Flow Diagram: Usage + Upgrade System

Step 4: Handle Edge Cases

A few tricky cases came up once people started returning:

Switching Devices

If a user upgraded on one device but their session still had stale data (cached plan or credits), they'd get blocked incorrectly.

Fix:

Fetched fresh credit/plan info on each app load
Added loading gate to dashboard to ensure correct plan before any session began

Retry After Upgrade

Some users upgraded after hitting 0, then retried but still saw the error modal.

Fix:

On upgrade, re-pulled session from Kinde via a backend sync
Refreshed local state using useEffect hook with plan/credit dependency

What Changed After Shipping

Once I made credit usage visible and value obvious, behavior shifted.

Numbers (first 30 users):

70% used at least 5 credits
Around 30% upgraded to Pro
Zero support tickets asking "What are credits?"

I didn’t add more features.

I made the business logic clearer.

What I Learned

Credits must feel like currency. They’re not abstract limits, they’re fuel to your product.
Upgrades must be contextual. Don’t send users to a billing page. Put the prompt where the pain is.
Metadata isn’t enough. Storing plan = "pro" is easy. Reflecting that in the experience is the work.

A Note on Kinde

Kinde did exactly what I needed:

Hosted signup and pricing table
Stored plan + metadata per user
Role-based gating support in frontend logic

The hosted pricing table alone saved me days.

But the biggest value wasn’t features — it was clarity.

Once pricing and access were defined, the rest was just logic.

Final Thoughts

If you're building an AI product — especially one with per-session cost — you can't afford ambiguous usage.

You need clarity:

When does usage happen?
What do users get?
What happens when it runs out?

Your credit system isn't just backend logic.

It's how you translate value.

Your Turn

If you're launching a usage-based tool:

What’s your model?
What’s your feedback loop?
Where does pricing show up?

Let’s trade notes in the comments.

PS: Want to try Learnflow AI? Drop a comment also, I’ll send you a link to get early access.

Auth and Billing in One API Call: A Pattern Worth Betting On

Shola Jegede — Sun, 03 Aug 2025 16:04:26 +0000

The first real backend decision I made on Learnflow AI wasn’t about speed, performance, or even voice logic.

It was about simplicity.

From the start, I knew two things:

Every user should be on a plan (Free or Pro)
Every plan should define exactly what features the user could access

But here’s the problem: Most tools split these concerns across two completely different services. One API for auth. Another for billing. A third for usage tracking (usually the database). You end up stitching together logic just to answer a question as basic as:

"Can this user start a session right now?"

Learnflow AI isn’t a typical SaaS app. It’s usage-based, voice-powered, and session-restricted. And to make the experience smooth, I didn’t want 5 lookups across 3 APIs.

So I made a bet:

What if billing and access came from the same source of truth?

Why This Matters (Even for Small Teams)

AI apps aren’t just about signing in and clicking around. They come with real costs.

For Learnflow AI, every session spins up a voice assistant. The longer the call, the higher the cost.

So:

Every user needs usage limits
Those limits need to reflect their pricing tier
And the app needs to enforce them in real-time

That meant I had to build a flow that looked like this:

If the auth and billing systems lived separately, this would have been brittle, slow, and error-prone.

So instead, I chose a system that merged them.

The Stack That Let Me Pull This Off

Kinde for both auth and plan metadata (+ usage tracking)
Convex for real-time database to store sessions
Vapi for voice session orchestration

Why Kinde?

Most auth providers return a token and a user ID. That’s it.

Kinde goes further: it lets you store plan info inside the user metadata.

That means when a user logs in, I can:

Show or hide features
Enforce limits
Trigger upgrade prompts

All without hitting a separate billing API.

Walkthrough: One API Call, Full Access Logic

When a user signs in, here’s what happens under the hood:

1. User Picks a Plan on Signup

Kinde supports hosted pricing tables. So when a user signs up, they see:

Free Plan
Pro Plan ($)

Once they select a plan, Kinde adds that to their metadata, which I go on to store into the user’s table in my database.

No need to run a webhook or background sync.

2. Metadata Comes with Every Session

Now, anytime the user logs in, their plan info is bundled in.

So inside Convex, I can write logic like:

export const canStartSession = query({
  args: { userId: v.id("users") },
  handler: async (ctx, args) => {
    const user = await ctx.db.get(args.userId);
    const plan = user.plan;
    const credits = user.credits || 0;

    if (plan === "free" && credits <= 0) {
      return { allowed: false, reason: "out_of_credits" };
    }

    return { allowed: true };
  }
});

That’s it.

One call. Full access check.

What Went Wrong (Before This Pattern)

Mistake 1: Treating Auth and Billing as Separate

My first implementation used a separate billing API and tried to sync plan data into Convex via webhook.

Problems:

Race conditions
Out-of-date plan info
Complex error handling if sync failed

Mistake 2: Not Storing Plan Info in Session

Early users would sign up for Pro, but get treated like Free for a few minutes. Why?

Because the app didn’t read billing metadata until a background sync completed.

Friction. Confusion. Drop-off.

Mistake 3: Hidden Usage Until Failure

Before adding credit counters, users had no idea they were near their limit. So the session would just fail one day.

How I Fixed It

Used Kinde's metadata API as the billing source of truth
Moved plan info into session
Showed credit counters in the UI

UI Changes:

Dashboard header: You have 3 sessions left
Tutor page: This tutor requires Pro
Modal on failure: You're out of credits. Upgrade to continue.

Full Flow

Why This Pattern Scales

Even though Learnflow AI is small today, this access logic will scale to thousands of users.

Why?

No custom billing backend
No race conditions
Every plan decision is portable

Plus, plan upgrades are reflected immediately.

What You Can Steal from This

If you're building an AI app with usage-based pricing:

Choose an auth system that lets you store plan metadata
Use one backend query to decide access
Reflect usage visually, early, and often

Don't treat billing as a separate concern.

It is product logic.

Final Thought

It’s easy to over-engineer early.

You start imagining scale. Edge cases. Payment fails. Rate limits.

But in the first version, users just want to know:

Can I use this?
What am I allowed to do?
What happens when I hit the limit?

If you answer those clearly, you win trust.

That’s what this pattern gave me: clarity by default.

Auth and billing in one call.

A pattern worth betting on.

Built with:

Kinde (Auth + Billing + Metadata + Usage metering)
Convex (Backend)
Vapi (Voice sessions)
Next.js App Router