DEV Community: Shola Jegede

Kinde Is Missing from Mastra's Auth Lineup, So I Built the Provider

Shola Jegede — Sun, 21 Jun 2026 21:10:11 +0000

If you're building a SaaS AI agent product and you're already on Kinde, you already know the problem.

Mastra is the TypeScript-first AI agent framework. It ships with official auth providers for Clerk, Auth0, Supabase, Firebase, WorkOS, and Better Auth. Kinde is not on that list.

The obvious question is why not reach for one of those providers, since Auth0 is already there.

Most developers who choose Kinde rely on far more than its login. Kinde ships with the organizational structures, permission systems, and monetization tools that products actually need, bringing auth, billing, feature flags, and multi-tenancy together in one platform. If you're building a B2B SaaS product on Kinde, you're using Kinde orgs to segment your customers, Kinde billing to manage subscriptions, and Kinde feature flags to gate features by plan. Switching to Auth0 or Clerk to support a Mastra agent would mean rebuilding all of that elsewhere, which is not a real option.

That gap is the problem. You need Kinde to work with Mastra, and until now there was no clean way to connect them.

That's why I built mastra-auth-kinde.

What Mastra's auth system actually does

When you add an auth provider to Mastra, it protects two things at once: all your API routes (/api/agents/*, /api/workflows/*, and so on) and your Mastra Studio UI. Every request to a protected route goes through your provider before it reaches anything else.

You extend Mastra's MastraAuthProvider base class and implement two methods:

authenticateToken(token, request) verifies the JWT and returns the decoded user, or null if it fails
authorizeUser(user, request) returns true to let the request through, or false for a 403

Mastra handles everything else: extracting the Bearer token from the Authorization header, calling your methods in order, and storing the verified user in the request context so your agents and tools can access it.

Why Kinde specifically

Beyond the billing and org story above, a few things make Kinde the right fit for agent developers in particular.

First, Kinde's org model maps directly to multi-tenancy, so each customer gets isolated data and configuration without you building it. Each Kinde organization is a tenant, and the org_code claim on every token tells you exactly which org the user belongs to. For a multi-tenant agent, one that serves different customers on the same infrastructure, this is exactly what you need.

Second, machine-to-machine authentication comes standard rather than as an expensive add-on. AI agents frequently need to run background jobs, scheduled workflows, and nightly pipelines with no human user in the loop. Kinde handles this natively with client credentials tokens, and this provider handles those too, which I cover below.

Third, the free tier is usable for real products, including 10,500 monthly active users, unlimited organizations, and all authentication methods including SSO. You can build a real multi-tenant agent product without paying anything until you're at scale.

Installation

npm install github:sholajegede/mastra-auth-kinde

You also need @mastra/core if you don't already have it:

npm install @mastra/core

Step 1 — Basic setup

Wire the provider into your Mastra instance:

import { Mastra } from '@mastra/core'
import { MastraAuthKinde } from 'mastra-auth-kinde'

export const mastra = new Mastra({
  server: {
    auth: new MastraAuthKinde({
      domain: 'https://yourapp.kinde.com',
    }),
  },
})

Or use environment variables:

KINDE_DOMAIN=https://yourapp.kinde.com
KINDE_AUDIENCE=https://api.yourapp.com  # optional — see the audience section below

export const mastra = new Mastra({
  server: {
    auth: new MastraAuthKinde(),
  },
})

Once this is in place, every request to /api/* needs a valid Kinde access token in the Authorization: Bearer <token> header. Unauthenticated requests get a 401, and requests that fail the authorization check get a 403.

Step 2 — User token authentication

A standard Kinde user access token carries these claims:

iss, sub, aud, azp, exp, iat, jti, scp

The provider verifies the token against Kinde's JWKS endpoint, validates the issuer and expiry, and checks the audience claim if you have the option configured.

Kinde's JWKS endpoint sits at /.well-known/jwks with no .json extension, even though the common assumption is /.well-known/jwks.json. Verify it against your tenant's discovery document before assuming:

curl -s https://yourapp.kinde.com/.well-known/openid-configuration | jq .jwks_uri
# "https://yourapp.kinde.com/.well-known/jwks"

The provider handles this correctly out of the box.

The audience option

Only set audience (or KINDE_AUDIENCE) once you've registered and bound an API audience in the Kinde dashboard. A default Kinde user token carries an empty aud array, and any token with an empty aud will fail the audience check if the option is set.

new MastraAuthKinde({
  domain: 'https://yourapp.kinde.com',
  audience: 'https://api.yourapp.com', // only add this after binding an API audience in Kinde
})

Step 3 — M2M / system-actor support

In the standard agent setup, a human user logs in, the frontend gets a token, and that token is passed to the Mastra API, which works for user-facing agents. Real agent architectures also have background jobs, things like nightly workflows, scheduled pipelines, and cron tasks, running with no human attached.

Kinde handles this with machine-to-machine apps using the OAuth client credentials flow. The resulting token looks different from a user token:

{
  "aud": ["https://yourapp.kinde.com/api"],
  "azp": "your_client_id",
  "exp": 1234567890,
  "gty": ["client_credentials"],
  "iat": 1234567890,
  "iss": "https://yourapp.kinde.com",
  "org_code": "org_abc123",
  "scope": "read:users",
  "scp": [],
  "v": "2"
}

Two things to notice: there is no sub claim, and there is a gty claim set to ["client_credentials"]. That combination tells you this is a machine rather than a person.

The provider detects this and treats the token as a trusted system actor instead of rejecting it. You can check for it in your agent tools or route handlers:

import { isSystemActor } from 'mastra-auth-kinde'

const user = requestContext.get('user')

if (isSystemActor(user)) {
  // trusted background process — no human user attached
  console.log('running for org:', user.org_code)
}

So a nightly workflow can mint a Kinde M2M token, pass it to your Mastra API, and authenticate cleanly, with no human user required.

Step 4 — Org-based access control

If you're building a multi-tenant product where different organizations should only access their own agents and data, use allowedOrgCodes:

new MastraAuthKinde({
  domain: 'https://yourapp.kinde.com',
  allowedOrgCodes: ['org_abc123', 'org_def456'],
})

The provider checks the org_code claim on every token and rejects anything that doesn't match. This works for both user tokens (when org claims are enabled in Kinde) and M2M tokens, which carry org_code automatically when the app is org-scoped in Kinde.

On user tokens, org_code only appears once you've enabled org claims in the Kinde dashboard token customization settings, so if you decode a default user token and the claim is missing, that is a Kinde config step rather than a bug in the provider.

Step 5 — Edge deployment

The provider uses jose for JWT verification, which runs on Web Crypto and fetch, with no Node.js built-ins and no nodejs_compat flag needed on Cloudflare Workers.

This matters if you're planning to deploy your Mastra agent to the edge. Node-only JWKS libraries fail at build time on Workers with missing crypto, buffer, stream, http, https, events, and util. With jose, it builds clean and runs without any additional flags. This is the same approach Mastra's own Auth0 provider uses.

Putting it all together

Here's a full setup for a multi-tenant Mastra agent that supports both human users and background M2M workflows:

import { Mastra } from '@mastra/core'
import { Agent } from '@mastra/core/agent'
import { openai } from '@ai-sdk/openai'
import { MastraAuthKinde } from 'mastra-auth-kinde'

const supportAgent = new Agent({
  name: 'support-agent',
  instructions: 'You are a helpful support agent.',
  model: openai('gpt-4o-mini'),
})

export const mastra = new Mastra({
  agents: { supportAgent },
  server: {
    auth: new MastraAuthKinde({
      domain: process.env.KINDE_DOMAIN!,
      audience: process.env.KINDE_AUDIENCE,
      allowedOrgCodes: process.env.KINDE_ALLOWED_ORGS?.split(','),
    }),
  },
})

On the frontend, get the access token from the Kinde SDK and pass it as a Bearer token:

import { useKindeAuth } from '@kinde-oss/kinde-auth-nextjs'

const { getToken } = useKindeAuth()

const response = await fetch('/api/agents/support-agent/generate', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${await getToken()}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    messages: [{ role: 'user', content: 'Hello' }],
  }),
})

For background workflows, get an M2M token via the client credentials flow:

// Server-side only — never expose client_secret in the browser
const tokenResponse = await fetch(
  `${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.KINDE_AUDIENCE!,
    }),
  }
)

const { access_token } = await tokenResponse.json()

const agentResponse = await fetch('/api/agents/support-agent/generate', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${access_token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    messages: [{ role: 'user', content: 'Run the nightly summary' }],
  }),
})

Both token types work through the same provider, the same API, and the same Mastra instance.

What the provider exports

import {
  MastraAuthKinde,  // The main auth provider class
  isSystemActor,    // Returns true for M2M / client credentials tokens
} from 'mastra-auth-kinde'

Full options:

new MastraAuthKinde({
  domain: 'https://yourapp.kinde.com',     // Required
  audience: 'https://api.yourapp.com',      // Optional — only set after binding in Kinde
  allowedOrgCodes: ['org_abc123'],           // Optional — restrict to specific orgs
  name: 'kinde',                             // Optional — overrides the provider name
})

What's next

The provider is open-source and usable today at github.com/sholajegede/mastra-auth-kinde.

Kinde is free for up to 10,500 monthly active users, with no credit card required to start. You can create an account and try this provider against a test organization at kinde.com.

If this saved you time, drop a reaction. And if you're building something with Mastra agents, I'd love to hear about it in the comments.

How to Configure SAML Connections Programmatically With Kinde's Management API

Shola Jegede — Sun, 21 Jun 2026 20:58:13 +0000

You have forty enterprise customers, and every one of them needs its own SAML connection. You are not going to click through a dashboard forty times, and you definitely are not going to do it again every time one of them rotates a certificate. This is how you make the connection setup part of your onboarding flow instead of a recurring support ticket.

Configuring a single SAML connection by hand is fine. You open the Kinde dashboard, paste in a metadata URL, pick a Name ID format, save, and move on. The trouble starts when SAML stops being a one-off and becomes a repeatable step in how you onboard enterprise customers. Each customer's IT team sends slightly different details, a different Name ID format here, a stricter signing algorithm there, a binding their IdP happens to require, and every one of those becomes a manual configuration session that someone on your team has to run and then babysit.

At that point the dashboard is the wrong tool, and Kinde's Management API is the right one. Instead of a human entering values into a form, your onboarding flow makes an authenticated API call, the connection comes into existence in seconds, and your team is involved only when something genuinely needs a human. This article walks through how to build that, from authenticating to the API through to a provisioning service that creates, updates, and tears down SAML connections as customers come and go.

What you will learn

Why manual SAML setup quietly breaks once you have more than a handful of enterprise customers
How to authenticate to the Kinde Management API with a machine-to-machine application
How to create a SAML connection in a single API call, and what each of the key fields controls
How to map the details a customer's IT team sends you onto the right field values
When to update a connection in place versus replace it entirely, and the trap that sits between those two
How to use Kinde's strict validation to fail fast inside a provisioning pipeline rather than discovering a broken connection in production
How to wire all of this into an onboarding service that provisions, updates, and deprovisions connections automatically

When clicking through the dashboard stops scaling

The dashboard works beautifully for your first enterprise customer and remains tolerable for your second and third. The failure is gradual, which is part of why teams do not see it coming. Each new customer adds a configuration session, each session is a context switch for whoever runs it, and each connection becomes a thing that can drift, break, or need updating later. By the time you are at a couple of dozen customers, a meaningful slice of someone's week is spent inside the Kinde SAML form, and the work only grows from there.

There is a second cost that is easy to miss. When connection setup lives in a human's hands, it cannot be part of your product's onboarding flow. The customer signs the contract, and then they wait for your team to schedule the SAML work. Compare that to the version where your backend provisions the connection the moment the customer's plan upgrades to enterprise, hands their IT admin the ACS URL in the welcome email, and is ready before the admin has finished reading it. The difference between those two experiences is the difference between SSO as a support burden and SSO as a feature that sells itself.

The Management API is what moves you from the first world to the second. Everything below assumes that destination, a system where SAML connections are provisioned by code as a natural consequence of a customer becoming an enterprise customer.

How the pieces fit together

Before any code, it helps to hold the whole shape in your head, because the individual API calls make far more sense once you can see where they sit.

Your application's onboarding flow is the trigger. When a customer crosses into enterprise territory, whether that is a plan upgrade, a sales handoff, or a manual flag your team flips, that event calls into a small provisioning service you own. That service authenticates to the Kinde Management API using a machine-to-machine application, creates a SAML connection scoped to the customer's Kinde organization, and returns the details the customer's IT admin needs to finish their side. Later, the same service handles changes, a certificate rotation becomes an update, a switch to a different identity provider becomes a replacement, and a customer leaving becomes a deletion.

In Kinde's model, each enterprise customer maps to a Kinde organization, and the SAML connection is attached to that organization. That mapping is what keeps tenants isolated, since one customer's Okta setup has no bearing on another's Entra configuration, and it is also the key your provisioning service uses to know which connection belongs to whom.

Step 1: Authenticate to the Management API

Every call you make is authenticated with a short-lived access token, and you get that token from a machine-to-machine application. In the Kinde dashboard you create an M2M application under Settings then Applications, choosing Machine to Machine as the type, and Kinde issues it a client ID and client secret. You then authorize that application for the Management API and grant it only the scopes it needs, which for our purposes are the connection management scopes.

With the application authorized, your service exchanges its client credentials for an access token by calling the token endpoint. This is the same client credentials flow you would use for any backend-to-backend Kinde call.

// Exchange M2M client credentials for a Management API access token.
async function getManagementToken(): Promise<string> {
  const res = 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!,
      // The Management API audience for your Kinde domain.
      audience: `https://${process.env.KINDE_DOMAIN}/api`,
    }),
  });

  if (!res.ok) {
    throw new Error(`Token request failed: ${res.status}`);
  }

  const { access_token } = await res.json();
  return access_token;
}

The token is valid for a limited window, so a real provisioning service caches it and refreshes only when it is close to expiry rather than fetching a fresh one on every call.

Step 2: Create a SAML connection in one call

With a token in hand, creating a connection is a single authenticated POST to /api/v1/connections. The body carries a name, the strategy, and the SAML options that describe how Kinde and the customer's identity provider will understand each other. Kinde namespaces its strategy values, so a custom SAML connection uses saml:custom, sitting alongside built-in strategies like email:password and provider-specific ones like saml:google.

async function createSamlConnection(token: string, input: { name: string }) {
  const res = await fetch(`https://${process.env.KINDE_DOMAIN}/api/v1/connections`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: input.name,
      strategy: "saml:custom",
    }),
  });

  if (!res.ok) {
    const error = await res.json();
    throw new Error(`Create failed (${res.status}): ${JSON.stringify(error)}`);
  }

  // 201 → { code: "CONNECTION_CREATED", message: "...", connection: { id: "conn_..." } }
  return res.json();
}

A minimal create needs only name and strategy, and Kinde returns 201 with the new connection.id. You then add the SAML specifics through the connection's options object, either on this create call or in a follow-up update once you have the customer's details. The fields that live under options are covered next.

A successful call returns the new connection's identifier in connection.id, and you will want to store that against the customer's record, because it is the handle you use for every later update or deletion. After the call succeeds, the connection exists in Kinde and you can confirm it in the dashboard exactly as if a human had created it.

Step 3: Map what the customer sends you onto the right fields

Mapping the customer's details onto the four fields separates a script that works once from a provisioning system that holds up across dozens of different identity providers. No reference page walks you through it, because it is about judgement rather than syntax.

When a customer's IT team hands you their SAML details, they are giving you raw material that you have to translate into the four fields. Knowing which value goes where, and why each one matters, is what lets your service handle Okta, Entra, Google Workspace, and the long tail of less common providers without a human in the loop.

Field	What it controls	How to decide its value
`idp_metadata_url`	The public URL Kinde reads to learn the IdP's endpoints and signing certificate	Comes straight from the customer. Note that some providers, Google among them, will not host this at a stable URL, so the customer may give you a self-hosted link instead
`name_id_format`	How the user's unique identifier is represented in the assertion	Dictated by what the customer's IdP supports and is configured to send. Confirm it with their admin rather than assuming, since a mismatch here breaks sign-in
`saml_user_id_key_attr`	Which attribute in the assertion Kinde treats as the user identifier	Set this when the IdP carries the user ID in a non-standard attribute. Getting it right is what keeps a returning user mapped to the same Kinde identity instead of spawning duplicates
`sign_request_algorithm`	The algorithm used to sign the SAML request	Use `rsa-sha256`, the modern secure choice. Only fall back to `rsa-sha1` when a particular IdP still requires it, and treat that as a temporary accommodation
`protocol_binding`	The transport used to send the request to the IdP	Use `HTTP-POST` for signed requests and larger payloads, which is the common case, and switch to the redirect binding only when the IdP supports nothing else

Secure defaults matter because your provisioning service is making these choices for every customer at once. If your default signing algorithm is the strong one and you only step down when an IdP forces it, then your whole customer base is secure by default and the exceptions are visible and deliberate. If you let each customer's IT team push you toward whatever is easiest on their side, you end up with a fleet of connections whose security posture you cannot reason about.

Step 4: Update in place, or replace entirely

Connections are not static. Certificates rotate, customers migrate from one identity provider to another, and occasionally a field was simply set wrong and needs correcting. Kinde handles all of these through a single PATCH /api/v1/connections/{id} call, and the distinction that matters is how much of the options object you send.

A partial update changes specific fields while leaving the rest of the connection as it is. This is what you reach for in the common cases. A customer's IdP rotates its signing certificate and republishes its metadata, and you patch the metadata URL. A customer asks to move from the older signing algorithm to the modern one, and you patch that single field. These updates are surgical, and they are the right default. A successful call returns {"code": "CONNECTION_UPDATED"}.

A full replacement sends the entire options object when the change is wholesale rather than incremental, the clearest example being a customer migrating from, say, Okta to Entra ID, where almost everything about the connection is now different. You use the same PATCH endpoint, but you send the complete new configuration rather than a single field.

One trap bites people who treat a wholesale change carelessly. When you send an options object, treat it as the new state of those fields, so read the current connection first, merge your changes onto what is already there, and send the complete object. If you intend a full replacement and forget to include the signing algorithm you had carefully set, you risk losing it. Treat a partial patch as "change exactly these fields" and a full replacement as "here is the complete new configuration", and the trap disappears.

Step 5: Let validation fail fast for you

Kinde recently changed how it handles bad values. Previously, an invalid enum value might be accepted silently and quietly corrected at runtime, which is the kind of behaviour that hides a misconfiguration until a user cannot sign in. Now an invalid value for one of these fields returns a clear 400 error immediately.

For a provisioning service, this is a gift rather than an inconvenience. It means a malformed configuration fails at the moment you try to create it, in your pipeline, where you can catch it and surface it, instead of failing days later in a customer's sign-in flow where it becomes a support escalation. Let the 400 propagate into your onboarding system as a visible, actionable error.

try {
  const connection = await createSamlConnection(token, input);
  await saveConnectionId(input.organizationCode, connection.id);
  return { ok: true, connectionId: connection.id };
} catch (err) {
  // A 400 here means a bad field value. Surface it to your onboarding UI
  // so it is fixed now, not discovered by the customer in production.
  return { ok: false, reason: (err as Error).message };
}

Your provisioning service should treat connection creation the way you treat any other deploy. It either succeeds cleanly or it tells you precisely what was wrong, and a customer never becomes the person who discovers the mistake.

Step 6: The full lifecycle

Putting the pieces together, a provisioning service is a small, well-defined surface that your onboarding flow calls into. It provisions a connection when a customer becomes enterprise, updates it as the customer's setup changes over time, and removes it when the customer leaves so you are not carrying dead connections.

class EnterpriseSsoProvisioner {
  // Called when a customer upgrades to an enterprise plan.
  async provision(idp: { name: string; idpMetadataUrl: string; signRequestAlgorithm: "rsa-sha256" | "rsa-sha1" }) {
    const token = await getManagementToken();
    const { connection } = await createSamlConnection(token, idp);
    await saveConnectionId(connection.id);
    return this.handoffDetails(connection.id); // ACS URL + Entity ID for the customer's admin
  }

  // Certificate rotation, algorithm change, fixing a single field.
  // PATCH /api/v1/connections/{id} with only the fields that moved.
  async patch(connectionId: string, changes: Partial<SamlOptions>) {
    const token = await getManagementToken();
    return patchConnection(token, connectionId, { options: changes });
  }

  // Customer migrates to a different IdP: send the complete new options object.
  async replace(connectionId: string, fullOptions: SamlOptions) {
    const token = await getManagementToken();
    return patchConnection(token, connectionId, { options: fullOptions });
  }

  // Customer churns or downgrades.
  // DELETE /api/v1/connections/{id}
  async deprovision(connectionId: string) {
    const token = await getManagementToken();
    await deleteConnection(token, connectionId);
  }
}

The shape here is the real deliverable. Your sales and onboarding flows do not know or care about SAML internals. They call provision when a deal closes and deprovision when it ends, and the messy reality of metadata URLs and binding choices lives entirely inside this one service.

Step 7: Test the whole thing without a customer

You do not need a real enterprise customer, or even a real identity provider, to build and verify this. A throwaway Kinde account with a test organization is enough to exercise every call, and a few curl commands let you watch the real request and response shapes before you wire any of it into your product.

Run the create call against your test organization and confirm the connection appears in the dashboard. Send a deliberately invalid enum value and confirm you get the 400, so you know your error handling works. Update a single field and confirm only that field changed. Then delete it and confirm it is gone. Once those four behave the way you expect, you have validated the entire surface your provisioning service depends on, and you can build the rest with confidence.

Wrapping up

The forty-customer problem from the opening is, underneath, a question of whether SAML setup is something a person does or something your system does. Hand-configuring connections is fine until it is not, and the point where it stops scaling arrives sooner than most teams expect, usually right as enterprise deals start closing in earnest. Moving that work into the Management API turns a recurring manual chore into a provisioning service that runs as a natural part of onboarding, fails loudly and early when a value is wrong, and handles the full life of a connection from creation through certificate rotations to eventual teardown.

You authenticate once with a machine-to-machine application, create connections with a single call, map each customer's details onto the four fields that matter, choose update or replace depending on how much is changing, and lean on Kinde's strict validation to keep broken configurations out of production. The result is an onboarding flow where an enterprise customer's SSO is ready before their IT admin has finished reading the welcome email.

Kinde is free for up to 10,500 monthly active users, with no credit card required to start. You can create an account, set up a machine-to-machine application, and try these calls against a test organization at kinde.com, and the full Management API reference documents every field and operation in detail.

I write about identity, billing, and the infrastructure behind multi-tenant and AI products. If provisioning systems like this are your world, follow along for more.

How to Support IdP-Initiated SSO in Your App With Kinde

Shola Jegede — Sat, 20 Jun 2026 18:39:02 +0000

Your enterprise customer just emailed: "Our employees can't find your app in Okta. Can you add a tile?" If you have no idea what they mean, this article is for you. By the end of it you will know exactly what they are asking for, why the deal might stall without it, and how to deliver it with Kinde in an afternoon.

When you sell software to enterprises, the people who actually log in every day rarely navigate to your app the way a consumer would. They sit inside a company portal, something like Okta, Microsoft Entra ID, or Google Workspace, and they launch every approved application from a single dashboard of tiles. If your app is not one of those tiles, it does not really exist to them, and the IT team that controls that dashboard will tell you so in plain terms.

That request, "add a tile to our portal," is a request for IdP-initiated single sign-on. It is one of the quieter blockers in B2B sales, because it almost never comes up in a demo and almost always comes up right before a contract is signed. This guide walks through what the flow is, why enterprises insist on it, the security concern that has historically made it risky, and how Kinde handles the whole thing so that your application code barely changes.

What you will learn

What IdP-initiated SSO is, and how it differs from the SP-initiated flow you already know
Why enterprise IT teams require it before they will deploy your app
The security risk that is unique to this flow, and how Kinde absorbs it for you
How to enable IdP-initiated SSO on a Kinde enterprise connection
How to set up the matching app tile in Okta, Microsoft Entra ID, and Google Workspace
Exactly what to send your customer's IT admin so they can finish their side
How to test both directions of the flow before you go live

The two directions of SAML

Every SAML single sign-on flow has two participants. The Identity Provider, or IdP, is the system that owns the user's identity and verifies who they are. That is the customer's Okta, Entra ID, or Google Workspace. The Service Provider, or SP, is the application the user wants to reach. In a Kinde setup, Kinde is the Service Provider, and your app sits behind Kinde.

The difference between the two flows comes down to one question: who starts the login?

In SP-initiated SSO, the user starts at your app. They click a sign-in button, your app hands off to Kinde, Kinde routes them to their IdP, they authenticate, and they come back authenticated. This is the flow most developers build first, and it is the one most consumer logins use.

In IdP-initiated SSO, the user starts inside their company portal. They are already logged into Okta or Entra ID for the day, they click your app's tile, and they land in your app already authenticated. Your app never sent them anywhere. The login simply arrives.

In SP-initiated flow your app starts the conversation. In IdP-initiated flow the identity provider does, and the assertion arrives unsolicited.

These are two entry points into the same destination. A single enterprise connection in Kinde can serve both, and most enterprise customers will end up using both depending on where their employees happen to be when they need your app.

Why enterprise customers ask for this

Large organizations do not let employees manage their own logins for dozens of business applications. Instead, the IT team maintains a central portal where every approved app appears as a tile, and that portal becomes the front door to the entire software stack. There are real reasons this matters to them, and understanding those reasons helps you have the right conversation when the request lands.

The first reason is simply how people work. An employee at a financial services firm opens their Okta dashboard in the morning and launches everything from there. They do not bookmark your app's login page, and many of them would not be able to find it if asked. If your app is missing from the portal, adoption inside that company quietly stalls, because the path of least resistance does not include you.

The second reason is governance. Enterprise IT teams need every application that touches company data to be visible in their identity stack, both so they can provision access centrally and so they can revoke it the instant someone leaves. When a thirty-person team is deactivated, IT expects that turning off the account in their IdP turns off access everywhere, including your app, on the same day.

An application that lives outside that system is a gap in their audit trail, and that gap is exactly the kind of thing that fails a SOC 2 or ISO 27001 review.

So when a customer asks for a tile, they are really asking whether your app can become a well-behaved citizen of their identity governance system. IdP-initiated SSO is a large part of the answer, and being able to say yes quickly is often what keeps the deal moving.

The security risk you should understand first

IdP-initiated SSO has a reputation among security engineers, and understanding why matters even though Kinde handles the hard part for you. Knowing the risk lets you answer your customer's security team with confidence rather than a shrug.

In an SP-initiated flow, your side starts the conversation. Kinde generates a request with its own identifier before the user is ever sent to the IdP, and when the response comes back, Kinde can confirm that it matches a request it actually made. There is a built-in handshake. The response is expected, and anything unexpected can be discarded.

IdP-initiated flow removes that handshake. The assertion arrives without any prior request from the Service Provider, which is why it is sometimes called an unsolicited response. That property is convenient for the user, but it opens a specific attack.

If an attacker can capture a valid SAML assertion, perhaps from a shared machine or an intercepted session, they can replay it to the Service Provider and potentially sign in as the original user, because there is no earlier request to check the assertion against.

This class of issue is well documented, and it is the reason mature SAML implementations apply strict validation to unsolicited assertions rather than trusting them on arrival.

For you as a developer building on Kinde, the architecture is what makes this manageable. Because Kinde is the Service Provider, the SAML assertion is posted to Kinde, not to your app. Kinde receives the unsolicited response, validates it, and only then issues your app its own session token.

The replay protection, the assertion validation, the freshness and integrity checks, all of that lives inside Kinde's SAML handling. Your application never parses a raw assertion, never touches the SAML XML, and never has to implement these defenses itself. You receive a clean, validated Kinde session that looks exactly like any other login.

This is the single most important architectural point in this article. The reason this integration is mostly configuration rather than code is that Kinde absorbs the part that is genuinely dangerous to get wrong.

Before you start: how Kinde models enterprise customers

A quick mental model will make the configuration steps make sense. In Kinde, each enterprise customer maps to a Kinde organization, and enterprise connections live on those organizations. The customer brings their own identity provider, Kinde acts as the Service Provider in front of it, and your application always talks to Kinde rather than to the customer's IdP directly.

You can attach a SAML connection at the environment level, meaning it is available across your business, or scope it to a single organization, meaning only that one customer uses it. For a typical B2B setup where each enterprise has its own Okta or Entra tenant, you will usually create the connection on that customer's organization.

You will be working with a handful of values during setup, and it helps to know them by name before they appear on screen:

ACS URL (Assertion Consumer Service URL). This is Kinde's endpoint that receives the SAML response. You copy it from Kinde and give it to the customer's IT admin.
Entity ID. A shared identifier that must match exactly on both sides. In various consoles it appears as Entity ID, SP Entity ID, Audience, or entityID.
IdP metadata URL. A publicly reachable URL hosting the IdP's SAML metadata XML, which Kinde reads to stay current on the IdP's signing certificate.
Name ID format and key attributes. These describe how the user's identifier and details, such as email, first name, and last name, are carried in the assertion.

With those in hand, the setup is a matter of configuring two sides and making sure the shared values line up.

Step 1: Create or open the SAML enterprise connection in Kinde

Inside the Kinde dashboard, you reach a connection either through the customer's organization, by going to Organizations, opening the organization, and selecting Authentication, or at the environment level through Settings then Authentication. From there, in the enterprise connection section, you add a new enterprise connection and choose SAML, or open an existing SAML connection if you have already created one.

Give the connection a clear name, since this name becomes the label on the sign-in button your users may see. Once the connection exists, you configure its core SAML fields, which is the next step.

Step 2: Configure the core SAML fields

These fields define how Kinde and the customer's IdP understand each other. Most of them have sensible behavior, and you only need to be precise where the customer's IdP demands a specific value.

Name ID format. The Name ID is the element in the SAML assertion that uniquely identifies the user. The format you choose in Kinde must be one that the customer's IdP supports, so this is a value you confirm with their IT admin rather than guess.

Email key attribute. This tells Kinde which attribute in the SAML token carries the user's email. Setting it ensures the email comes through correctly, which matters both for identifying the user and for the friction-reducing behavior described later. Kinde recommends against leaving this blank, and will fall back to email if you do.

First name and last name key attributes. Optional, used for personalization and for mapping the user into your system cleanly.

Sign request algorithm. This is the cryptographic algorithm used to sign SAML requests. RSA-SHA256 is the secure, commonly used choice. RSA-SHA1 is older and widely deprecated, so you only select it if a particular IdP still requires it.

Protocol binding. This is the transport used to send the SAML request. HTTP POST sends it via an HTML form and handles larger, signed payloads, which is the common choice. HTTP Redirect sends it as a URL parameter and is lighter but size-limited. You match whatever the customer's IdP supports.

If you want a deeper reference for any of these, Kinde's advanced SAML configuration documentation covers each field in detail, but for most setups the defaults plus the customer's stated requirements are all you need.

Step 3: Turn on IdP-initiated SSO

Enabling IdP-initiated SSO is a single toggle. Kinde shipped support for it in February 2026. On the SAML connection, scroll to the IdP-initiated SSO behavior section and enable Accept requests.

The helper text spells out exactly what this does: it tells Kinde to accept unsolicited login requests sent to it by the identity provider, which is what allows the Kinde login page to be bypassed entirely when a user clicks the tile in their portal.

One detail here tells Kinde where to send the user after the unsolicited login lands, and getting it right is essential.

Kinde asks you to pass a relayState value in the IdP-initiated request, and that value is a target redirect URI carrying two parameters, client_id and connection_id. The client_id identifies which of your Kinde applications the user is signing in to, and the connection_id identifies which enterprise connection the assertion belongs to.

You configure this relayState on the identity provider side, in the app you set up there, so that every IdP-initiated login arrives pointed at the right application and connection. Without it, Kinde receives a valid assertion but has no instruction on where to take the user next.

Directly beneath the toggle is a second option, Use IdP email as login hint. Switching it on tells Kinde to carry the email from the SAML response into the login_hint query parameter, which lets the IdP skip its own account-selection screen when the user happens to be signed into more than one account. It is a small touch, but it removes a click for users who live in multiple Google or Microsoft accounts at once.

Two related options matter for a B2B setup. Trusting email addresses from the IdP lets Kinde match an incoming user to an existing account with the same email, rather than creating a duplicate identity, which makes for a more seamless sign-in. Single logout, if switched on, means that signing out of your app also signs the user out of the other apps on that connection, which some enterprise customers expect.

Step 4: Hand the ACS URL and Entity ID to your customer

With the Kinde side configured, copy two values to send to the customer's IT admin: the ACS URL and the Entity ID. These are the bridge between the two systems.

The ACS URL is where the IdP will post its SAML response, and it points at Kinde. The Entity ID is the shared identifier that has to match precisely on both sides. If you use a custom domain in Kinde, copy the custom domain version of the ACS URL instead of the default.

The Entity ID is the value most likely to cause a silent failure, because it shows up under different names in different consoles. In Kinde it is the Entity ID field. In the customer's IdP it might be labeled Audience, SP Entity ID, or simply Entity ID. If the strings do not match exactly, sign-in fails, often with an unhelpful invalid SAML response error.

So when you send these values, say explicitly that the Entity ID must be entered character for character on their side.

What to send your customer's IT admin

ACS URL, copied from Kinde

Entity ID, which must match character for character on both sides

The Name ID format you configured

A request for their IdP metadata URL in return

In return, you need one thing from them: the IdP metadata URL, a publicly reachable link to their SAML metadata XML. Kinde reads this URL so that the IdP's signing certificate stays current automatically.

One practical note, since it trips people up: some providers, Google Workspace among them, do not host the metadata file at a stable public URL, so the customer may need to host it somewhere reachable such as an S3 bucket, Cloudflare R2, or a public site, and give you that link.

Step 5: Set up the app tile on the IdP side

This is the half of the work that lives in the customer's identity provider, and it is the part that creates the tile. The exact clicks differ per provider, so here are the three most common, at the level of detail your customer's admin will recognize. Including them serves readers who are configuring both sides themselves, which many smaller enterprise admins do.

Okta

In the Okta admin console, the admin creates a new SAML application, enters the ACS URL and Entity ID from Kinde into the SAML settings, and configures the attribute statements so that email and name are passed through under the keys Kinde expects. Once the app is created and assigned to the relevant users or groups, it appears as a tile on those users' Okta dashboards.

Microsoft Entra ID

In the Entra admin center the admin goes to Enterprise applications, selects New application, then Create your own application, and chooses the option to integrate a non-gallery application. On the resulting app they open the single sign-on tile, select SAML, and edit the basic SAML configuration to add the Entity ID and ACS URL from Kinde. Entra carries email and name through claim attributes that use the schemas.xmlsoap.org claim URLs, and the admin copies the App federation metadata URL back to you as the IdP metadata URL.

Google Workspace

In the Google Admin console the admin goes to Apps, then Web and Mobile Apps, and chooses Add custom SAML app. After naming the app, Google shows its own identity provider details and a DOWNLOAD METADATA button, and because Google does not host that metadata XML at a stable public URL, the admin downloads it and uploads it somewhere reachable, such as a Cloudflare R2 bucket or a public file host, then provides that link as the IdP metadata URL.

On the Service provider details step the admin enters the ACS URL and the matching Entity ID from Kinde, sets the Name ID format to EMAIL, and sets the Name ID to Basic Information then Primary email. On the Attribute mapping step they map Primary email to the email key attribute Kinde expects, optionally adding first and last name, then finish and turn the app on for the chosen users so the tile appears.

Across all three, the shape is identical even though the labels move around: enter Kinde's ACS URL and Entity ID, map the attributes, hand back the metadata URL, and assign the app to users so the tile appears.

Step 6: Test both directions

Once both sides are configured and the connection is switched on, test the SP-initiated direction first, because it is the simpler check and it confirms the connection itself is sound. Open your app, trigger the enterprise sign-in, authenticate at the IdP, and confirm you land back in your app with a valid session. If you configured a home realm domain, the user is routed silently to the IdP. If not, they see a sign-in button labeled with your connection name.

Next, test the IdP-initiated direction. Go to the IdP portal as an assigned user, click your app's tile, and confirm you arrive in your app already authenticated, with no detour through a login screen. That is the IdP-initiated flow working end to end, and it is the experience your enterprise customer's employees will have every day.

A free Okta developer account or a test Entra tenant is enough to rehearse the whole thing before you involve a real customer, so that when a customer does ask, you can walk them through it from memory.

If something fails, the usual culprit is the Entity ID not matching exactly between Kinde and the IdP, followed by an unreachable or stale metadata URL. Both produce sign-in errors that look more mysterious than they are, so they are the first two things to recheck.

What your app code has to change

Almost nothing changes, and that is the whole point. Because Kinde is the Service Provider and absorbs the SAML handling, your application keeps talking to Kinde exactly as it already does. A user who arrives through the IdP-initiated flow shows up in your app as an authenticated Kinde session, indistinguishable in your code from a user who logged in any other way. There is no SAML parsing to write, no assertion to validate, no new endpoint to stand up on your side. The work you just did was configuration and coordination, which is precisely why this is something you can deliver to a customer quickly rather than scheduling a sprint for it.

// Your existing Kinde session check is unchanged.
// An IdP-initiated user arrives as a normal authenticated session.
import { getKindeServerSession } from "@kinde-oss/kinde-auth-nextjs/server";

const { isAuthenticated, getUser } = getKindeServerSession();

if (await isAuthenticated()) {
  const user = await getUser();
  // Same code path for every login method, IdP-initiated included.
}

The snippet above is illustrative of how little changes. The exact Kinde SDK call depends on your framework, and Kinde provides SDKs for React, Next.js, Node/Express, .NET, Flutter, Java, SvelteKit, Remix, Go, and Expo.

Wrapping up

The email that started this article, the one asking you to add a tile to a customer's portal, is no longer a mystery or a blocker. It is a request for IdP-initiated SSO, a flow where the identity provider starts the login and the assertion arrives unsolicited. Enterprises insist on it both for how their employees actually work and for the governance requirements that decide whether you pass a security review. The replay risk makes the flow sensitive, and Kinde, sitting in front of your app as the Service Provider, validates the unsolicited assertion so your code never has to.

The work is configuration rather than construction. Enable the Accept requests toggle on the Kinde connection, set the relayState with your client_id and connection_id on the identity provider side, exchange the ACS URL, Entity ID, and metadata URL with your customer's IT admin, set up the matching app on their Okta, Entra, or Google Workspace, and test both directions. Your customer's employees get a tile that drops them straight into your app, their IT team gets an application that behaves inside their identity governance, and the deal that was waiting on this keeps moving.

Kinde is free for up to 10,500 monthly active users, with no credit card required to start. You can create an account and configure your first enterprise connection at kinde.com, and the enterprise connections documentation walks through each provider in full detail.

Building something with Kinde and enterprise auth? I write about identity, billing, and agent infrastructure for developers. Follow along for more walkthroughs like this one.

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.

Environment > Authentication page showing the Passwordless section with Email + code, Phone, and Username + code tiles. The Phone tile has a " width="800" height="502">

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.

Phone providers showing the Twilio configuration with a WhatsApp section. Show the toggle or setting that enables WhatsApp as the preferred delivery channel, with SMS shown as the fallback" width="800" height="502">

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.

Multi-factor auth page showing the " width="800" height="501">

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.

Phone providers page showing the Twilio configuration panel with Account SID and Auth Token fields, and the WhatsApp delivery toggle enabled" width="800" height="501">

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.

Plans page showing the " width="800" height="502">

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.

Data management > Properties page showing the " start="" width="800" height="502">

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.

Feature flags page showing the " value="" width="800" height="502">

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

Environment > Feature flags page showing a list of flags with their values. The " value="" width="800" height="502">

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.

[Org name] > Feature flags page showing the list of flags and their values for this specific organization" width="800" height="502">

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.

[User name] > Feature flags tab showing the list of all flags and the user's current values. The " value="" width="800" height="502">

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.

Authentication page showing the Enterprise connections section with an " width="800" height="504">

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.

Self-serve portal showing the SSO configuration option with a toggle to enable customers to manage their own enterprise connections. The description text explains what customers can configure" width="800" height="502">

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:

Applications showing an application with " width="800" height="502">

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:

Permissions page showing a list of permissions: posts:create, posts:update, posts:delete, posts:publish, users:view, users:manage. Each has its key visible" width="800" height="502">

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:

Roles page showing three roles: Admin (key: admin), Editor (key: editor), Viewer (key: viewer" width="800" height="502">

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.

Permissions page showing a list of defined permissions with columns for key and description." width="800" height="501">

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:

and Billing. Cards show both Edit and Delete buttons.
Badge shows Admin · Sarah Chen" width="800" height="501">

Cards show Edit button only, no Delete.
Badge shows Member · Sarah Chen" width="800" height="501">

Cards show No actions available — no buttons at all.
Badge shows Viewer · Sarah Chen" width="800" height="501">

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.

DEV Community: Shola Jegede

Kinde Is Missing from Mastra's Auth Lineup, So I Built the Provider

What Mastra's auth system actually does

Why Kinde specifically

Installation

Step 1 — Basic setup

Step 2 — User token authentication

The audience option

Step 3 — M2M / system-actor support

Step 4 — Org-based access control

Step 5 — Edge deployment

Putting it all together

What the provider exports

What's next

How to Configure SAML Connections Programmatically With Kinde's Management API

When clicking through the dashboard stops scaling

How the pieces fit together

Step 1: Authenticate to the Management API

Step 2: Create a SAML connection in one call

Step 3: Map what the customer sends you onto the right fields

Step 4: Update in place, or replace entirely

Step 5: Let validation fail fast for you

Step 6: The full lifecycle

Step 7: Test the whole thing without a customer

Wrapping up

How to Support IdP-Initiated SSO in Your App With Kinde

The two directions of SAML

Why enterprise customers ask for this

The security risk you should understand first

Before you start: how Kinde models enterprise customers

Step 1: Create or open the SAML enterprise connection in Kinde

Step 2: Configure the core SAML fields

Step 3: Turn on IdP-initiated SSO

Step 4: Hand the ACS URL and Entity ID to your customer

Step 5: Set up the app tile on the IdP side

Okta

Microsoft Entra ID

Google Workspace

Step 6: Test both directions

What your app code has to change

Wrapping up

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

Step #4: Build the `useTrialStatus` Hook

The `auditLog` Helper

Step #1: Call `auditLog` Inside Your Mutations