DEV Community

Shola Jegede
Shola Jegede Subscriber

Posted on

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

#ai #kinde #mastra #webdev

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
Enter fullscreen mode Exit fullscreen mode

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

npm install @mastra/core
Enter fullscreen mode Exit fullscreen mode

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',
    }),
  },
})
Enter fullscreen mode Exit fullscreen mode

Or use environment variables:

KINDE_DOMAIN=https://yourapp.kinde.com
KINDE_AUDIENCE=https://api.yourapp.com  # optional — see the audience section below
Enter fullscreen mode Exit fullscreen mode 
export const mastra = new Mastra({
  server: {
    auth: new MastraAuthKinde(),
  },
})
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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"
Enter fullscreen mode Exit fullscreen mode

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
})
Enter fullscreen mode Exit fullscreen mode

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"
}
Enter fullscreen mode Exit fullscreen mode

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)
}
Enter fullscreen mode Exit fullscreen mode

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'],
})
Enter fullscreen mode Exit fullscreen mode

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(','),
    }),
  },
})
Enter fullscreen mode Exit fullscreen mode

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' }],
  }),
})
Enter fullscreen mode Exit fullscreen mode

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' }],
  }),
})
Enter fullscreen mode Exit fullscreen mode

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'
Enter fullscreen mode Exit fullscreen mode

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
})
Enter fullscreen mode Exit fullscreen mode

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.

Top comments (0)