Forem: Shola Jegede

How to Send Auth Codes via WhatsApp in Your App With Kinde

Shola Jegede — Fri, 15 May 2026 00:38:16 +0000

Your users are in San Francisco, Jakarta, São Paulo, and Sydney. They have WhatsApp open all day. They check it before they check their SMS inbox. When your app sends an OTP to their phone number, it lands in a carrier SMS thread they barely look at. When it lands in WhatsApp, they see it instantly.

In this article, you will learn:

Why WhatsApp OTP delivers better completion rates than SMS in high-penetration markets
How Kinde delivers phone OTPs via WhatsApp when configured, with automatic SMS fallback
What you need before you start: Twilio account, WhatsApp Sender, Kinde Pro
How to configure Twilio Verify with a WhatsApp Sender
How to connect your Twilio account to Kinde
How to enable phone authentication in your Next.js app
How to enable WhatsApp as the delivery channel in Kinde
How to configure SMS as the automatic fallback
How to test the full flow before going live
What to watch for in Africa, South Asia, and Southeast Asia specifically

Let's dive in!

Why WhatsApp OTP Is the Right Choice for Your Market

If your users are in Europe or North America, SMS OTP is a reasonable default. Delivery is reliable, carrier infrastructure is solid, and most users check texts promptly.

If your users are in Nigeria, Kenya, Indonesia, Brazil, India, or the Philippines, the calculation is different. WhatsApp penetration in these markets is near-universal. Users across sub-Saharan Africa and Southeast Asia treat WhatsApp as their primary communication channel. SMS sits behind it, sometimes significantly behind.

The data on this is clear. Twilio has documented that in heavy WhatsApp countries, 20 to 40 percent of users pick the WhatsApp channel when given the option for OTP delivery. More importantly, WhatsApp OTPs arrive over Wi-Fi connections. A user whose cellular data signal is weak but who is on Wi-Fi still receives the WhatsApp message instantly. SMS requires telephony connectivity. In markets where cellular data coverage is more reliable than SMS delivery, WhatsApp is not just more convenient. It is more reliable.

There is also a cost argument. WhatsApp authentication messages cost 50 to 99 percent less than SMS in most markets globally. In developing markets where SMS costs are highest, the savings are largest. At any meaningful scale, the economics strongly favor WhatsApp.

The correct production setup is WhatsApp first with automatic SMS fallback for the minority of users who do not have WhatsApp. That is exactly what Kinde gives you.

How Kinde Handles WhatsApp OTP

Kinde supports phone number as both a primary authentication method and a secondary MFA factor. When phone authentication is configured, Kinde uses Twilio to deliver OTP codes. When you configure a WhatsApp Sender in your Twilio account and connect it to Kinde, Kinde automatically prefers WhatsApp for delivery and falls back to SMS when WhatsApp is unavailable.

This is Twilio's Verify WhatsApp feature working through Kinde's phone authentication layer. You do not write any message-routing logic. Kinde and Twilio handle it. When a user enters their phone number on your sign-in screen, the OTP arrives in their WhatsApp. If they do not have WhatsApp or the delivery fails, Twilio's Verify API automatically retries via SMS.

There are a few important constraints to know before you start:

Kinde Pro is required for production phone authentication. Kinde gives you 10 free SMS test sends per month on any plan to experiment with the feature, but production phone authentication (including WhatsApp) requires upgrading to the Pro plan or above.

The OTP message format is not editable. Kinde uses a standardized SMS/WhatsApp template that complies with OTP best practices. The message arrives as: 123456 is your verification code. followed by For your security, do not share this code. No app name, no URL, no hash. The sender name shown at the top of the WhatsApp chat comes from your registered Twilio business display name, not the message body. You cannot customize the message text or format.

A Twilio business account is required. You cannot use a personal or trial Twilio account for production A2P (Application-to-Person) messaging. You need a Twilio business account with a configured phone number or Messaging Service.

10DLC registration may be required in the US. If your users are in the United States, Twilio requires 10DLC registration for SMS. Check Twilio's guidelines and A2P messaging requirements for your target countries before setting up.

What You Need Before You Start

Before touching the Kinde dashboard, have the following ready:

A Twilio business account with your Account SID and Auth Token from the Twilio Console.

A Twilio phone number or Messaging Service SID. Twilio gives you two options for identifying the sender: a specific phone number or a Messaging Service (a pool of numbers Twilio manages for deliverability). The Messaging Service is recommended for production because Twilio handles number rotation and deliverability automatically.

A WhatsApp Sender configured in Twilio. This is a WhatsApp Business Account (WABA) phone number registered with Meta and approved for authentication message templates. Twilio's Verify WhatsApp documentation walks through this process. You need Meta Business verification and an approved authentication template before WhatsApp delivery works.

A Kinde account on the Pro plan or above.

A Next.js app with the Kinde SDK installed. If you are starting fresh, the Kinde Next.js quickstart at docs.kinde.com gets you to a working auth setup in under ten minutes.

Note: You can complete the Kinde configuration and test with the 10 free SMS sends before completing the WhatsApp Sender setup in Twilio. This lets you verify the Kinde connection is working before adding WhatsApp to the mix.

Step #1: Configure Twilio for Phone and WhatsApp Delivery

Get your credentials. From the Console Dashboard, copy your Account SID and Auth Token. Keep the Auth Token private.

Set up a Messaging Service (recommended) or phone number. If using a Messaging Service, navigate to Messaging → Services → Create Messaging Service. Give it a name, add your sender number to it, and copy the Messaging Service SID.

If using a specific Twilio phone number instead, navigate to Phone Numbers → Manage → Active numbers and copy the phone number in E.164 format (e.g. +12025551234).

Configure the WhatsApp Sender for Verify. This is the step that enables WhatsApp delivery. Navigate to Messaging → Senders → WhatsApp senders in the Twilio Console.

Select Add Sender. You will be prompted to connect a WhatsApp Business Account. This requires:

A Meta Business Account (verified)
A phone number registered as a WhatsApp Business number
An approved WhatsApp authentication message template

Twilio auto-creates the authentication template in supported languages once you complete the WhatsApp Sender setup. The template uses the Copy Code format, which displays the OTP with a button users tap to copy it to their clipboard.

Note: WhatsApp Sender approval from Meta typically takes one to three business days. Plan your timeline accordingly. You can continue with the Kinde setup and test using SMS while waiting for WhatsApp approval.

Step #2: Connect Twilio to Kinde

With Twilio credentials ready, connect them to Kinde.

In your Kinde dashboard, navigate to Settings → Environment → Phone providers.

Enter your Twilio credentials:

Account SID: from your Twilio Console dashboard
Auth Token: from your Twilio Console dashboard
Messaging service SID or Twilio phone number: enter whichever you set up in Step #1

If you want to use a fallback in case the primary Twilio service is interrupted, enable the fallback service option and configure a secondary provider.

Select Save.

Terrific! Kinde can now route phone OTP delivery through Twilio. The WhatsApp channel activates automatically once your WhatsApp Sender is approved in Twilio.

Step #3: Enable Phone Authentication in Kinde

With Twilio connected, turn on phone as an authentication method for your application.

Navigate to Settings → Environment → Authentication. In the Passwordless section, find the Phone tile and select Configure.

In the configuration window, toggle phone authentication on for the applications you want it active for. If you have multiple applications in your Kinde environment, you can enable it selectively per application.

Select Save.

Your sign-in screen now includes a phone number input option alongside the existing email input. Users can choose to sign in with their phone number and receive an OTP instead of entering a password or email code.

Step #4: Enable WhatsApp as the Delivery Channel

With phone authentication active and Twilio connected, the final step is confirming that WhatsApp is set as the preferred delivery channel.

In your Kinde dashboard, navigate to Settings → Environment → Phone providers. In your Twilio configuration, you will see the WhatsApp delivery option.

Enable the WhatsApp delivery option. Once enabled:

Kinde sends the OTP via WhatsApp when the user's phone number is registered with WhatsApp
If WhatsApp delivery fails (user does not have WhatsApp, or the delivery fails for any reason), Twilio's Verify API automatically falls back to SMS
No code changes are needed in your application

The fallback happens silently. Your users do not see an error or need to request a retry. Twilio detects the WhatsApp delivery failure and retries via SMS automatically.

Step #5: Configure Phone Auth as MFA (Optional)

If you want to use WhatsApp OTP as a second factor rather than (or in addition to) a primary authentication method, configure it at the MFA level.

Navigate to Settings → Environment → Multi-factor auth.

In the Additional authentication methods section, toggle on SMS. Per the Kinde docs, the SMS MFA option delivers via WhatsApp when configured, with automatic fallback to SMS. The WhatsApp preference follows from your Twilio configuration in Step #4 automatically.

Set MFA to Yes (mandatory) or Optional depending on your product's security requirements:

Yes: every user is required to set up MFA on first sign-in. For products targeting enterprise customers or handling sensitive data, this is the right default.
Optional: users are prompted to set up MFA but can skip it. They can enable it later from their profile settings.

Note: if your primary authentication method is already phone OTP (email OTP), do not set phone SMS as the secondary MFA factor. Kinde recommends against using the same channel for both primary and secondary factors. If your primary auth is email OTP, use phone SMS or authenticator app for MFA. If your primary auth is phone OTP, use email or authenticator app for MFA.

Select Save.

Step #6: Wire Phone Authentication Into Your Next.js App

Kinde's hosted sign-in screen already includes the phone number input once you enable phone authentication. Your Next.js app does not need code changes to show the phone sign-in option. It appears automatically on the Kinde-hosted auth pages.

However, if you want to pre-fill the phone number for users coming from a known context (for example, users you have invited via phone number), use the login_hint parameter to reduce friction:

// app/api/auth/[kindeAuth]/route.ts
// Standard Kinde auth setup — no changes needed for basic WhatsApp OTP

// For login with pre-filled phone number hint:
// Pass login_hint in the authorization URL when you know the user's phone number
// This skips the phone number entry step

import { handleAuth } from "@kinde-oss/kinde-auth-nextjs/server";
export const GET = handleAuth();

For inviting users with a known phone number and pre-filling the sign-in form:

// components/PhoneInviteButton.tsx
// Pre-fills the phone number on the Kinde sign-in screen
// Useful when you know the user's phone number before they authenticate

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

interface PhoneInviteButtonProps {
  phoneNumber: string; // E.164 format e.g. "+2348012345678"
}

export function PhoneInviteButton({ phoneNumber }: PhoneInviteButtonProps) {
  return (
    <LoginLink
      authUrlParams={{
        // login_hint pre-fills the identity field on the Kinde sign-in screen
        // The user sees their phone number already entered and just confirms it
        login_hint: phoneNumber,
        // connection_id routes directly to phone authentication
        // Skips the method selection screen
        connection_id: "phone",
      }}
    >
      Sign in with phone
    </LoginLink>
  );
}

For protecting API routes on the server, the existing getKindeServerSession approach works identically regardless of whether the user authenticated via email or phone:

// app/api/example/route.ts
// Phone-authenticated users produce the same session as email-authenticated users
// No changes needed to protected route logic

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

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

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

  const user = await getUser();

  // user.phone is populated when the user authenticated via phone number
  // user.email is populated when the user authenticated via email
  // Both may be present if the user has linked both identities

  return NextResponse.json({
    userId: user?.id,
    phone: user?.phone,
    email: user?.email,
  });
}

Amazing!

Step #7: Test the Full WhatsApp OTP Flow

Before going live, test three scenarios in your Kinde non-production environment.

Test 1: WhatsApp delivery to a WhatsApp-registered number

Enter a phone number that is registered with WhatsApp. Kinde should route the OTP through Twilio Verify to WhatsApp. The code arrives in your WhatsApp with your Twilio-registered business name as the sender.

Note: Kinde provides 10 free SMS sends per month for testing. These 10 free sends apply to SMS delivery. WhatsApp delivery tests use your Twilio Verify credits.

Test 2: Automatic SMS fallback

To test the fallback, enter a valid phone number that is not registered with WhatsApp, or temporarily disable WhatsApp in your Twilio account. Twilio Verify should detect the WhatsApp delivery failure and automatically send via SMS. The OTP code is the same in both channels.

Test 3: MFA flow (if configured)

If you have set phone SMS as an MFA factor, sign in with email OTP first. On the second factor screen, Kinde prompts for the phone-based code. Enter your phone number if not already registered, and confirm the WhatsApp delivery.

Country-Specific Notes for African and Southeast Asian Markets

Nigeria and Ghana: WhatsApp penetration is extremely high, above 90 percent of smartphone users. SMS delivery is inconsistent in some areas. WhatsApp OTP is strongly recommended as the primary channel. Twilio's A2P messaging in Nigeria requires pre-registered sender IDs. Check Twilio's Nigeria SMS guidelines before launch.

Kenya, Tanzania, Uganda: WhatsApp is widely used but M-Pesa and other mobile money services mean users are accustomed to SMS-based verification from financial services. WhatsApp OTP delivers a better experience but SMS fallback is particularly important in rural areas.

Indonesia, Philippines, Vietnam: Near-universal WhatsApp (and Line, in some markets) penetration. International SMS is expensive from most providers. WhatsApp OTP delivers significant cost savings at scale here.

India: WhatsApp has over 500 million users. However, Meta has implemented messaging limits for WhatsApp Business in India. Review the current Meta Business Platform limits for Indian traffic before projecting volume. Twilio's documentation covers the current limits.

Brazil: One of the highest WhatsApp penetration rates globally. WhatsApp OTP is effectively the standard for authentication flows built for Brazilian users.

For all markets: always test with real numbers in the target country before launch. Carrier behavior, number formatting requirements (always use E.164 format), and delivery timing vary by region.

Troubleshooting Common Issues

OTP not received via WhatsApp

Check that your WhatsApp Sender is approved in Twilio and that the authentication template is active. An unapproved or suspended sender silently fails delivery. Check Twilio's delivery logs for error codes. Error code 63024 from Twilio means the phone number is not associated with a WhatsApp account and the fallback to SMS should have triggered.

OTP received via SMS instead of WhatsApp

This is the expected behavior when WhatsApp delivery is not available. If you expected WhatsApp delivery but got SMS, check: Is the destination phone number registered with WhatsApp? Is the WhatsApp Sender active and approved in Twilio? Has the user blocked your business sender in WhatsApp?

"You need to enter your Twilio account details" message in Kinde

This appears when Kinde's phone authentication is configured but Twilio credentials have not been saved, or the credentials are invalid. Navigate to Settings → Environment → Phone providers and re-enter your Twilio Account SID and Auth Token.

Users in the United States not receiving SMS

US carriers require 10DLC registration for A2P SMS. If your Twilio account is not 10DLC registered for US traffic, messages to US numbers will fail. Complete 10DLC registration in Twilio before enabling phone authentication for US users.

Phone number formatting errors

Kinde and Twilio both require phone numbers in E.164 format (e.g. +2348012345678 for a Nigerian number). If users enter numbers without country codes, the OTP send will fail. Kinde's hosted sign-in screen includes a country code dropdown to help users format numbers correctly. If you are pre-filling numbers via login_hint, always format them in E.164.

Putting It All Together

Here is a summary of the full setup:

Step	What you do	Where
Twilio business account	Get Account SID, Auth Token, Messaging Service	Twilio Console
WhatsApp Sender	Register WhatsApp Business number with Meta via Twilio	Twilio Console > Verify > WhatsApp Senders
Connect Twilio to Kinde	Enter Twilio credentials	Kinde > Settings > Phone providers
Enable phone auth	Toggle on Phone in Passwordless section	Kinde > Settings > Authentication
Enable WhatsApp delivery	Configure WhatsApp as preferred channel	Kinde > Settings > Phone providers
Configure MFA (optional)	Enable SMS as second factor	Kinde > Settings > Multi-factor auth
Test	3-scenario flow test before going live	Non-production environment

Conclusion

In this article, you connected Twilio Verify to Kinde, registered a WhatsApp Business Sender, enabled phone authentication, and configured WhatsApp as the preferred OTP delivery channel with automatic SMS fallback. Users in markets where WhatsApp dominates now receive their authentication codes in the app they check first, over Wi-Fi when needed, at a fraction of the SMS cost.

The setup is the same for phone as primary auth and as MFA. Once your Twilio credentials are in Kinde and your WhatsApp Sender is approved, the routing is handled entirely by Twilio Verify. Your application code does not change. Kinde issues the same JWT regardless of whether the OTP arrived via WhatsApp or SMS.

Kinde is free for up to 10,500 monthly active users. Phone authentication and WhatsApp OTP require the Pro plan. Create your account at kinde.com and meet your users where they already are.

Why SMS Auth Is Quietly Failing Your Users (And How to Fix It With WhatsApp)

Shola Jegede — Thu, 14 May 2026 12:25:03 +0000

Here is something most developers shipping SMS OTP in 2026 do not want to sit with: the channel they are trusting to verify their users is failing roughly one in ten of them, costing the industry $71 billion per year in fraud, and is actively being legislated out of financial services in the UAE, Philippines, Singapore, Malaysia, and India.

None of this shows up in your dashboard. That is the problem.

SMS OTP failures are quiet. A user who never received their code does not generate an error log. They generate a support ticket, or more likely, they just leave. You see a slightly elevated drop-off at the verification step, you assume it is user error, and you move on. The system is technically working. It is just not working for everyone.

This article is not going to tell you to abandon SMS entirely. For markets with low smartphone penetration or poor data connectivity, SMS is still the right fallback. What it is going to argue is that for the majority of your users in 2026, WhatsApp OTP is a demonstrably better primary channel, SMS has serious and growing structural problems that are not going to self-correct, and switching is neither difficult nor expensive. In fact, it is cheaper.

Let's start with the failure modes you are not seeing.

The Silent Failure Rate You Are Not Measuring

Studies consistently show that 10 to 15 percent of SMS OTPs never reach their intended recipients. The causes compound on each other: carrier filtering, network congestion, DND lists, international routing failures, grey route fraud, and plain old delivery lag that outlasts the OTP expiry window.

None of these show up as errors from your SMS provider's perspective. Twilio, Vonage, and every other SMS gateway report a message as "delivered" the moment a carrier accepts it. What happens between carrier acceptance and the user's phone is invisible to you. A message accepted by a carrier at 11:59pm that arrives at 12:04am after the user has given up and closed the app counts as successfully delivered in your analytics. Your success rate looks healthy. Your signup conversion does not.

The carrier filtering problem is getting worse, not better. Since February 2025, US carriers block 100 percent of unregistered A2P traffic on 10-digit long codes. In 2025, Phone-Check.app found that 23 percent of properly formatted business messages never reach inboxes due to carrier filtering and sender reputation issues alone. These are messages that follow every formatting rule and compliance requirement. They just never arrive.

The pattern is consistent across every market with aggressive spam filtering. India's DLT registration system, the UK's carrier-level filtering, and the US's 10DLC compliance regime are all responses to legitimate spam problems. The side effect is that legitimate OTP delivery gets caught in the same net. Your users pay for that friction.

The Fraud Problem That Is Eating Your OTP Budget

The silent delivery failure is a conversion problem. The fraud problem is a financial one, and it is orders of magnitude larger.

SMS pumping, also known as Artificially Inflated Traffic (AIT) or toll fraud, is a scheme where attackers abuse your OTP endpoint to generate revenue for themselves. The mechanics are straightforward: a fraudster partners with a premium-rate carrier, floods your phone verification form with bot-generated numbers on that carrier's network, and collects a share of the termination fees your SMS provider pays to deliver each message. Your users get nothing. You pay for everything.

The numbers at the industry level are staggering. Messaging fraud losses were $80.5 billion in 2025, projected at $71 billion in 2026. AIT fraud specifically cost brands $1.16 billion in 2023 alone. OTPs now make up approximately 89 percent of all international A2P SMS traffic, which makes your OTP endpoint the single largest attack surface in your entire application.

The most cited concrete example is Twitter. Elon Musk disclosed in 2022 that Twitter was losing approximately $60 million per year to SMS pumping through 2FA flows, driven by collusion with around 390 telecom operators. Twitter eventually cut off SMS-based two-factor authentication entirely. That is not a small company overreacting to a minor fraud problem. That is one of the largest user authentication systems in the world discovering that the default channel was being systematically exploited.

The attack is not hypothetical for smaller teams either. Developers on Reddit and Hacker News regularly report waking up to five-figure surprise invoices after their OTP endpoint was pumped overnight. Most SMS providers will dispute these charges if caught quickly, but not all, and the process is slow and uncertain.

What makes this particularly insidious is that it targets the exact markets where you most want phone verification to work. Africa has the highest density of high-risk SMS pumping markets globally, followed by Asia and the Caribbean. If you are building for Nigerian users, Kenyan users, Indonesian users, these are simultaneously the markets with the highest WhatsApp penetration and the highest SMS fraud risk. You are paying a premium for a channel that is both less reliable and more fraudulent in your target market than the alternative.

The Regulatory Wall That Is Coming

The delivery failures and the fraud are operational problems. The regulatory picture is different. It is structural and permanent.

Central banks and financial regulators around the world have spent the last two years reaching the same conclusion: SMS OTP is not a secure authentication factor for financial services. The policy responses are now binding.

The Philippines Bangko Sentral ng Pilipinas issued Circular No. 1213 in June 2025, requiring banks to "limit the use of authentication mechanisms that can be shared with, or intercepted by, third parties unrelated to the transaction." This directly targets SMS OTP.

The UAE Central Bank issued its directive in June 2025 giving financial institutions until March 2026 to completely eliminate SMS and email OTPs. That deadline has passed. UAE banks have already made the transition.

Singapore's Monetary Authority directed major banks to phase out OTPs for account logins, moving toward digital tokens. Malaysia's Bank Negara directed financial institutions to stop using SMS OTPs to combat rising financial scams. India's Reserve Bank is planning to eliminate SMS OTP for digital payments. FINRA in the United States retired SMS as an acceptable authentication option by July 2025.

These are not future concerns. They are enacted policies in major markets. If you are building fintech, payments, banking, or anything adjacent to financial services and you are still SMS-first in these markets, you are already out of compliance in some of them.

The underlying technical reasoning is consistent across every regulator that has weighed in. SMS does not provide a meaningful possession factor because SIM swapping lets an attacker transfer a phone number to a device they control. SS7 network attacks allow interception of SMS in transit. The channel is unencrypted. A code that can be socially engineered out of the user, intercepted in transit, or accessed by compromising the carrier does not satisfy modern strong customer authentication requirements.

This argument is not going away. The regulatory trajectory for SMS OTP in financial services is one direction.

What WhatsApp Actually Fixes

Before getting into the practical switch, let's be precise about what WhatsApp OTP solves and what it does not.

It fixes delivery reliability. WhatsApp messages achieve 90 to 95 percent open rates within three minutes of delivery. SMS sits at 70 to 80 percent, and that figure includes late deliveries that missed their OTP window. WhatsApp runs over data and Wi-Fi, which in most developing markets is more reliable than SMS carrier routing. A user in Lagos who has weak 2G signal but is connected to a building's Wi-Fi network will receive a WhatsApp OTP instantly and may never receive the SMS equivalent.

It eliminates SMS pumping as an attack vector. WhatsApp OTPs operate through Meta's messaging infrastructure, not through the telecom carrier network that SMS pumping exploits. The revenue-sharing fraud mechanics that make SMS pumping profitable simply do not exist in WhatsApp's system. Switching your OTP delivery to WhatsApp does not require you to implement additional fraud protection against AIT. The attack surface is gone.

It costs substantially less. A US OTP via SMS costs approximately $0.04 via Twilio. The WhatsApp authentication equivalent costs $0.006. That is 85 percent cheaper. An analysis of 219 countries found that 100 percent of countries see at least 44 percent savings when switching from SMS to WhatsApp OTP, and 58 percent of countries see 90 percent or greater savings. At 1 million monthly OTPs, the global-mix cost savings reach approximately $76,000 per month, or over $914,000 per year.

It is end-to-end encrypted. SMS travels over carrier infrastructure in plaintext and is vulnerable to SS7 attacks, SIM swapping, and interception. WhatsApp messages are end-to-end encrypted between Meta's servers and the recipient device. This does not make WhatsApp OTP invulnerable, but it eliminates the class of network-level interception attacks that have been used against SMS.

What it does not fix: WhatsApp requires the user to have the app installed and an active data or Wi-Fi connection. Roughly 5 to 10 percent of your users in most markets will not have WhatsApp. This is why the correct production setup is WhatsApp first with automatic SMS fallback, not WhatsApp as a complete replacement. You keep SMS as the safety net for the minority of users who cannot receive WhatsApp messages. You stop paying SMS rates and accepting SMS fraud risk for the 90 percent who can.

Feature	SMS	WhatsApp
Delivery rate	~65-77%	~95%+
Open rate within 3 min	~20%	~98%
Cost per OTP (US market)	~$0.0079 (Twilio)	~$0.005 (Spur.com)
Cost per OTP (Nigeria/India)	~$0.04	~$0.006 (Spur.com)
End-to-end encryption	❌	✅
Vulnerable to SMS pumping	✅ Yes	❌ No
Vulnerable to SS7 attacks	✅ Yes	❌ No
Wi-Fi delivery	❌	✅
Regulatory pressure	⚠️ Active bans in 6+ markets	✅ Preferred channel

The Developer Counterarguments (And Why They Do Not Hold Up)

Every time this argument comes up, three objections appear. They are worth addressing directly.

"Not all my users have WhatsApp."

This is true. It is also not an argument against WhatsApp OTP. It is an argument for WhatsApp-first with SMS fallback, which is exactly what Twilio Verify's channel selection feature provides. You configure WhatsApp as the primary channel and Twilio automatically falls back to SMS when WhatsApp delivery fails. Your users who do not have WhatsApp get an SMS. Your users who do get WhatsApp. You do not choose one. You choose both, with a preference.

"SMS is simpler to set up."

It was, four years ago. Today the compliance overhead for SMS (10DLC registration in the US, DLT registration in India, Sender ID registration in Nigeria) has made SMS a non-trivial setup in the markets that matter most. WhatsApp Sender setup through Twilio requires Meta Business verification and template approval, which typically takes two to five business days. That is comparable to the time required to complete US 10DLC registration, and you get a cleaner channel on the other side of it.

"WhatsApp is controlled by Meta. That is a single point of failure."

This is a legitimate concern, not a dismissible one. Meta does impose messaging limits, can suspend accounts, and the WhatsApp Business API has had outages. The correct response to this concern is not to avoid WhatsApp but to maintain SMS fallback, which is the recommended setup anyway. A WhatsApp-first, SMS-fallback architecture is more resilient than SMS-only because you have two delivery paths instead of one.

How Kinde Makes This a One-Afternoon Integration

If you are using Kinde for authentication, you do not need to build any of this delivery routing logic yourself. Kinde handles phone OTP delivery through Twilio Verify, and when you configure a WhatsApp Sender in Twilio and connect it to Kinde, the routing is automatic. WhatsApp when available. SMS when not. No code changes.

The setup is three things:

One. Connect your Twilio account to Kinde in Settings → Phone providers. You need your Twilio Account SID, Auth Token, and a Messaging Service SID or phone number.

Two. Register a WhatsApp Sender in Twilio Verify and wait for Meta approval (two to five business days). Once approved, Kinde automatically routes to WhatsApp first.

Three. Enable phone authentication in Settings → Authentication, or SMS as an MFA factor in Settings → Multi-factor auth. The WhatsApp preference follows from the Twilio configuration automatically.

That is the full configuration surface. Kinde gives you 10 free SMS sends per month for testing. Production phone authentication requires the Pro plan. The WhatsApp routing itself uses your Twilio Verify credits, billed at Meta's authentication rates through Twilio.

The OTP message format is standardized by Kinde and cannot be customized. The delivery intelligence, the fallback logic, and the channel selection are all handled by Twilio Verify. Your application code does not change at all. A user who authenticated via WhatsApp OTP produces the same Kinde JWT as a user who authenticated via email OTP. Nothing downstream needs to know which channel was used.

For full setup documentation including Twilio Sender configuration, Next.js SDK integration, and country-specific notes for Nigeria, Kenya, Indonesia, India, and Brazil, see the companion tutorial on dev.to.

The Actual Stakes

Here is the case stated plainly.

You are likely losing 10 to 15 percent of the users who hit your OTP verification step to silent SMS delivery failures. You are paying $0.04 or more per SMS in markets where the WhatsApp equivalent costs $0.006. You are exposed to a fraud vector that cost the industry over $80 billion in 2025 and specifically targets your OTP endpoint. You are using a channel that is being legislated out of financial services in the UAE, Philippines, Singapore, Malaysia, India, and the United States.

The alternative is end-to-end encrypted, operates over Wi-Fi, costs 85 percent less in the US market and more in most developing markets, eliminates SMS pumping as an attack vector, and reaches 2.7 billion active users globally. The fallback to SMS is automatic and handles the minority of users who cannot receive WhatsApp messages.

The switch requires a Twilio account, a two-to-five business day wait for Meta's WhatsApp Sender approval, and a Kinde dashboard configuration that takes about ten minutes.

The users who are quietly failing your verification step are not filing support tickets. They are just not coming back. The fraud attacking your OTP endpoint is not showing up in your error logs. It is showing up in your invoice.

The channel you inherited as the default is not the best available option anymore. It has not been for a while.

Kinde handles authentication, billing, and feature flags in one platform. Phone OTP via WhatsApp and SMS is available on the Pro plan. Free up to 10,500 monthly active users, no credit card required.]

How to Add Free Trials to Your SaaS Without Friction: A Step-by-Step Guide With Kinde

Shola Jegede — Thu, 14 May 2026 11:48:59 +0000

Most SaaS products need free trials. Most free trial implementations are a mess — a trial_expires_at column in the database, a cron job nobody fully trusts, middleware that sometimes runs and sometimes does not, and an upgrade prompt that appears on the wrong page at the wrong moment.

In this article, you will learn:

Why most free trial implementations break down at the edges
How Kinde's billing model works today and the honest state of native trial support
How to use a $0.00 Free plan as a friction-free trial container — no credit card required
How to stamp a trial_start date onto every new user using Kinde Workflows
How to surface that date as a custom claim in the access token so your app never queries a database to check trial status
How to build a useTrialStatus hook that drives every trial-aware UI decision in one place
How to build the upgrade prompt that appears at day 7, day 13, and on expiry
How to transition the user to a paid plan the moment the trial ends — smoothly, with no data loss
How to test the full trial lifecycle without waiting 14 days

Let's dive in!

The Free Trial Problem Nobody Talks About

Free trials are not hard to implement. They are hard to implement correctly. The obvious approach — store a trial end date in your database and check it on every request — works until it does not. The cron job that downgrades expired trial users runs at 3am but the user is in a different timezone. The middleware check runs on API routes but not on the WebSocket connection. The upgrade prompt fires but the user already paid ten minutes ago and the webhook has not processed yet.

The underlying issue is that trial state lives in multiple places — your database, Stripe, your app's middleware — and those places are never perfectly in sync.

The cleaner approach keeps trial state in one place: the Kinde access token. Every time the user makes a request, the token carries their trial_start date and their current plan. Your app reads those claims, computes whether the trial is active, expired, or converted, and acts accordingly. No database query. No sync lag. No cron jobs.

Here is how to build that.

How Kinde Billing Works Today — And One Important Caveat

Before writing a single line of code, one thing needs to be stated clearly: as of mid-2026, Kinde Billing does not have native free trial support built in. The Kinde docs list "support for plan models with free trial periods" as a known limitation that is actively being worked on.

This article does not work around that limitation — it builds a production-grade trial system using the Kinde primitives that exist today: a $0.00 Free plan, custom user properties, Kinde Workflows, and feature flags. The result is a trial system that is arguably more flexible than a built-in trial toggle would be, because you control the logic entirely.

When Kinde ships native trial support, the trial_start workflow and the expiry logic in your app can be replaced with a single plan configuration. The feature-gating code using getBooleanFlag stays exactly the same. The migration will be clean.

Note: everything in this article uses Kinde's non-production environment for setup and Stripe test mode for payments. Do not touch production until you have walked the full flow in test mode.

The Architecture You Are Building

The trial system has four moving parts:

1. A Free plan configured in Kinde Billing with a $0.00 charge, credit card collection disabled, and the trial feature flags attached to it. This is what users land on when they sign up.

2. A Workflow that fires on user post-authentication and stamps a trial_start Unix timestamp onto the user's Kinde property record the first time they authenticate.

3. Token customization that surfaces the trial_start property and the user's current plan flags in the access token, so your app can read trial state without a database lookup.

4. A useTrialStatus hook in your Next.js app that reads those token claims, computes the trial state, and drives every trial-aware UI decision — the countdown banner, the upgrade prompt, the locked feature overlay, and the expired paywall.

Step #1: Create the Free Plan in Kinde Billing

Navigate to Billing → Plans → Add plan.

Configure the plan with these settings:

Name: Free Trial (this is what users see on the pricing table)
Description: 14 days of full Pro access, no credit card required
Key: free_trial (this is how you reference it in code — cannot be changed after publishing)
Plan type: Users (for B2C) or Organizations (for B2B)

After saving the basic details, add a charge. Every plan in Kinde — including free plans — needs at least one charge so it syncs to Stripe correctly.

Select Add charge. Configure it as:

Name: Base subscription fee
Amount: $0.00
Interval: Monthly

Select Save.

Now configure the credit card collection setting. Because this is a free trial plan with a $0.00 charge, Kinde allows you to disable credit card collection. Scroll to the Payment collection section and disable the credit card requirement.

Note: credit card collection can only be disabled for plans with no paid charges. The moment you add a charge above $0.00, Kinde requires card collection. Your Free Trial plan stays at $0.00 for this reason — users sign up without friction and you collect card details only when they upgrade.

Now attach the feature flags that control what trial users can access. Navigate to the Features section of the plan and attach the flags that represent your Pro tier features — things like advanced_analytics, api_access, export_data. These flags will activate automatically for any user on the Free Trial plan.

![Kinde plan features section showing three feature flags attached to the Free Trial plan: advanced_analytics (boolean, true), api_access (boolean, true), export_data (boolean, true). These represent the Pro features users get during the trial]](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/uetjbd1rngmv91tvvu7d.png)

Select Publish to make the plan live. Published plans sync to Stripe automatically.

Terrific! The trial container plan exists. Now stamp the start date.

Step #2: Stamp the Trial Start Date With a Kinde Workflow

Kinde Workflows let you run custom code in response to Kinde events. The trigger you need is user:post_authentication — it fires after a user authenticates and before the token is issued, giving you a window to set properties on the user record.

First, create the custom property that will hold the trial start date. Navigate to Settings → Data management → Properties → Add property.

Configure the property:

Name: Trial start date
Key: trial_start (cannot be changed later)
Type: Single line text (you will store a Unix timestamp as a string)
Private: off — this must be public so you can include it in the access token

Select Save.

Now create the workflow. Kinde Workflows live in your code repository and are synced to Kinde via GitHub. The recommended way to get started is to use the official Kinde workflow base template, which has the correct folder structure already set up.

Navigate to github.com/kinde-starter-kits/workflow-base-template, click the green Use this template button, and select Create a new repository. This creates a repo with the following structure:

kindeSrc/
└── environment/
    └── workflows/
        └── postUserAuthentication/
            └── Workflow.ts

Replace the contents of postUserAuthentication/Workflow.ts with the trial start workflow:

import {
  onPostAuthenticationEvent,
  WorkflowSettings,
  WorkflowTrigger,
  createKindeAPI,
} from "@kinde/infrastructure";

export const workflowSettings: WorkflowSettings = {
  id: "trialStartWorkflow",
  name: "Stamp trial start date",
  failurePolicy: { action: "continue" },
  bindings: {
    "kinde.fetch": {},
  },
  trigger: WorkflowTrigger.PostAuthentication,
};

export default async function Workflow(event: onPostAuthenticationEvent) {
  // Only stamp the trial start on new users — never overwrite existing value
  if (event.context.isExistingUser) {
    return;
  }

  const userId = event.context.user.id;
  const trialStart = Math.floor(Date.now() / 1000).toString();

  // Use the Kinde Management API to set the trial_start property on the user
  const kindeAPI = await createKindeAPI(event);

  await kindeAPI.patch({
    endpoint: `user`,
    params: { id: userId },
    requestBody: {
      properties: {
        trial_start: trialStart,
      },
    },
  });
}

Commit and push the file to your repository. Then in your Kinde dashboard, navigate to Settings → Git repo, connect your repository, select your branch, and hit Sync code. Once the sync succeeds, navigate to Workflows — the "Stamp trial start date" workflow will appear with status Live.

Note: the isExistingUser check is critical. Without it, the workflow would overwrite trial_start on every login, resetting the trial clock each time the user authenticates. The check ensures the timestamp is only written once — on first sign-in.

Note: the isExistingUser check is critical. Without it, the workflow would overwrite the trial_start on every login, resetting the trial clock each time the user authenticates. The check ensures the timestamp is only written once — on first sign-in.

Step #3: Surface Trial State in the Access Token

The trial_start property is now stored on the user record in Kinde. To make it available in the access token without a database query, add it to the token customization settings for your application.

Navigate to Settings → Applications → [your app] → Tokens → Customize on the Access token card.

In the Customize access token dialog, scroll to the Properties section and toggle on trial_start. Select Save.

From this point, every access token issued to your users will contain an application_properties claim with the trial_start value:

{
  "sub": "kp_abc123",
  "email": "user@example.com",
  "feature_flags": {
    "advanced_analytics": { "t": "b", "v": true },
    "api_access": { "t": "b", "v": true },
    "export_data": { "t": "b", "v": true }
  },
  "application_properties": {
    "trial_start": { "v": "1717200000" }
  },
  "iss": "https://yourapp.kinde.com",
  "exp": 1717286400
}

The feature_flags claim carries the Pro features active on the Free Trial plan. The application_properties.trial_start.v claim carries the Unix timestamp of when the trial started. Your app now has everything it needs to compute trial status without touching the database.

Amazing!

Step #4: Build the `useTrialStatus` Hook

This hook is the single source of truth for trial state in your React app. Every trial-aware component — the countdown banner, the upgrade prompt, the feature gate, the expired paywall — reads from this hook.

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

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

const TRIAL_LENGTH_DAYS = 14;
const TRIAL_LENGTH_SECONDS = TRIAL_LENGTH_DAYS * 24 * 60 * 60;

export type TrialStatus =
  | "active"      // Trial is running, days remain
  | "expiring"    // Trial has 3 or fewer days left
  | "expired"     // Trial ended, user has not upgraded
  | "converted";  // User is on a paid plan

export interface TrialState {
  status: TrialStatus;
  daysRemaining: number;
  trialStartDate: Date | null;
  trialEndDate: Date | null;
  isPro: boolean;
}

export function useTrialStatus(): TrialState {
  const { getClaim, getBooleanFlag } = useKindeBrowserClient();

  // Read trial_start from the application_properties claim
  // The value is a Unix timestamp stored as a string
  const trialStartClaim = getClaim("application_properties", "access_token");
  const trialStartRaw = (trialStartClaim?.value as any)?.trial_start?.v;
  const trialStartSeconds = trialStartRaw ? parseInt(trialStartRaw, 10) : null;

  // Read feature flags to determine if the user has Pro access
  // These flags are active on both the Free Trial plan and the paid Pro plan
  const hasAdvancedAnalytics = getBooleanFlag("advanced_analytics", false);
  const hasApiAccess = getBooleanFlag("api_access", false);

  // A user is "Pro" if they have the paid plan flags active
  // When the Free Trial expires, these flags go false unless they upgrade
  // Note: during the trial, these are also true — so use trial state to distinguish
  const hasPlanAccess = hasAdvancedAnalytics && hasApiAccess;

  if (!trialStartSeconds) {
    // No trial_start means this is a legacy user or the workflow has not run yet
    // Treat as expired to avoid unintended access
    return {
      status: "expired",
      daysRemaining: 0,
      trialStartDate: null,
      trialEndDate: null,
      isPro: hasPlanAccess,
    };
  }

  const now = Math.floor(Date.now() / 1000);
  const trialEndSeconds = trialStartSeconds + TRIAL_LENGTH_SECONDS;
  const secondsRemaining = trialEndSeconds - now;
  const daysRemaining = Math.max(0, Math.ceil(secondsRemaining / 86400));

  const trialStartDate = new Date(trialStartSeconds * 1000);
  const trialEndDate = new Date(trialEndSeconds * 1000);

  // If the user has Pro feature flags active AND the trial has expired,
  // they have upgraded — they are a paying customer
  if (hasPlanAccess && secondsRemaining <= 0) {
    return {
      status: "converted",
      daysRemaining: 0,
      trialStartDate,
      trialEndDate,
      isPro: true,
    };
  }

  if (secondsRemaining <= 0) {
    return {
      status: "expired",
      daysRemaining: 0,
      trialStartDate,
      trialEndDate,
      isPro: false,
    };
  }

  if (daysRemaining <= 3) {
    return {
      status: "expiring",
      daysRemaining,
      trialStartDate,
      trialEndDate,
      isPro: true,
    };
  }

  return {
    status: "active",
    daysRemaining,
    trialStartDate,
    trialEndDate,
    isPro: true,
  };
}

Note: the hook reads application_properties from the access token. The Kinde browser client's getClaim method defaults to reading from the access token, which is what you want here. The getBooleanFlag method also reads from the token — no network request is made.

Step #5: Build the Trial UI Components

With the useTrialStatus hook in place, build the UI components that surface trial state to users.

The Trial Banner

This sits at the top of the dashboard and counts down the remaining days. It changes color and urgency as the trial approaches expiry.

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

import { useTrialStatus } from "@/hooks/useTrialStatus";
import { RegisterLink } from "@kinde-oss/kinde-auth-nextjs/components";

export function TrialBanner() {
  const { status, daysRemaining } = useTrialStatus();

  // Do not show the banner for converted users or when there is no trial data
  if (status === "converted" || status === "expired") return null;

  const isUrgent = status === "expiring";

  return (
    <div
      className={`w-full px-4 py-2 text-sm font-medium text-center flex items-center justify-center gap-4 ${
        isUrgent
          ? "bg-red-50 text-red-700 border-b border-red-200"
          : "bg-blue-50 text-blue-700 border-b border-blue-200"
      }`}
    >
      <span>
        {isUrgent
          ? `Your trial expires in ${daysRemaining} day${daysRemaining !== 1 ? "s" : ""}. Upgrade to keep your access.`
          : `${daysRemaining} days left in your free trial.`}
      </span>
      <RegisterLink
        planInterest="pro_monthly"
        className={`px-3 py-1 rounded text-xs font-semibold ${
          isUrgent
            ? "bg-red-600 text-white hover:bg-red-700"
            : "bg-blue-600 text-white hover:bg-blue-700"
        }`}
      >
        Upgrade now
      </RegisterLink>
    </div>
  );
}

The Expired Paywall

When the trial ends, replace the dashboard content with an upgrade prompt. Users can still access their data — they just cannot take action until they upgrade.

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

import { useTrialStatus } from "@/hooks/useTrialStatus";
import { RegisterLink } from "@kinde-oss/kinde-auth-nextjs/components";

interface TrialExpiredPaywallProps {
  children: React.ReactNode;
}

export function TrialExpiredPaywall({ children }: TrialExpiredPaywallProps) {
  const { status, trialEndDate } = useTrialStatus();

  if (status !== "expired") {
    // Trial is active or user has converted — show the content normally
    return <>{children}</>;
  }

  const endDateFormatted = trialEndDate
    ? trialEndDate.toLocaleDateString("en-US", {
        month: "long",
        day: "numeric",
        year: "numeric",
      })
    : "recently";

  return (
    <div className="relative">
      {/* Blur the underlying content so users can see what they are missing */}
      <div className="pointer-events-none select-none blur-sm opacity-40">
        {children}
      </div>

      {/* Paywall overlay */}
      <div className="absolute inset-0 flex items-center justify-center">
        <div className="bg-white rounded-xl shadow-xl border border-gray-200 p-8 max-w-md w-full mx-4 text-center space-y-4">
          <div className="text-2xl font-bold text-gray-900">
            Your trial ended on {endDateFormatted}
          </div>
          <p className="text-gray-500 text-sm">
            Your data is safe. Upgrade to Pro to get back to work.
          </p>

          <RegisterLink
            planInterest="pro_monthly"
            className="block w-full py-3 px-6 bg-black text-white rounded-lg font-semibold text-sm hover:bg-gray-800 transition-colors"
          >
            Upgrade to Pro
          </RegisterLink>

          <p className="text-xs text-gray-400">
            No setup required. Your account picks up exactly where you left off.
          </p>
        </div>
      </div>
    </div>
  );
}

The Feature Gate

For features that are available during the trial but locked on a free-forever tier, use this gate to show an upgrade prompt in context rather than a full-page paywall.

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

import { useTrialStatus } from "@/hooks/useTrialStatus";
import { RegisterLink } from "@kinde-oss/kinde-auth-nextjs/components";

interface FeatureGateProps {
  feature: string;
  children: React.ReactNode;
}

export function FeatureGate({ feature, children }: FeatureGateProps) {
  const { isPro, status } = useTrialStatus();

  if (isPro) {
    return <>{children}</>;
  }

  return (
    <div className="relative rounded-lg border border-gray-200 p-6">
      <div className="pointer-events-none select-none blur-sm opacity-40">
        {children}
      </div>
      <div className="absolute inset-0 flex items-center justify-center rounded-lg bg-white/80">
        <div className="text-center space-y-2 px-4">
          <p className="text-sm font-semibold text-gray-900">
            {feature} is a Pro feature
          </p>
          {status === "expired" ? (
            <RegisterLink
              planInterest="pro_monthly"
              className="inline-block px-4 py-2 bg-black text-white rounded-md text-xs font-medium"
            >
              Upgrade to unlock
            </RegisterLink>
          ) : (
            <p className="text-xs text-gray-500">
              Available during your trial — upgrade to keep access after it ends.
            </p>
          )}
        </div>
      </div>
    </div>
  );
}

Putting the Components Together

Use all three in your dashboard layout:

// app/dashboard/layout.tsx
import { TrialBanner } from "@/components/TrialBanner";
import { TrialExpiredPaywall } from "@/components/TrialExpiredPaywall";

export default function DashboardLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <div className="min-h-screen flex flex-col">
      {/* Trial countdown banner — hidden when converted or expired */}
      <TrialBanner />

      <main className="flex-1">
        {/* Paywall wraps all dashboard content — activates only on expiry */}
        <TrialExpiredPaywall>{children}</TrialExpiredPaywall>
      </main>
    </div>
  );
}

For individual features, wrap the component with FeatureGate:

// app/dashboard/analytics/page.tsx
import { FeatureGate } from "@/components/FeatureGate";
import { AdvancedAnalyticsDashboard } from "@/components/AdvancedAnalyticsDashboard";

export default function AnalyticsPage() {
  return (
    <div className="p-6">
      <h1 className="text-xl font-semibold mb-4">Analytics</h1>
      <FeatureGate feature="Advanced Analytics">
        <AdvancedAnalyticsDashboard />
      </FeatureGate>
    </div>
  );
}

Step #6: Handle the Upgrade — Moving From Trial to Paid

When a trial user clicks "Upgrade to Pro," they go through Kinde's hosted payment flow via the RegisterLink component with planInterest="pro_monthly". After payment, Kinde switches the user's plan from free_trial to pro_monthly.

Two things happen in your app automatically:

First, the feature flags attached to the Pro plan remain active. The advanced_analytics, api_access, and export_data flags do not disappear — they continue to resolve as true because they are also attached to the Pro plan. The user notices no change in what they can access.

Second, the useTrialStatus hook detects that the trial has ended but the plan flags are still active, and returns status: "converted". The paywall never appears. The banner disappears.

On the server side, Kinde fires a webhook when the subscription is created. Use this to record the conversion in your own database if needed:

// app/api/webhooks/kinde/route.ts
import { getKindeWebhookDecodedEvent } from "@kinde/webhooks";
import { NextRequest, NextResponse } from "next/server";

export async function POST(request: NextRequest) {
  let event;
  try {
    event = await getKindeWebhookDecodedEvent(request);
  } catch {
    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
  }

  if (event.type === "subscription.created") {
    const { user_id, plan_key } = event.data as {
      user_id: string;
      plan_key: string;
    };

    // Record the conversion — trial user is now a paid customer
    await db.users.update({
      where: { kindeId: user_id },
      data: {
        plan: plan_key,
        convertedAt: new Date(),
      },
    });

    console.log(`Trial converted: user ${user_id} upgraded to ${plan_key}`);
  }

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

Note: the webhook is for your own record-keeping. The access control in your app should always read from the token — not from your database's plan column — because the token is always authoritative. The database record is useful for analytics, billing history, and support tooling.

Step #7: Test the Full Trial Lifecycle Without Waiting 14 Days

Testing a 14-day trial by waiting 14 days is not practical. Here are the three approaches for simulating trial state in development.

Approach 1: Manipulate the Trial Start Date

The quickest way to simulate an expiring or expired trial is to set the trial_start property to a past timestamp via the Kinde Management API. Create a test utility:

// scripts/set-trial-date.ts
// Usage: npx ts-node scripts/set-trial-date.ts <userId> <daysAgo>
// Example: npx ts-node scripts/set-trial-date.ts kp_abc123 13
//          Sets trial_start to 13 days ago — 1 day until expiry

const userId = process.argv[2];
const daysAgo = parseInt(process.argv[3] || "0");

const trialStart = Math.floor(Date.now() / 1000) - daysAgo * 86400;

async function setTrialDate() {
  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: `https://${process.env.KINDE_DOMAIN}/api`,
      }),
    }
  );

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

  const response = await fetch(
    `https://${process.env.KINDE_DOMAIN}/api/v1/user?id=${userId}`,
    {
      method: "PATCH",
      headers: {
        Authorization: `Bearer ${access_token}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        properties: {
          trial_start: trialStart.toString(),
        },
      }),
    }
  );

  if (response.ok) {
    console.log(
      `Set trial_start to ${daysAgo} days ago for user ${userId}`
    );
    console.log(`Trial expires in ${14 - daysAgo} days`);
  }
}

setTrialDate();

Run it to simulate each trial state:

# Active trial — 10 days remaining
npx ts-node scripts/set-trial-date.ts kp_abc123 4

# Expiring trial — 2 days remaining
npx ts-node scripts/set-trial-date.ts kp_abc123 12

# Expired trial
npx ts-node scripts/set-trial-date.ts kp_abc123 15

After running the script, the user needs to re-authenticate to get a fresh token with the updated trial_start value.

Approach 2: Override Trial Length in the Hook

For rapid UI development, add a TRIAL_OVERRIDE_DAYS environment variable that overrides the trial length:

// In useTrialStatus.ts, replace the constant with:
const TRIAL_LENGTH_DAYS = process.env.NEXT_PUBLIC_TRIAL_OVERRIDE_DAYS
  ? parseInt(process.env.NEXT_PUBLIC_TRIAL_OVERRIDE_DAYS)
  : 14;

Set NEXT_PUBLIC_TRIAL_OVERRIDE_DAYS=1 in .env.local during development. A trial that started today will expire tomorrow, letting you test the full lifecycle in 24 hours.

Approach 3: Use the Trial Status Storybook

For component-level testing, pass mock trial state directly to the components by extracting the hook logic into a context provider that can be overridden in tests:

// This pattern lets you render <TrialBanner /> with any trial state
// in Storybook or Jest without needing a real Kinde token
const mockTrialState: TrialState = {
  status: "expiring",
  daysRemaining: 2,
  trialStartDate: new Date(Date.now() - 12 * 86400 * 1000),
  trialEndDate: new Date(Date.now() + 2 * 86400 * 1000),
  isPro: true,
};

Wonderful! The full trial lifecycle — from first sign-up through expiry and upgrade — is now testable without waiting.

Putting It All Together

Here is the complete trial system mapped across all layers:

Layer	What it does	Where it lives
Free Trial plan (Kinde)	$0.00 plan, no credit card, Pro feature flags attached	Kinde Billing dashboard
Workflow	Stamps `trial_start` Unix timestamp on first sign-in	`trialStartWorkflow.ts` pushed to Kinde
Token customization	Surfaces `trial_start` and feature flags in the access token	Kinde application settings
`useTrialStatus` hook	Reads token claims, computes trial state	`hooks/useTrialStatus.ts`
`TrialBanner`	Shows countdown, changes urgency at day 11	`components/TrialBanner.tsx`
`TrialExpiredPaywall`	Blurs content, shows upgrade prompt on expiry	`components/TrialExpiredPaywall.tsx`
`FeatureGate`	Locks individual features after expiry	`components/FeatureGate.tsx`
Webhook handler	Records conversion in your database	`app/api/webhooks/kinde/route.ts`

What Happens When Kinde Adds Native Trial Support

When Kinde ships built-in trial periods — which is on their roadmap — the migration from this approach is straightforward:

The trialStartWorkflow.ts gets retired. The trial length configuration moves from your app's constant into the Kinde plan settings. Kinde handles the start date stamping automatically.

The useTrialStatus hook gets simplified — instead of reading application_properties.trial_start, it reads a Kinde-provided trial claim directly from the token. The state logic (active, expiring, expired, converted) stays identical.

The TrialBanner, TrialExpiredPaywall, FeatureGate, and webhook handler stay completely unchanged.

The migration is a one-afternoon job, not a rewrite.

Conclusion

In this article, you built a complete free trial system using Kinde's existing billing primitives: a $0.00 Free Trial plan with Pro feature flags, a Workflow that stamps the trial start date on first sign-in, token customization that surfaces that date without a database query, and a useTrialStatus hook that drives every trial-aware UI decision from one place.

The result is a trial system with no cron jobs, no database sync issues, no middleware that sometimes runs and sometimes does not. Trial state lives in the token. Your app reads it. The user sees the right thing at the right moment.

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

How to Add Device Authorization Flow to Your App With Kinde

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

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

In this article, you will learn:

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

Let's dive in!

The Problem With Browser-Based Auth

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

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

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

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

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

When to Use the Device Flow

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

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

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

Prerequisites

Before writing any code, make sure you have:

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

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

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

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

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

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

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

Step #2: Understand the Full Flow

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

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

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

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

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

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

Step #3: Request the Device Code

Here is the first API call your device makes:

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

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

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

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

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

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

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

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

The response from Kinde looks like this:

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

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

Step #4: Display the Code to the User

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

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

  const deviceCodeData = await requestDeviceCode();

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

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

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

Step #5: Poll for the Token

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

// src/auth.ts

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

A few things to pay attention to here:

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

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

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

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

Step #6: Store and Use the Token

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

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

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

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

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

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

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

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

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

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

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

To call your API with the token:

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

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

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

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

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

  return response.json();
}

Step #7: Validate the Token on Your API

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

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

const KINDE_DOMAIN = "YOUR_SUBDOMAIN.kinde.com";

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

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

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

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

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

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

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

Putting It All Together

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

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

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

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

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

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

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

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

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

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

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

Common Mistakes to Avoid

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

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

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

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

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

What This Enables

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

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

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

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

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

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

In this article, you will learn:

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

Let's dive in!

The Audit Log Gap That Costs You Enterprise Deals

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

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

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

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

Why Convex Is the Right Database for Audit Logs

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

Convex handles this well for three reasons.

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

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

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

Schema

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

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

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

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

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

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

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

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

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

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

The `auditLog` Helper

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

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

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

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

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

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

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

Pulling Actor Identity From Kinde

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

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

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

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

  const kindeId = identity.subject;

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

  return user;
}

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

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

Step #1: Call `auditLog` Inside Your Mutations

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

Document creation

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

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

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

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

    return documentId;
  },
});

Document deletion

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

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

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

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

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

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

Member role change

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

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

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

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

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

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

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

Settings update

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

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

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

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

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

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

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

Step #2: Query the Activity Log

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

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

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

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

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

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

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

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

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

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

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

    return results;
  },
});

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

Step #3: Build the Activity Feed UI

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Step #4: Export as CSV for Compliance

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

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

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

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

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

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

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

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

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

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

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

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

Step #5: Guarantee Org Isolation

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

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

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

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

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

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

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

  return { user, membership };
}

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

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

Testing the System

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

Test 1: Transactional commit

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

Test 2: Actor identity per session

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

Test 3: Org isolation under direct API call

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

Error: Access denied

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

Test 4: Resource label captured before deletion

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

Test 5: Metadata correctness on role changes

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

Common Mistakes to Avoid

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

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

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

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

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

What This Enables

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

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

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

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

What Is Next

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

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

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

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

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

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

In this article, you will learn:

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

Let's dive in!

Why Feature Flags Exist

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

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

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

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

How Kinde Feature Flags Work

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

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

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

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

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

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

The Four Flag Types

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

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

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

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

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

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

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

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

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

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

Step #1: Create a Feature Flag in Kinde

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

Fill in the flag details:

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

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

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

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

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

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

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

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

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

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

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

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

  const user = await getUser();

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

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

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

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

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

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

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

Step #3: Override Flags Per Environment

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

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

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

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

The cascade order for flag evaluation is:

Business default → Environment override → Organization override → User override

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

Step #4: Override Flags Per Organization for Gradual Rollouts

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

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

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

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

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

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

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

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

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

Step #5: Override Flags Per User for Beta Access

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

Navigate to Users → select the user → Feature flags.

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

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

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

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

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

In your API route that calls the AI:

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

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

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

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

type PromptStrategy = keyof typeof PROMPT_STRATEGIES;

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

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

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

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

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

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

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

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

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

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

Step #7: Use Integer Flags for AI Token Limits

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

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

Use it in your AI route handler:

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

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

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

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

Now adjust limits per organization without touching code:

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

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

Step #8: Use JSON Flags for Complex AI Configurations

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

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

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

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

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

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

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

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

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

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

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

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

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

  return NextResponse.json({ response });
}

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

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

Putting It All Together

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

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

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

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

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

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

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

Flag Naming Conventions

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

Prefix by category:

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

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

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

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

Conclusion

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

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

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

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

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

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

In this article, you will learn:

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

Let's dive in!

Why Enterprise SSO Is No Longer Optional for AI Apps

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

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

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

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

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

SAML vs OIDC: Choosing the Right Protocol

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

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

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

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

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

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

How Kinde Models Enterprise SSO

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

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

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

Step #1: Create an Organization for Your Enterprise Customer

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

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

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

Step #2: Configure a Custom SAML Connection

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Step #4: Enable IdP-Initiated SSO

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

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

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

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

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

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

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

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

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

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

Step #6: Let Enterprise Customers Configure Their Own SSO

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

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

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

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

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

Step #7: Read Enterprise Identity in Your App

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

In a Next.js application:

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

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

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

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

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

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

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

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

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

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

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

  const org = await getOrganization();

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

  // Execute AI operation
  // ...

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

Step #8: Suspend an Organization Instantly

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

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

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

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

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

Putting It All Together

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

In Kinde dashboard:

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

What you give the customer's IT team:

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

What the customer's IT team gives you:

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

In your application code:

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

SAML Troubleshooting Reference

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

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

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

Conclusion

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

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

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

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

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

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

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

In this article, you will learn:

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

Let's dive in!

Prerequisites

Before starting this tutorial, make sure you have:

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

What Is RBAC and Why Does It Belong in Auth?

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

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

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

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

How Kinde's RBAC Model Works

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

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

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

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

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

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

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

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

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

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

Step #1: Create a Next.js 16 Project

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

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

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

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

Step #2: Configure Kinde and Set Environment Variables

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

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

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

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

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

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

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

Step #3: Set Up the Auth Route Handler

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

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

export const GET = handleAuth();

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

Step #4: Wrap the Root Layout with KindeProvider

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

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

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

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

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

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

Step #5: Protect Routes Using proxy.ts

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

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

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

export default withAuth;

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

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

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

Step #6: Define Roles and Permissions in Kinde

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

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

For this tutorial, create these permissions:

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

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

Assign permissions to each role:

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

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

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

Step #7: Check Permissions in Server Components

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

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

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

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

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

  const user = await getUser();

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

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

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

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

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

Step #8: Enforce Permissions in Route Handlers

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Step #9: Build a Reusable Permission Guard Component

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

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

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

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

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

  return <>{children}</>;
}

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

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

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

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

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

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

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

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

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

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

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

Step #10: Add Sign In and Sign Out

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

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

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

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

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

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

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

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

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

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

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

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

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

Putting It All Together

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

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

The flow for every protected request:

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

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

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

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

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

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

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

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

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

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

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

Testing Your RBAC Implementation

Verify your setup by testing these scenarios:

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

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

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

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

Conclusion

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

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

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

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

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

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

In this article, you will learn:

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

Let's dive in!

The Problem With Global Permissions

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

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

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

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

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

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

How Kinde Models This

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

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

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

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

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

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

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

Step #1: Define Roles and Permissions in Kinde

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

Defining permissions

Navigate to Roles & Permissions → Permissions → Add permission.

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

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

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

Defining roles

Navigate to Roles & Permissions → Roles → Add role.

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

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

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

Viewer: projects:read, reports:read

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

Assigning roles per organization

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

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

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

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

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

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

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

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

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

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

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

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

  return NextResponse.json({ projects });
}

Two things to pay attention to here.

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

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

Step #3: Build a Reusable Permission Guard

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  return NextResponse.json({ projects });
}

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

  const body = await request.json();

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

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

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

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

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

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

Amazing!

Step #4: Gate UI Components by Permission

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

Create a client-side permission hook:

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

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

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

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

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

  const org = getOrganization();

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

Use the hook in your components for conditional rendering:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Step #5: Handle Tenant Switching Correctly

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

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

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

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

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

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

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

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

Putting It All Together

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

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

The Two Most Common Multi-Tenant Permission Bugs

Bug #1: Trusting the client-supplied tenant ID

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

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

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

Bug #2: Checking role names instead of permissions

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

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

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

Conclusion

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

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

Four layers, one source of truth: the token.

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

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

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

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

In this article, you will learn:

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

Let's dive in!

The Conversation That Prompted This Article

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

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

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

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

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

What the Data Actually Says

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

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

A few statistics that should make every technical founder uncomfortable:

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

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

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

The Five Friction Points That Kill Free Trial Conversion

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

Friction Point #1: The Signup Wall (Infrastructure)

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

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

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

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

Friction Point #2: Email Verification Delay (Infrastructure)

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

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

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

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

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

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

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

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

Friction Point #4: The Upgrade Moment (Infrastructure)

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

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

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

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

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

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

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

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

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

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

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

The Category of Friction You Should Stop Building

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

It was not the right call. Here is why.

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

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

What Kinde Gets Right Out of the Box

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

Here is what you get without writing any infrastructure code:

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

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

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

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

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

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

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

Applying This to Your Own Funnel

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

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

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

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

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

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

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

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

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

The Division of Labor That Works

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

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

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

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

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

Conclusion

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

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

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

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

How to Build a Secure MCP Server for AI Agents

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

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

In this article, you will learn:

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

Let's dive in!

OpenClaw, Moltbook, and the Security Wake-Up Call

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

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

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

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

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

This article is about building exactly that.

Why Most MCP Servers Are Architecturally Insecure

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

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

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

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

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

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

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

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

The Kinde MCP Server as a Reference Model

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

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

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

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

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

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

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

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

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

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

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

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

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

Step #2: Define Scopes for Tool-Level Permissions

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

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

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

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

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

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

Step #3: Build the MCP Server with Token Validation

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

First, install the dependencies:

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

Create the server file:

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

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

const KINDE_DOMAIN = process.env.KINDE_DOMAIN!; // e.g. "yourapp.kinde.com"
const MCP_AUDIENCE = process.env.MCP_AUDIENCE!;  // e.g. "https://mcp.yourapp.com"

// JWKS client — fetches Kinde's public signing keys
// Used to verify that incoming tokens were genuinely signed by Kinde
const jwks = jwksClient({
  jwksUri: `https://${KINDE_DOMAIN}/.well-known/jwks.json`,
  cache: true,
  cacheMaxEntries: 5,
  cacheMaxAge: 600_000, // 10 minutes
});

// ─── JWT Validation ──────────────────────────────────────────────────────────

interface TokenPayload {
  sub: string;           // agent identity (M2M app client ID)
  scp?: string;          // space-separated scopes
  permissions?: string[]; // Kinde also surfaces permissions here
  aud: string | string[];
  iss: string;
  exp: number;
}

async function validateToken(authHeader: string | undefined): Promise<TokenPayload> {
  if (!authHeader?.startsWith("Bearer ")) {
    throw new Error("Missing or malformed Authorization header");
  }

  const token = authHeader.slice(7);

  // Decode the header to find the key ID (kid)
  const decoded = jwt.decode(token, { complete: true });
  if (!decoded || typeof decoded === "string") {
    throw new Error("Invalid token format");
  }

  const kid = decoded.header.kid;
  if (!kid) {
    throw new Error("Token missing key ID (kid)");
  }

  // Fetch the public key from Kinde's JWKS endpoint
  const signingKey = await jwks.getSigningKey(kid);
  const publicKey = signingKey.getPublicKey();

  // Verify the token — this checks signature, expiry, issuer, and audience
  const payload = jwt.verify(token, publicKey, {
    algorithms: ["RS256"],
    issuer: `https://${KINDE_DOMAIN}`,
    audience: MCP_AUDIENCE, // prevents token passthrough attacks
  }) as TokenPayload;

  return payload;
}

// ─── Scope Enforcement ───────────────────────────────────────────────────────

function requireScope(requiredScope: string) {
  return (payload: TokenPayload): void => {
    // Kinde puts scopes in the `scp` claim as a space-separated string
    const tokenScopes = payload.scp?.split(" ") ?? [];

    // Also check the `permissions` array (Kinde's permission system)
    const permissions = payload.permissions ?? [];

    const hasScope =
      tokenScopes.includes(requiredScope) ||
      tokenScopes.includes("admin") ||
      permissions.includes(requiredScope) ||
      permissions.includes("admin");

    if (!hasScope) {
      throw new Error(
        `Insufficient permissions. Required: ${requiredScope}. ` +
        `Token has: ${tokenScopes.join(", ") || "none"}`
      );
    }
  };
}

// ─── Auth Middleware ──────────────────────────────────────────────────────────

// Store the validated token payload on the request object
// so tool handlers can access it without re-validating
declare global {
  namespace Express {
    interface Request {
      agentToken?: TokenPayload;
    }
  }
}

async function authMiddleware(req: Request, res: Response, next: NextFunction) {
  try {
    const payload = await validateToken(req.headers.authorization);
    req.agentToken = payload;
    console.log(`Agent authenticated: ${payload.sub} with scopes: ${payload.scp}`);
    next();
  } catch (err) {
    console.warn(`Auth failed: ${(err as Error).message}`);
    res.status(401).json({
      error: "unauthorized",
      message: (err as Error).message,
    });
  }
}

// ─── MCP Server Definition ────────────────────────────────────────────────────

const server = new McpServer({
  name: "secure-mcp-server",
  version: "1.0.0",
});

// Tool #1: get_user — requires users:read scope
server.tool(
  "get_user",
  "Retrieve a user by their ID",
  {
    user_id: z.string().describe("The unique identifier of the user to retrieve"),
  },
  async ({ user_id }, { _meta }) => {
    // Access the validated token from the request context
    // The token was validated and attached by authMiddleware before this handler runs
    const token = (_meta as any)?.agentToken as TokenPayload;
    requireScope("users:read")(token);

    // Your actual business logic here
    // This is a placeholder — replace with real data fetching
    return {
      content: [
        {
          type: "text" as const,
          text: JSON.stringify({
            id: user_id,
            email: "user@example.com",
            name: "Jane Smith",
            created_at: "2025-01-15T10:30:00Z",
          }),
        },
      ],
    };
  }
);

// Tool #2: create_user — requires users:write scope
server.tool(
  "create_user",
  "Create a new user account",
  {
    email: z.string().email().describe("Email address for the new user"),
    name: z.string().describe("Full name of the user"),
    role: z.enum(["admin", "member", "viewer"]).default("member"),
  },
  async ({ email, name, role }, { _meta }) => {
    const token = (_meta as any)?.agentToken as TokenPayload;
    requireScope("users:write")(token);

    // Log who created the user for audit purposes
    console.log(`User creation requested by agent: ${token.sub}`);

    // Your actual user creation logic here
    return {
      content: [
        {
          type: "text" as const,
          text: JSON.stringify({
            id: `usr_${Date.now()}`,
            email,
            name,
            role,
            created_by_agent: token.sub,
            created_at: new Date().toISOString(),
          }),
        },
      ],
    };
  }
);

// Tool #3: delete_user — requires users:delete scope (most restrictive)
server.tool(
  "delete_user",
  "Permanently delete a user account",
  {
    user_id: z.string().describe("ID of the user to delete"),
    reason: z.string().describe("Reason for deletion (required for audit trail)"),
  },
  async ({ user_id, reason }, { _meta }) => {
    const token = (_meta as any)?.agentToken as TokenPayload;

    // This scope is only granted to trusted admin agents
    // Read-only agents cannot call this tool even if they know it exists
    requireScope("users:delete")(token);

    console.log(
      `AUDIT: User ${user_id} deleted by agent ${token.sub}. Reason: ${reason}`
    );

    return {
      content: [
        {
          type: "text" as const,
          text: JSON.stringify({
            deleted: true,
            user_id,
            deleted_by: token.sub,
            reason,
            timestamp: new Date().toISOString(),
          }),
        },
      ],
    };
  }
);

// ─── HTTP Server ──────────────────────────────────────────────────────────────

const app = express();
app.use(express.json());

// The auth middleware runs on every MCP request before the tool handlers
app.post("/mcp", authMiddleware, async (req, res) => {
  const transport = new StreamableHTTPServerTransport({
    sessionIdGenerator: undefined,
  });

  // Pass the validated token into the MCP request context
  // so tool handlers can access it via _meta.agentToken
  (req as any).agentToken = req.agentToken;

  await server.connect(transport);
  await transport.handleRequest(req, res, req.body);
});

// Protected resource metadata endpoint — required for OAuth 2.1 discovery
// MCP clients fetch this to learn where to get tokens
app.get("/.well-known/oauth-protected-resource", (_req, res) => {
  res.json({
    resource: MCP_AUDIENCE,
    authorization_servers: [`https://${KINDE_DOMAIN}`],
    scopes_supported: [
      "users:read",
      "users:write",
      "users:delete",
      "data:read",
      "data:write",
      "admin",
    ],
    bearer_methods_supported: ["header"],
  });
});

const PORT = process.env.PORT ?? 3000;
app.listen(PORT, () => {
  console.log(`Secure MCP Server running on port ${PORT}`);
  console.log(`Protected resource metadata: http://localhost:${PORT}/.well-known/oauth-protected-resource`);
});

Step #4: How Agents Obtain Tokens

Your MCP server is now a protected resource. To call it, an agent needs a token. Here is how an OpenClaw-style agent — or any MCP client — would obtain one using Kinde's client credentials flow:

// agent-token.ts
// This code runs in the AGENT (the MCP client), not in the MCP server

async function getAgentToken(): Promise<string> {
  const tokenResponse = await fetch(
    `https://${process.env.KINDE_DOMAIN}/oauth2/token`,
    {
      method: "POST",
      headers: { "Content-Type": "application/x-www-form-urlencoded" },
      body: new URLSearchParams({
        grant_type: "client_credentials",
        client_id: process.env.KINDE_M2M_CLIENT_ID!,
        client_secret: process.env.KINDE_M2M_CLIENT_SECRET!,
        audience: process.env.MCP_AUDIENCE!, // your MCP server's audience
        scope: "users:read data:read", // only request what this agent needs
      }),
    }
  );

  if (!tokenResponse.ok) {
    const error = await tokenResponse.json();
    throw new Error(`Token request failed: ${JSON.stringify(error)}`);
  }

  const { access_token } = await tokenResponse.json();
  return access_token;
}

// Then use the token in every MCP request
async function callMcpTool(tool: string, params: object) {
  const token = await getAgentToken();

  const response = await fetch("https://mcp.yourapp.com/mcp", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": `Bearer ${token}`, // Kinde-issued JWT
    },
    body: JSON.stringify({
      jsonrpc: "2.0",
      method: "tools/call",
      params: { name: tool, arguments: params },
      id: 1,
    }),
  });

  return response.json();
}

Note: Tokens issued via client credentials are valid for one hour by default in Kinde. Agents should cache the token and only request a new one when it is close to expiry — not on every tool call. Check the expires_in field in the token response and refresh when there are 60 seconds or fewer remaining.

Step #5: Configure an OpenClaw Skill With Proper Auth

To connect a properly authenticated MCP server to an OpenClaw agent, you configure the skill in openclaw.json with the token endpoint details. Here is what a secure skill configuration looks like:

{
  "plugins": {
    "entries": {
      "my-secure-tool": {
        "enabled": true,
        "type": "mcp",
        "transport": "streamable-http",
        "url": "https://mcp.yourapp.com/mcp",
        "auth": {
          "type": "oauth2",
          "flow": "client_credentials",
          "token_endpoint": "https://YOUR_DOMAIN.kinde.com/oauth2/token",
          "client_id": "your_m2m_client_id",
          "client_secret_env": "MY_TOOL_CLIENT_SECRET",
          "audience": "https://mcp.yourapp.com",
          "scopes": ["users:read", "data:read"]
        }
      }
    }
  }
}

Note: client_secret_env points to an environment variable rather than embedding the secret inline — critical for anyone publishing skill configurations or committing them to version control. The secret itself lives in the environment, not in the config file.

This configuration gives your agent the specific scopes it needs and nothing more. If someone performs a prompt injection attack via Moltbook and tries to get this agent to call delete_user, the token does not have the users:delete scope — the MCP server rejects the call before it can execute.

Putting It All Together

Here is the complete security architecture you have built:

┌─────────────────────────────────────────────────────────────────┐
│                         Kinde                                   │
│                                                                 │
│  M2M Application (Agent Identity)                               │
│  ├── Client ID: m2m_abc123                                      │
│  ├── Granted scopes: users:read, data:read                      │
│  └── NOT granted: users:write, users:delete, admin              │
│                                                                 │
│  JWKS Endpoint: /well-known/jwks.json (public key verification) │
│  Token Endpoint: /oauth2/token (client credentials flow)        │
└───────────────────────────────┬─────────────────────────────────┘
                                │ issues signed JWT (1hr TTL)
                                │ with scopes: users:read data:read
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                      Agent (OpenClaw)                           │
│                                                                 │
│  Holds JWT in memory (never stored on disk)                     │
│  Sends: Authorization: Bearer <JWT> on every MCP request        │
└───────────────────────────────┬─────────────────────────────────┘
                                │ HTTPS POST /mcp
                                │ Authorization: Bearer <JWT>
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Secure MCP Server                            │
│                                                                 │
│  1. authMiddleware: validates JWT signature via JWKS            │
│     → checks issuer, audience, expiry                           │
│                                                                 │
│  2. Per-tool scope check: requireScope("users:read")            │
│     → tools/get_user ✓ (scope present)                          │
│     → tools/delete_user ✗ (scope missing → 401)                 │
│                                                                 │
│  3. Audit log: agent ID, tool called, timestamp                 │
└─────────────────────────────────────────────────────────────────┘

The security properties you now have that OpenClaw's default Skills did not:

Property	Insecure MCP (OpenClaw default)	Secure MCP (with Kinde)
Agent identity	Anonymous / shared API key	Cryptographic JWT (`sub` claim = M2M app ID)
Token forgability	API key can be shared/leaked	RS256 JWT signed by Kinde — cannot be forged
Tool-level permissions	All tools accessible to all callers	Per-tool scope enforcement
Prompt injection blast radius	Agent can call any tool if injected	Injected instruction can only call scoped tools
Token expiry	API keys never expire	1-hour TTL — breach window is bounded
Revocation	Must rotate key for all agents	Revoke one M2M app, others unaffected
Audit trail	None	Agent ID + scope logged on every tool call

Testing Your Security Layer

Before deploying, verify these four scenarios:

Test 1 — Valid token, allowed scope. Call get_user with a token that has users:read. You should receive the user data. This confirms the happy path works.

Test 2 — Valid token, insufficient scope. Call delete_user with a token that only has users:read. You should receive a 401 with a message like "Insufficient permissions. Required: users:delete." This confirms scope enforcement works.

Test 3 — Expired token. Manually modify the exp claim of a token or wait for it to expire, then attempt a call. You should receive a 401 with a JWT expiry error. This confirms token lifecycle enforcement works.

Test 4 — Wrong audience. Use a token issued for a different API (different aud claim) and attempt a call to your MCP server. You should receive a 401 with an audience mismatch error. This confirms that token passthrough attacks are blocked.

# Test 2 example — calling a tool without the required scope
curl -X POST https://your-mcp-server.com/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $READ_ONLY_TOKEN" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "delete_user",
      "arguments": {
        "user_id": "usr_123",
        "reason": "Test deletion attempt"
      }
    },
    "id": 1
  }'

# Expected response:
# HTTP 401 Unauthorized
# { "error": "unauthorized", "message": "Insufficient permissions. Required: users:delete. Token has: users:read" }

Amazing! Your MCP server is now hardened against the attack patterns that took down OpenClaw deployments and turned Moltbook into a security incident.

Conclusion

In this article, you built a secure MCP server with scoped, tool-level authentication — the approach that the OpenClaw and Moltbook incidents showed was critically missing from most agentic AI deployments. Your server now knows who every connecting agent is, what they are allowed to do, and rejects anything outside those boundaries at the tool boundary before execution.

The key insight from Kinde's own MCP server — shipped in January 2026 as a working reference implementation — is that security for AI agents is not fundamentally different from security for any other kind of software. M2M identities, scoped tokens, short TTLs, and JWT validation are not new concepts. What is new is applying them consistently to MCP servers, which the ecosystem has been slow to do.

Agentic AI is not going away. OpenClaw proved that. The question is whether the infrastructure it runs on is built securely. That starts with the MCP server you control.

Kinde is free for up to 10,500 monthly active users, no credit card required. Create your account at kinde.com and start treating your agents as the production infrastructure they are.

Stop Treating AI Agents Like Users: Why Your Auth Model Needs a New Layer for Non-Human Identities

Shola Jegede — Sat, 21 Mar 2026 23:40:03 +0000

Your auth system was built for humans. AI agents are not humans. Something has to give.

In this article, you will learn:

Why the traditional user auth model breaks down for AI agents
What non-human identities are and why they need their own auth layer
The difference between global and org-scoped machine identity
How the OAuth 2.0 client credentials flow works for non-human callers
How to use Kinde M2M applications to authenticate AI agents properly
How to scope agent access to a specific tenant using org-scoped M2M apps
The biggest security mistakes developers make when adding agent auth and how to avoid them

Let's dive in!

The Problem Nobody Warned You About

You shipped auth. Users can sign up, sign in, and get sessions. You followed the OAuth flow, you set up JWTs, you protected your routes. Everything works.

Then someone on your team says: "We're adding an AI agent that acts on behalf of users."

And suddenly you have a question your auth system was never designed to answer: how do you authenticate something that has no browser, no session, no email address, and no ability to type in a password?

The lazy answer is to create a fake user account for the agent. Give it an email like agent@yourapp.com, hand it a password, and call it done. It works — until it becomes a security nightmare. You have an account with full user-level access, no MFA, credentials that never rotate, and no audit trail that distinguishes what the agent did from what a real user did. That is not an auth model. That is a ticking clock.

The real answer is that AI agents are not users. They are non-human identities. They need their own authentication layer, their own token type, their own scopes, and their own access boundaries. And in 2026, with AI agents becoming a core part of SaaS products, getting this right is no longer optional.

Here is what that looks like in practice, and how Kinde's M2M application system handles it properly.

What Is a Non-Human Identity?

A non-human identity (NHI) is any software principal that needs to authenticate and call APIs without a human being directly involved in the auth flow. In the context of modern SaaS products, non-human identities include things like backend services, CI/CD pipelines, scheduled jobs, microservices, and — increasingly — AI agents.

What all of these have in common is that they cannot participate in an interactive auth flow. There is no redirect. There is no browser. There is no one sitting at a keyboard to enter a verification code. A human auth flow is fundamentally the wrong tool for the job.

The problem is that most auth systems — and most developer mental models — were built around human identities first. Non-human auth was bolted on later, often improperly, as an afterthought.

Why the Fake User Approach Fails

Before getting into the right solution, it is worth being specific about why the fake user workaround is dangerous. These are not theoretical risks.

Over-permissioned by default. A user account typically has all the permissions of a regular user. For an AI agent that only needs to read data from one endpoint and write to another, that is massive over-permission. Least-privilege is the foundational principle of access control, and fake user accounts violate it immediately.

No credential rotation. User passwords are designed to be long-lived and human-memorable. They are not designed to be rotated on a schedule the way service credentials should be. In practice, the fake user's password never changes, which means a leaked credential is a permanent breach.

No audit trail separation. When an agent operating as agent@yourapp.com makes a write operation, your logs show a user action. You cannot distinguish agent activity from human activity. Debugging becomes a nightmare, compliance becomes impossible, and incident response becomes guesswork.

Sessions and cookies do not make sense. User auth produces sessions tied to browsers. Agents do not have browsers. They do not maintain state across requests the same way users do. Forcing them through a session-based flow creates fragile plumbing that breaks under load or on token expiry.

MFA breaks the whole thing. If you ever enforce MFA for user accounts — and you should — your fake agent account will be locked out the moment MFA is required. Either you exempt it, which creates a security hole, or you break your automation.

The Right Mental Model: Machine-to-Machine Authentication

The correct solution has existed in the OAuth 2.0 specification for years. It is called the client credentials flow, and it is specifically designed for non-human identities authenticating without user involvement.

Instead of a user logging in with credentials, a machine authenticates using a client_id and client_secret. It sends those credentials directly to the token endpoint and receives an access token in return. No redirects. No browser. No session. Just a token that the machine can use to call APIs on its own behalf.

The access token issued through the client credentials flow is structurally different from a user token. It does not have a sub claim representing a user. It does not expire into a refresh token cycle the way user sessions do. It is scoped to the capabilities of the machine application, not the permissions of a specific person. This distinction is crucial.

In Kinde, this pattern is implemented through M2M applications — Machine-to-Machine applications. An M2M application is a registered identity in Kinde with its own client_id and client_secret, its own set of API scopes, and its own token. It is the right primitive for any non-human caller: a CI/CD pipeline, a backend service, an automation script, or an AI agent.

Two Types of Machine Identity in Kinde

Kinde supports two types of M2M applications, and understanding the difference is important for building the right auth model for your product.

Global M2M Applications

A global M2M application is not tied to any specific organization in your Kinde setup. It operates across your entire tenant space. This makes it suitable for internal tooling, admin automation, infrastructure scripts, and anything that needs to operate at the system level rather than within a specific customer's context.

A typical use case is a CI/CD pipeline that needs to call the Kinde Management API to create users, update flags, or deploy configuration changes across all of your organizations. It does not need to be scoped to one tenant — it needs cross-tenant access, and a global M2M app provides exactly that.

Org-Scoped M2M Applications

An org-scoped M2M application is tied to a specific organization — a specific tenant — in your Kinde setup. Tokens issued to this app automatically include the org_code claim, which enforces that all API calls made by this machine identity are restricted to that organization's context.

This is the right pattern for AI agents acting on behalf of a specific customer. If Acme Corp has an AI agent that reads their data, writes to their workspace, and takes actions in their context, that agent should not have any access to the data or context of Beta Inc. Org-scoped M2M applications enforce this boundary at the token level — before your API even has to think about it.

Note: Org-scoped M2M applications are available on the Kinde Plus and Kinde Scale plans.

Global vs Org-Scoped M2M: At a Glance

Feature	Global M2M App	Org-Scoped M2M App
Org context in token	No	Yes (`org_code` claim)
Tenant data isolation	Manual (your API must enforce it)	Enforced at token issuance
Best for	Admin scripts, internal automation, infra	Per-tenant AI agents, scoped APIs
Token restrictions	None	Scoped to one organization
Credential rotation	Manual, in Kinde dashboard	Manual, in Kinde dashboard
Available on	All plans	Kinde Plus and Scale

How the Client Credentials Flow Works in Kinde

When an M2M application needs to call an API, it follows the OAuth 2.0 client credentials flow. Here is exactly what that looks like in code.

Step #1: Request a Token

The machine application sends a POST request to your Kinde domain's token endpoint. It authenticates with its client_id and client_secret and requests the scopes it needs.

curl --request POST \
  --url https://YOUR_KINDE_DOMAIN.kinde.com/oauth2/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data grant_type=client_credentials \
  --data client_id=YOUR_M2M_CLIENT_ID \
  --data client_secret=YOUR_M2M_CLIENT_SECRET \
  --data audience=https://YOUR_KINDE_DOMAIN.kinde.com/api \
  --data scope=read:users write:flags

Note: Replace YOUR_KINDE_DOMAIN, YOUR_M2M_CLIENT_ID, and YOUR_M2M_CLIENT_SECRET with the values from your Kinde dashboard.

Step #2: Receive the Access Token

Kinde responds with an access token:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 86400,
  "scope": "read:users write:flags"
}

For an org-scoped M2M app, the decoded token payload will also include the org_code claim:

{
  "iss": "https://YOUR_KINDE_DOMAIN.kinde.com",
  "sub": "YOUR_M2M_CLIENT_ID",
  "aud": ["https://YOUR_KINDE_DOMAIN.kinde.com/api"],
  "exp": 1234567890,
  "iat": 1234567890,
  "scope": "read:users write:flags",
  "org_code": "org_abc123"
}

The org_code claim is embedded at token issuance time and cannot be modified. Your API can trust it completely.

Step #3: Call Your API with the Token

The agent uses the access token as a Bearer token in subsequent API calls:

// Node.js example — calling your API as an M2M client
const response = await fetch("https://api.yourapp.com/v1/users", {
  method: "GET",
  headers: {
    // pass the M2M token as a Bearer token
    Authorization: `Bearer ${accessToken}`,
    "Content-Type": "application/json",
  },
});

const data = await response.json();

Step #4: Verify the Token on Your API

Your API receives the token and verifies it. For an org-scoped M2M app, you can trust the org_code claim directly from the verified token to enforce tenant isolation without any additional lookup:

// Express.js middleware — verifying and using the org_code from an M2M token
import jwt from "jsonwebtoken";
import jwksClient from "jwks-rsa";

const client = jwksClient({
  jwksUri: `https://YOUR_KINDE_DOMAIN.kinde.com/.well-known/jwks.json`,
});

function getKey(header, callback) {
  client.getSigningKey(header.kid, (err, key) => {
    const signingKey = key.getPublicKey();
    callback(null, signingKey);
  });
}

function verifyM2MToken(req, res, next) {
  const authHeader = req.headers["authorization"];
  const token = authHeader && authHeader.split(" ")[1];

  if (!token) {
    return res.status(401).json({ error: "No token provided" });
  }

  jwt.verify(
    token,
    getKey,
    {
      audience: "https://YOUR_KINDE_DOMAIN.kinde.com/api",
      issuer: "https://YOUR_KINDE_DOMAIN.kinde.com",
    },
    (err, decoded) => {
      if (err) {
        return res.status(403).json({ error: "Invalid token" });
      }

      // org_code is now trusted and available — no additional lookup needed
      req.orgCode = decoded.org_code;
      req.scopes = decoded.scope ? decoded.scope.split(" ") : [];
      next();
    }
  );
}

// Use in a route to enforce org isolation
app.get("/v1/users", verifyM2MToken, async (req, res) => {
  // All queries are automatically scoped to this organization
  const users = await db.users.findAll({
    where: { org_code: req.orgCode },
  });

  res.json({ users });
});

Wonderful! Your API now enforces tenant isolation based entirely on what is in the verified token — no additional queries, no custom middleware logic, no trust-but-verify gymnastics.

Setting Up an M2M Application in Kinde

Creating a Global M2M Application

In your Kinde dashboard, navigate to Settings → Applications.
Select Add application.
Give your application a name — something descriptive like "Reporting Pipeline" or "Internal Automation Agent".
Select Machine to machine as the application type.
Select Save.

Kinde generates a client_id and client_secret for your new application. Save the secret immediately — it is only shown once.

Assigning Scopes to the M2M Application

Before your M2M application can call any API, you need to assign the scopes it is permitted to request. Scopes define the boundaries of what the token can do.

Navigate to the APIs section of your M2M application and select the APIs the application needs access to. For each API, choose only the scopes genuinely required by the agent. A reporting agent that only reads data should have read:reports, not write:reports or delete:reports. Least privilege applies here just as much as it does for users.

Creating an Org-Scoped M2M Application

In your Kinde dashboard, navigate to Organizations.
Select the organization you want to scope the M2M app to.
Select the M2M apps tab.
Enter a name for the application — for example, "Acme Corp AI Agent".
Select M2M application as the type.
Select Save.

Kinde generates a client_id and client_secret tied specifically to that organization. Tokens issued with these credentials will automatically include the org_code claim set to that organization's code.

A Real-World Scenario: Per-Tenant AI Agent

Here is a concrete scenario to make this tangible. You are building a B2B SaaS product with an AI feature that automatically summarizes activity for each customer's workspace. The agent needs to read data from your API, process it, and write a summary back.

Without org-scoped M2M, your agent either has global access (dangerous) or you build custom tenant-checking middleware on every endpoint (fragile). With org-scoped M2M in Kinde, each customer's agent gets its own set of credentials that are cryptographically tied to their organization. The token tells your API exactly which tenant it belongs to, and your API can trust that claim without any additional work.

The full flow for this scenario looks like:

On onboarding, create an org-scoped M2M application for the new customer's organization in Kinde.
Store the client_id and client_secret securely (environment variables, secrets manager, etc.).
When the agent needs to act, it requests a token using the client credentials flow.
It calls your API with the token as a Bearer header.
Your API verifies the token, extracts org_code, and scopes all database queries to that organization.
The agent can never access another tenant's data, even if its credentials were somehow leaked — because the token itself is bound to one org.

What About Kinde's MCP Server?

In January 2026, Kinde shipped an MCP (Model Context Protocol) server. This lets AI agents and AI tools connect to Kinde directly using the MCP protocol — which is rapidly becoming the standard interface for AI-to-tool communication.

What this means in practice is that AI agents using MCP-compatible frameworks (like Claude Code, Cursor, or any agent built on an MCP client library) can interact with Kinde's management capabilities — creating users, managing organizations, checking permissions, and more — through a standardized tool interface rather than raw API calls.

For teams building AI-native products, this is a big deal. Instead of writing custom integration code to give your agent access to Kinde's capabilities, you can connect it via the MCP server and let it use those capabilities as native tools.

The MCP server and M2M applications complement each other. M2M handles the authentication layer — proving the agent's identity and authorizing its access. The MCP server handles the interface layer — giving the agent a structured way to use Kinde's functionality once it is authenticated.

Security Best Practices for M2M Auth

There are a few principles that are non-negotiable when running machine identities in production.

One M2M application per service. Do not share credentials across multiple agents or services. If one service is compromised, its credentials can be revoked without affecting anything else. Shared credentials mean shared blast radius.

Minimum necessary scopes. Every M2M application should be granted only the scopes it genuinely needs to do its job. An agent that reads data should not have write access. An agent that writes to one resource should not have write access to all resources. Define your API scopes granularly and assign them carefully.

Rotate client secrets on a schedule. Client secrets are long-lived credentials and they should be rotated periodically. Kinde provides secret rotation directly in the dashboard. Build secret rotation into your operational runbook and do not treat it as optional.

Never put client secrets in client-side code. M2M credentials authenticate a service, not a user. They must live server-side — in environment variables, in a secrets manager, in a secure deployment config. Putting them anywhere that gets shipped to a browser is an immediate credential leak.

Track client_id and org_code in your logs. When an M2M token is used to call your API, log the client_id alongside the org_code. This gives you a clean audit trail that distinguishes what each agent did, in which tenant's context, at what time. When something goes wrong — and eventually something will — this makes debugging and incident response dramatically faster.

Token expiry is your friend. M2M tokens expire. Do not try to cache them indefinitely. Let them expire and re-request as needed. Short expiry windows limit the blast radius of a leaked token significantly. Kinde issues M2M tokens with configurable expiry — keep it as short as your use case allows.

Conclusion

In this article, you learned why the traditional user auth model breaks down for AI agents, what non-human identities are and why they need their own auth layer, and how the OAuth 2.0 client credentials flow provides the right foundation for machine authentication. You also saw how Kinde's M2M applications implement this properly — with global apps for internal tooling and org-scoped apps for per-tenant AI agents that enforce isolation at the token level.

The shift to AI-native products is not slowing down. Every SaaS product built in 2026 is adding or planning to add agent capabilities. The teams that get non-human identity right from the beginning are the ones that avoid the security incidents, the audit nightmares, and the architectural rewrites that come from bolting fake user accounts onto a system that was never designed for them.

Kinde gives you the primitives to do this properly from day one. Create a free Kinde account and start building your M2M auth layer today.

Forem: Shola Jegede

How to Send Auth Codes via WhatsApp in Your App With Kinde

Why WhatsApp OTP Is the Right Choice for Your Market

How Kinde Handles WhatsApp OTP

What You Need Before You Start

Step #1: Configure Twilio for Phone and WhatsApp Delivery

Step #2: Connect Twilio to Kinde

Step #3: Enable Phone Authentication in Kinde

Step #4: Enable WhatsApp as the Delivery Channel

Step #5: Configure Phone Auth as MFA (Optional)

Step #6: Wire Phone Authentication Into Your Next.js App

Step #7: Test the Full WhatsApp OTP Flow

Country-Specific Notes for African and Southeast Asian Markets

Troubleshooting Common Issues

Putting It All Together

Conclusion

Why SMS Auth Is Quietly Failing Your Users (And How to Fix It With WhatsApp)

The Silent Failure Rate You Are Not Measuring

The Fraud Problem That Is Eating Your OTP Budget

The Regulatory Wall That Is Coming

What WhatsApp Actually Fixes

The Developer Counterarguments (And Why They Do Not Hold Up)

How Kinde Makes This a One-Afternoon Integration

The Actual Stakes

How to Add Free Trials to Your SaaS Without Friction: A Step-by-Step Guide With Kinde

The Free Trial Problem Nobody Talks About

How Kinde Billing Works Today — And One Important Caveat

The Architecture You Are Building

Step #1: Create the Free Plan in Kinde Billing

Step #2: Stamp the Trial Start Date With a Kinde Workflow

Step #3: Surface Trial State in the Access Token

Step #4: Build the useTrialStatus Hook

Step #5: Build the Trial UI Components

The Trial Banner

The Expired Paywall

The Feature Gate

Putting the Components Together

Step #6: Handle the Upgrade — Moving From Trial to Paid

Step #7: Test the Full Trial Lifecycle Without Waiting 14 Days

Approach 1: Manipulate the Trial Start Date

Approach 2: Override Trial Length in the Hook

Approach 3: Use the Trial Status Storybook

Putting It All Together

What Happens When Kinde Adds Native Trial Support

Conclusion

How to Add Device Authorization Flow to Your App With Kinde

The Problem With Browser-Based Auth

When to Use the Device Flow

Prerequisites

Step #1: Create a Device and IoT Application in Kinde

Step #2: Understand the Full Flow

Step #3: Request the Device Code

Step #4: Display the Code to the User

Step #5: Poll for the Token

Step #6: Store and Use the Token

Step #7: Validate the Token on Your API

Putting It All Together

Common Mistakes to Avoid

What This Enables

How to Audit Who Did What in Your Multi-Tenant App: Building an Activity Log With Convex and Kinde

The Audit Log Gap That Costs You Enterprise Deals

Why Convex Is the Right Database for Audit Logs

Schema

The auditLog Helper

Pulling Actor Identity From Kinde

Step #1: Call auditLog Inside Your Mutations

Document creation

Document deletion

Member role change

Settings update

Step #2: Query the Activity Log

Step #3: Build the Activity Feed UI

Step #4: Export as CSV for Compliance

Step #5: Guarantee Org Isolation

Testing the System

Common Mistakes to Avoid

What This Enables

What Is Next

How to Use Feature Flags to Safely Roll Out Features in Production With Kinde

Why Feature Flags Exist

Step #4: Build the `useTrialStatus` Hook

The `auditLog` Helper

Step #1: Call `auditLog` Inside Your Mutations

A Note on `use cache` in Next.js 16