DEV Community: Shola Jegede

How to Let an OpenAI Agent Act in a User's GitHub Without Storing API Keys

Shola Jegede — Fri, 14 Aug 2026 16:58:48 +0000

Picture this: A user in your app connects their GitHub account. They ask the agent to deal with an issue, so it reads the thread, writes a comment that answers the question, and opens a pull request with the fix. That comment has to appear under the user's name, because their teammates need to see who acted. So you run an OAuth flow, take the access token GitHub returns, and put it in a column beside the user's row. Every action after that reads the column.

Now look at what you just created. That column holds a standing secret. It works on the first day and it keeps working long after the reason for it has gone, because the user wanted one comment and the token stays until somebody deletes it. It carries whatever scopes were convenient when you set it up rather than the narrow thing the task needed. Worst of all, it multiplies. The token sits in your database, in last night's backup, in any log line that printed it during an incident, and in the memory of whichever worker read it a minute ago. When that user decides they want the agent out of their account, revocation turns into a hunt through all of those places, and you are asking them to trust that you will find every copy.

In this tutorial, you'll build a demo that answers the other question: what if the app never holds the token at all? An OpenAI agent reads issues, writes comments, and opens pull requests inside a user's real GitHub account, while the app stores no GitHub token anywhere. Kinde Connected Apps holds the GitHub authorization and the refresh token. A broker asks Kinde for a token at the moment of each action, uses it for that one call, and then drops it. The user cuts the agent off with one click.

By the end, you'll have built:

A token broker that every GitHub action passes through, with nothing else in the app calling GitHub
Two deployment modes, one that stores nothing and one that stores a standing key, so you can watch the difference
An OpenAI tool-calling loop that proposes actions and never sees a credential
A live connect flow through Kinde Connected Apps, and a kill switch that cuts the agent off
An audit trail where every brokered action, refusal, and revocation carries a correlation id
A runtime assertion that hunts for a stored credential after a real agent run
An end-to-end script that walks the whole story and exits non-zero when any check fails

Everything in this article comes from running that build against live services. Every number, reason code, and token shape below is measured, including one result that weakens the easy version of the story.

What You'll Build
Prerequisites
How the Demo Is Structured
Why a Stored Key Fails
The Connected Apps Primitive
How to Connect a User's GitHub
How to Build the Broker
How to Model the Data
How to Decide the Storage Mode
How to Build the Agent Loop
Two Revocation Levers, and One Is a Decoy
The Central Finding: Revocation Reaches the Connection, Not the Token
The Two Modes, Side by Side
How to Keep Least Privilege
What the Operator Controls
How to Harden It for Production
How to Prove the Tests Can Fail
Honest Limitations
What This Design Costs
What You've Built, and Where to Take It
Wrapping Up
Resources

What You'll Build

The operator signs in, connects GitHub, and writes a task in plain text. The console shows which deployment mode is running, how many tokens the app keeps, and what the agent has done so far.

Every step of a run streams into a live timeline. The agent asks for a tool, the broker performs it, and each row carries the correlation id that ties the timeline to the audit trail.

That run posted a real comment on a real issue, written by the signed-in GitHub account, while the app stored nothing.

Then the operator clicks Revoke. The GitHub connection is cut, the next action the agent asks for is refused, and the operator stays signed in to the app. You'll see both of those later, once the code behind them is in place.

Prerequisites

To follow along, you'll need:

Node 18 or later, and comfort with TypeScript. You don't need to be an expert, but you should be comfortable reading async/await and typed function signatures.

A Kinde account. The free tier covers everything here. You'll create a back-end web app for sign-in, a machine-to-machine app for the Management API, and GitHub as a connected app.

A GitHub account, and a repository you're happy to write to. The agent posts real comments, so use a throwaway repository rather than anything that matters.

An OpenAI API key, and a model that supports tool calls.

A Convex account for the data store. The free tier is enough.

Basic familiarity with OAuth helps but is not required, since the whole point of this build is that Kinde runs that flow for you.

How the Demo Is Structured

Every GitHub action follows the same path, and the storage mode decides only where the credential comes from:

operator writes a task
        │
        ▼
   OpenAI agent  ──── proposes an action, holds no token
        │
        ▼
     BROKER  ─────────┬─── connected-app: ask Kinde, use once, discard
        │             └─── stored-key:   use the token the app keeps
        ▼
     GitHub  ──── the comment appears as the user
        │
        ▼
   audit row  ──── correlation id, storage mode, outcome

The broker is the only module that obtains a credential, and the only module that calls GitHub. The agent sits above it and never touches either. A test walks the source tree and fails the build if a second GitHub caller ever appears.

Why a Stored Key Fails

This shape is now common enough that the largest AI vendor ships it. Company knowledge in ChatGPT connects to Slack, SharePoint, Google Drive, and GitHub, and answers from the data in those accounts (OpenAI). Workspace agents go further, because they run repeatable workflows, use connected apps, and complete tasks end to end (OpenAI). Agents act inside a user's own third party accounts today, so the credential question stops being a detail you can defer.

Two of the costs are measurable, and this build measured both.

The stored key carries far more access than the work needs. A token that a developer already had is the token that gets used. In this build the stored key carried gist, read:org, repo, and workflow. The four actions in the demo need public_repo and nothing else. The broker recorded that gap on every action, in the audit row itself.

Central revocation does not reach it. The app holds the token, so nothing you do at your identity provider touches it. I revoked the connection and the agent carried on writing to the repository for another four and a half minutes, and it would have carried on for hours.

The fix is not a better column, or tighter access control on the column. The fix is to stop holding the credential.

Where the token lives, in each mode. In stored-key the app keeps a long-life token in its own database and calls GitHub with it. In connected-app the app keeps nothing, so it asks Kinde for one short-life token for each action. The second path has one more hop, and that hop is the whole difference.

The Connected Apps Primitive

Kinde Connected Apps let your users reach third party tools through Kinde (Kinde docs). Kinde holds the GitHub authorization. Your app asks Kinde for a token when it needs one.

Three Management API endpoints matter. I read them from the published OpenAPI specification rather than from memory, because the documentation pages do not carry the parameter detail.

Operation	Method and path	Parameters
Get the auth URL	`GET /api/v1/connected_apps/auth_url`	`key_code_ref` (required), `user_id`, `org_code`, `override_callback_url`
Get a token	`GET /api/v1/connected_apps/token`	`session_id` (required)
Revoke	`POST /api/v1/connected_apps/revoke`	`session_id` (required)

The token response carries two fields and nothing else: access_token and access_token_expiry. The schema has no refresh token field. My app never receives one.

Note the first parameter name. It is key_code_ref, a reference string that you set on the connected app in the Kinde dashboard. It is not a connection id. I had assumed otherwise and had to rename an environment variable.

Your app keeps one value from this flow: the session_id. Kinde returns it on the callback. That handle is not a GitHub credential. It grants nothing on its own, it needs your Kinde machine to machine credentials to be useful, and Kinde stops honouring it the moment you revoke the connection.

In the Kinde dashboard, the connected app carries a name, the GitHub client id, the GitHub client secret, and a key. That last field is the key_code_ref your code sends, and here it reads github.

The Permissions tab is where least privilege gets set. The Scopes box holds one chip, public_repo, and every other GitHub scope below it stays switched off.

Search that list for a user scope and nothing comes back, which is why this build reads the acting GitHub login from the API response instead.

The user sees GitHub's own consent screen, and it asks for exactly what Kinde requested.

The Repositories row reads "Public repositories" and nothing else, which is the public_repo scope reaching the user. The Organization access block is separate: GitHub offers it on every OAuth consent screen, and this demo grants none of it.

How to Connect a User's GitHub

The connect flow has three parts, and your app stores one value from it.

First, ask Kinde for an authorization URL for this specific user.

export async function getConnectedAppAuthUrl(options: {
  kindeUserId: string;
  overrideCallbackUrl?: string;
  token?: string;
}): Promise<ConnectedAppAuthUrl> {
  const env = kindeManagementEnv();

  const response = await managementRequest<{
    url?: string;
    session_id?: string;
  }>({
    path: AUTH_URL_PATH,
    query: {
      key_code_ref: env.KINDE_GITHUB_CONNECTED_APP_KEY,
      user_id: options.kindeUserId,
      override_callback_url: options.overrideCallbackUrl,
    },
    token: options.token,
  });

  if (!response.ok || !response.body?.url || !response.body?.session_id) {
    throw new Error(
      `Kinde did not return a connected app auth url (HTTP ${response.status}).`,
    );
  }

  return { url: response.body.url, sessionId: response.body.session_id };
}

Second, send the user to that URL. GitHub shows its own consent screen. The URL that Kinde generated for my demo requested scope=public_repo and nothing more, and GitHub's screen showed "Public repositories" only.

Third, Kinde returns the user to your callback with the session handle in the query string:

/api/connect/github/callback?session_id=dc5e2e23f19749f08c1f73b4ee7af8c2

Store that handle against the user. My callback route marks the connection linked and writes an audit row. No token arrives in this request, and the route stores none.

await convex.mutation(api.gateway.markLinked, {
  secret,
  userId: operator.userId,
  kindeConnectionId: kindeManagementEnv().KINDE_GITHUB_CONNECTED_APP_KEY,
  kindeSessionId: sessionId,
  grantedScopes: ["public_repo"],
});

Be clear with yourself about what this handle is. It identifies a connected app session at Kinde. It carries no GitHub access on its own. Somebody who steals it still needs your Kinde machine to machine credentials to turn it into a token, and Kinde stops honouring it the moment you revoke.

How to Build the Broker

The broker is one function. Every GitHub action in the app passes through it. Nothing else in the app calls GitHub.

Start with the credential step, because that is where the two modes differ.

export async function acquireConnectedAppToken(
  source: ConnectedAppSource,
): Promise<CredentialResult> {
  // Fail closed before Kinde is even asked.
  if (source.status !== "linked") {
    return {
      ok: false,
      status: 0,
      reason: `The GitHub connection is ${source.status}. Refusing to act.`,
    };
  }
  if (!source.kindeSessionId) {
    return {
      ok: false,
      status: 0,
      reason: "No connected app session for this user. Refusing to act.",
    };
  }

  const result = await fetchConnectedAppToken(source.kindeSessionId);
  if (!result.ok) {
    // INVALID_SESSION lands here after a revocation.
    return { ok: false, status: result.status, reason: result.reason };
  }

  return { ok: true, token: result.token.accessToken, source: CONNECTED_APP };
}

Now the stored key path. Read what it does not do.

export function acquireStoredKeyToken(): CredentialResult {
  try {
    return {
      ok: true,
      token: storedKeyEnv().GITHUB_STORED_TOKEN,
      source: STORED_KEY,
    };
  } catch {
    return {
      ok: false,
      status: 0,
      reason:
        "STORAGE_MODE is stored-key but GITHUB_STORED_TOKEN is not set. Refusing to act.",
    };
  }
}

This function never contacts Kinde. It never checks the connection status. That is not an oversight. It is the bug that the demo reproduces on purpose. Because nothing in this path asks Kinde, revocation at Kinde cannot reach it.

The broker binds the token into a call function and hands the call function to the action handler.

export function createGitHubClient(token: string): GitHubCall {
  return async function call<T>(path, options = {}) {
    const response = await fetch(url, {
      method: options.method ?? "GET",
      headers: {
        authorization: `Bearer ${token}`,
        accept: "application/vnd.github+json",
        "x-github-api-version": "2022-11-28",
        "user-agent": USER_AGENT,
      },
      cache: "no-store",
      signal: AbortSignal.timeout(GITHUB_TIMEOUT_MS),
    });
    // ...
  };
}

The token lives inside the closure. A handler receives call, not the token. A handler therefore cannot read, copy, log, or store a credential, because it never holds one.

The broker then runs the action and writes an audit row.

// 4. Act. The handler is given a bound caller, never the token.
const target = gitHubTargetEnv();
const call = createGitHubClient(credential.token);
const handler = getHandler(action.id);

const result = await handler(call, input as never, {
  owner: target.GITHUB_TARGET_OWNER,
  repo: target.GITHUB_TARGET_REPO,
});

await audit("action.invoked", "allowed", result.summary, user._id);
// The token goes out of scope here. Nothing wrote it anywhere.

Here is the whole path, including every way it can end.

Every path an action can take through the broker. An unregistered name never reaches a credential. A missing or refused token ends in token.refused. A GitHub error ends in a recorded failure. A success ends with the token going out of scope. Each ending writes an audit row, so no action leaves the broker without a record.

Every path ends in an audit row. The row carries a correlation id, so the run timeline and the audit trail join on one value.

How to Model the Data

The store has six tables: users, connections, actions, runs, run events, and the audit log.

The connections table records state only. It holds the status, the GitHub login, the granted scopes, the linked and revoked timestamps, and a counter of how many tokens Kinde has supplied. It holds no credential in either mode.

Writing that rule in a comment would prove nothing, so I wrote a test that walks the runtime validator tree of every table and fails on any field name that looks like a credential.

it("holds no field that could store a GitHub credential", () => {
  const forbidden =
    /(access_?token|refresh_?token|^token$|bearer|secret|credential|client_?secret|api_?key|private_?key)/i;

  for (const [table, definition] of Object.entries(tables)) {
    const names = [...fieldNames(definition.validator.json)];
    expect(names.length).toBeGreaterThan(0);
    const offenders = names.filter((name) => forbidden.test(name));
    expect(
      offenders,
      `table "${table}" declares credential-shaped fields: ${offenders.join(", ")}`,
    ).toEqual([]);
  }
});

The test reads the compiled schema rather than the source text. Somebody who adds a token column later breaks the build, and they break it for a clear reason.

The audit log carries the outcome of every decision. Six event types cover the whole surface: connection.linked, connection.revoked, token.brokered, token.refused, action.invoked, and action.refused. Three outcomes describe what happened: allowed, refused, and failed.

Every row also carries the storage mode. That single field is what lets the audit trail show both modes in one table and make the difference obvious.

Everything that changes state is an internal mutation. The browser cannot forge an audit row, and it cannot flip a connection to linked. The server reaches those functions through one gateway that requires a shared secret, and the browser does not have that secret.

One detail is worth copying. The broker writes a token row for each action rather than one row per run. A three action run produces three token.brokered rows:

18:25:38  token.brokered  allowed  connected-app  Fetched a token from Kinde for one action. Not stored.
18:25:42  action.invoked  allowed  connected-app  Read 3 open issue(s) ...
18:25:47  token.brokered  allowed  connected-app  Fetched a token from Kinde for one action. Not stored.
18:25:50  action.invoked  allowed  connected-app  Read issue #1 ...
18:25:59  token.brokered  allowed  connected-app  Fetched a token from Kinde for one action. Not stored.
18:26:01  action.invoked  allowed  connected-app  Commented on issue #1 as sholajegede.

Fetch per action stops being a claim in your README. It becomes a pattern in your data that anybody can count.

How to Decide the Storage Mode

The mode must not be something a request can influence. I put the whole rule in one pure function.

export function resolveStorageMode(raw: string | undefined | null): StorageMode {
  return raw === STORED_KEY ? STORED_KEY : CONNECTED_APP;
}

Only the exact string stored-key selects the unsafe mode. Every other value resolves to connected-app. That covers unset, empty, STORED-KEY, stored_key, a trailing space, and anything an attacker injects.

The only caller reads process.env.STORAGE_MODE and nothing else. No request, header, cookie, or query parameter appears anywhere in that path. The reader also throws if it ever runs with window defined, so a client component cannot pull it into the browser bundle.

How to Build the Agent Loop

The agent proposes actions. The broker performs them. The agent holds no credential.

The tool list comes from the action registry, so the agent cannot be offered a capability that the registry does not define.

export function agentTools(): AgentTool[] {
  return listActions().map((action) => ({
    type: "function",
    name: action.id,
    description: describe(action),
    parameters: toJsonSchema(action.input),
    strict: false,
  }));
}

The loop reads the model id from configuration. It never appears as a literal in the source.

const response = await openai.responses.create({
  model,
  input: conversation,
  tools,
});

const requested = response.output.filter(
  (item): item is Extract<typeof item, { type: "function_call" }> =>
    item.type === "function_call",
);

for (const toolCall of requested) {
  await emit("agent.tool_requested", `Requested ${toolCall.name}.`);

  // The one and only path to GitHub.
  const outcome = await brokerAction({
    actionId: toolCall.name,
    input,
    kindeUserId: request.kindeUserId,
    correlationId,
    runId,
  });
  // ...
}

I use the Responses API rather than chat completions for a measured reason. The model family I tested rejects function tools on /v1/chat/completions unless reasoning is switched off:

chat  effort=none     OK tool_calls=1
chat  effort=low      ERR 400 Function tools with reasoning_effort are not supported
responses api         OK  types=function_call

Staying on chat completions would have meant disabling the model's reasoning to get tools. The Responses API carries both.

When the broker refuses for lack of a credential, the agent stops. It does not retry, and it does not reach for another tool.

// Fail closed. A credential refusal will not resolve itself, so the
// run stops here rather than looping or reaching for another route.
if (outcome.status === "refused" && outcome.refusal === "credential") {
  halt = true;
  status = "refused";
  finalMessage = `Stopped: ${outcome.reason}`;
}

The broker returns a typed refusal kind so this check is structural, not a string match.

Refusal kind	Meaning	Caller behaviour
`credential`	No token now, and none coming	Stop
`input`	The arguments failed validation	Correct and retry
`unknown-action`	The name is not in the registry	Stop
`no-user`	No such user	Stop

I drew that line on purpose. An input refusal is the model's own mistake, and letting it fix the arguments is self correction rather than a blind retry of a denied action.

Four structural tests hold the agent honest. The agent module never imports the GitHub client, never names the GitHub API host, never reads a credential from the environment, and contains no storage mode branch at all. A test walks the source tree and fails the build if any of these change.

Two Revocation Levers, and One Is a Decoy

The Kinde Management API exposes two things that sound like a kill switch. Only one is.

I tested both against the live service.

Lever A: DELETE /api/v1/users/{user_id}/sessions.

DELETE sessions: HTTP 200 in 420ms
{"code":"USER_SESSIONS_INVALIDATED","message":"User sessions successfully invalidated"}

Then I polled the token endpoint every two seconds:

  +  2303ms  STILL ISSUING  HTTP 200  (fingerprint 7ea1fb9d9fa2)
  ...
  + 60011ms  STILL ISSUING  HTTP 200  (fingerprint 7ea1fb9d9fa2)

Kinde was still issuing tokens 60000ms after revocation, across 23 attempts.

Twenty three consecutive requests over a full minute. Every one returned HTTP 200. Every one returned the same token.

The endpoint reports success and stops nothing. The reason shows in the data. Before the test, GET /users/{id}/sessions returned "sessions": [], an empty list, while the connection was live and issuing tokens. A connected app session is not a user session. They are separate objects, and the user sessions endpoint does not reach the connected app.

If you build a kill switch on this endpoint, it returns HTTP 200, it logs success, and it cuts off nothing.

Lever B: POST /api/v1/connected_apps/revoke.

POST /api/v1/connected_apps/revoke   HTTP 200 in 151ms
{"message":"token revoke successful","code":"REVOKE_SUCCESSFUL"}

  +     0ms  REFUSED  HTTP 400  INVALID_SESSION: Error encountered while
                                retrieving tokens for connected app

The very next request failed. Not eventually. The first call after the revoke returned HTTP 400 with INVALID_SESSION.

This is the kill switch. I pinned it in code and in a test.

export async function revokeConnection(
  request: RevocationRequest,
): Promise<RevocationResult> {
  // ...
  const result = await revokeConnectedAppSession(connection.kindeSessionId);

  if (!result.ok) {
    const reason = `Kinde refused the revocation (HTTP ${result.status}).`;
    await audit("failed", reason, user._id);
    return { status: "failed", reason, httpStatus: result.status };
  }

  // Record the revocation locally too. The broker refuses on its own
  // authority once the connection reads `revoked`, rather than depending on
  // Kinde's refusal alone.
  await convex.mutation(api.gateway.markRevoked, { secret, userId: user._id });

The test asserts that the revoke module calls revokeConnectedAppSession, never mentions deleteUserSessions, and that the only file in the whole tree that calls the user sessions endpoint is the probe script where I measured it. A later edit that simplifies onto the decoy fails the build.

The Central Finding: Revocation Reaches the Connection, Not the Token

Now the result that matters most, and the one that weakens the easy version of this story.

After connected_apps/revoke succeeds and Kinde refuses to broker, does a token that Kinde already handed out still work at GitHub?

I measured it. I brokered a token, held it, revoked the connection, confirmed Kinde refused, then kept calling GitHub with the token I already had.

Step 1  broker a token and hold it        gho_ fingerprint ffda970320cd
Step 2  held token works before revoke    GET /user HTTP 200
Step 3  POST connected_apps/revoke        HTTP 200 in 177ms
Step 4  can Kinde still broker a token?   REFUSED HTTP 400 INVALID_SESSION
Step 5  does the HELD token still work?
          +   397ms  GET /user HTTP 200  STILL VALID
          +  6115ms  GET /user HTTP 200  STILL VALID
          + 13055ms  GET /user HTTP 200  STILL VALID
          + 19051ms  GET /user HTTP 200  STILL VALID
          + 30235ms  GET /user HTTP 200  STILL VALID
          + 37646ms  GET /user HTTP 200  STILL VALID

Kinde refused to broker in the same second that GitHub was still serving the token it had already issued. Six calls over 37.6 seconds. Every one returned HTTP 200.

Revocation at Kinde does not reach into GitHub. It stops Kinde from brokering and from refreshing. It does not cancel an outstanding token.

So the instant cutoff in connected-app mode is real, but the reason is not the one you might assume. The cutoff is instant because the broker keeps nothing between actions. The next action must ask Kinde. Kinde refuses. The action stops. There is no credential left inside the app for anything to keep using.

This has a direct consequence for your code. Do not cache the brokered token, not even for a few seconds. A cache is a window of access that survives the kill switch. In this design, fetch per action is a security boundary rather than a performance choice.

One revocation, and what each mode does next. Kinde stops brokering at once, so the connected-app broker gets INVALID_SESSION on its next request and the agent stops. The stored-key app never asks Kinde, so it keeps acting and its comment lands after the revocation. GitHub is the third party in this picture, and it honours the token it already issued until that token expires.

The Two Modes, Side by Side

I ran both modes against the same revocation and recorded what happened.

The revocation landed at 18:41:52 UTC. Here is the audit log across both modes, ordered by time.

time      mode           event              outcome   detail
18:41:31  connected-app  action.invoked     allowed   Commented on issue #3 as sholajegede.
18:41:52  connected-app  connection.revoked allowed   Connection revoked at Kinde.
18:42:20  connected-app  token.refused      refused   The GitHub connection is revoked.
18:45:52  connected-app  token.refused      refused   INVALID_SESSION: ...
18:46:17  stored-key     token.brokered     allowed   Used the token the app holds. Kinde was not consulted.
18:46:32  stored-key     action.invoked     allowed   Commented on issue #2 as sholajegede.

The stored-key comment is real. It has a GitHub comment id and a created_at of 2026-08-14T18:46:31Z, which is 4 minutes and 39 seconds after the revocation. An agent that the operator believed they had cut off carried on writing to the repository.

Every stored-key audit row says why, in the row itself: "Used the token the app holds. Kinde was not consulted."

The connected-app side shows two independent layers. The first refusal came from the local flag, because the broker marks the connection revoked and then refuses on its own authority. To check that Kinde also refuses, I forced the local flag back to linked while the Kinde session stayed revoked, and ran again:

3  broker.refused   INVALID_SESSION: Error encountered while retrieving tokens for connected app

INVALID_SESSION straight from Kinde, with the app's own bookkeeping claiming the connection was fine. Either layer stops the agent on its own. The cutoff does not depend on your local state being correct.

After the revoke. The GitHub connection is cut. The operator stays signed in to the app.

That last point matters and I tested it live. Revoking the GitHub connection does not end the app session. I clicked Revoke, then reloaded the page in the browser. The header still read the operator's name. The connection read revoked. The user keeps their session with your product and loses only the third party connection they chose to cut.

Ask the agent for something after the revoke, and the run stops on the first tool call.

The agent asks for one tool, the broker refuses, and the run halts. No retry, and no second route.

How to Keep Least Privilege

The registry defines four actions and nothing else. The agent cannot name its way to a capability that does not exist, because getAction() throws on anything unregistered.

Action	Effect	Acts as the user	Scope
`read_issues`	Reads	No	`public_repo`
`read_issue`	Reads	No	`public_repo`
`comment_issue`	Writes	Yes	`public_repo`
`open_pr`	Writes	Yes	`public_repo`

I first wrote the registry with public_repo and read:user, so the audit trail could record who acted. Then I hit a real constraint. Kinde's GitHub scope picker does not offer read:user. The connection grants public_repo and nothing else.

A registry that claims a scope the connection cannot hold is simply wrong, so I dropped it. The identity still gets recorded, because GitHub echoes the acting account back in the responses the actions already make.

export function actingUserFrom(payload: unknown): ActingUser | null {
  if (!payload || typeof payload !== "object") return null;
  const body = payload as MaybeUser;

  // A nested `user` is the shape returned by comments and pull requests.
  const candidate =
    typeof body.user?.login === "string"
      ? body.user
      : typeof body.login === "string"
        ? body
        : null;

  if (!candidate || typeof candidate.login !== "string") return null;
  return {
    login: candidate.login,
    id: typeof candidate.id === "number" ? candidate.id : null,
  };
}

A comment response carries { user: { login } }. GET /user needs no scope at all. When a response carries no identity, the function returns null and the app audits the action without a login. The app does not widen the connection to get one.

The broker also compares the scopes GitHub reports against what the registry claims, and records both directions. In connected-app mode the audit row reads:

Read 2 open issue(s) in sholajegede/connected-apps-github-sandbox.
Least privilege holds: the credential carries exactly what the action needs.

In stored-key mode the same code reads:

Over-privileged: the credential also carries gist, read:org, workflow,
which this action does not need.

That is the second failure of the stored key, visible in the audit trail. The stored key is not only impossible to revoke centrally. It is also far broader than the work needs, because a token that a developer already had tends to be the token that gets used.

What the Operator Controls

The demo gives the user the controls rather than a video of somebody else using them.

The operator signs in with their own session. They connect GitHub themselves. They write the task in free text, so nothing is a canned script. They watch each step arrive in a live timeline, and they cut the connection when they choose.

The console shows five counts, and each one answers a question a reader will ask.

Count	What it answers
Tokens supplied	How often the broker asked Kinde
GitHub tokens that the app keeps	Zero in `connected-app`, one in `stored-key`
Actions done on GitHub	What really happened in the repository
Actions refused	How often the broker said no
Actions after revocation	Zero in `connected-app`, above zero in `stored-key`

The second count is not derived from the data. It is a property of the deployment, decided on the server and passed down for display. The console shows it and can never set it. The same holds for the storage mode badge in the header.

The last count is the one to watch during a demo. It shows a dash until the operator revokes. After that it turns green at zero in connected-app, and red at a real number in stored-key.

How to Harden It for Production

A demo becomes trustworthy when the failure paths behave.

Give every outbound call a deadline. A hang is an outage from the caller's point of view, and an action that waits forever can never fail closed. I set 8 seconds on Kinde and 12 seconds on GitHub. I tested the Kinde deadline by pointing the issuer URL at an unroutable address:

outcome        refused
reason         Kinde did not answer within 8000ms.
audit:  token.refused  refused  connected-app  Kinde did not answer within 8000ms.

Before I added this, that path threw past the broker with no audit row at all. The credential step sat outside any try block. The fail closed claim was false for exactly the case that needed it most. Finding this is the reason to test outages rather than reason about them.

Refuse an action you cannot record. The broker writes the token.brokered row before it calls GitHub. If that write fails, the action does not happen.

if (!recorded) {
  const reason =
    "The audit trail is unavailable. Refusing to act rather than act without a record.";
  return {
    status: "refused",
    actionId: action.id,
    storageMode: mode,
    reason,
    refusal: "credential",
  };
}

The row also goes to an append only local queue first, so the attempt stays recoverable rather than lost.

Never log a token. The broker redacts every GitHub token shape from any text it records, and reports tokens by fingerprint.

const CREDENTIAL_PATTERN =
  /gh[pousr]_[A-Za-z0-9]{16,}|github_pat_[A-Za-z0-9_]{16,}/g;

export function redactCredentials(text: string): string {
  return text.replace(CREDENTIAL_PATTERN, "[redacted]");
}

A fingerprint is enough to answer real questions without exposing anything. It is a truncated SHA-256 of the token. Two fetches can be compared for equality, and the value itself never appears.

Prove the claim at run time. A comment in the source is not evidence. This script runs a real agent task, then looks for a credential everywhere the app could have put one: every row of every table, everything the code printed, the agent's own transcript, and the process environment.

Step 2 — scan every row of every table in the store
  actions      4 row(s) scanned
  auditLog     56 row(s) scanned
  connections  1 row(s) scanned
  runEvents    78 row(s) scanned
  runs         10 row(s) scanned
  users        1 row(s) scanned

Verdict
CLEAN — connected-app mode.
No GitHub credential is in the store, in the broker's output, or in
the environment.

The same script run in stored-key mode reports FOUND GitHub OAuth token (gho_) in env.GITHUB_STORED_TOKEN, and stays clean everywhere else. The same assertion, the same code, and a different answer per mode. That contrast is the point.

One detail makes this proof meaningful. The stored key lives in a separate file that the app loads only when the mode is stored-key. If it sat in the main environment file, it would be in process.env on every run, and the environment scan would be worthless.

How to Prove the Tests Can Fail

A green test suite means nothing until you have seen it go red.

The end to end script walks the whole story in one pass: clean slate, a connected-app run that comments on a real issue, a revoke, a refused run, a stored-key run after the same revoke, and a reconciliation across both modes. It asserts real outcomes and exits non-zero on any failure.

Each acting step runs in a child process with its own STORAGE_MODE. The mode is a deployment decision, and a script that flipped it in its own process would quietly contradict the property it tests.

Green looks like this:

GREEN — every assertion held. 69.3s

Then I inverted the load bearing check. Step 4 asserts that the stored-key agent still acts after the revocation. I changed status === "succeeded" to status !== "succeeded", so the assertion demanded the opposite of the measured truth:

RED — 1 assertion(s) failed. 54.3s

  4. stored-key — the same revocation, and the agent acts anyway
    the agent still acts after the connection was revoked
    status=succeeded — Reviewed the open issues and commented on issue #1 ...

EXIT CODE = 1

Exit code 1. The report names the step, the assertion, and the observed value. Every other assertion still passed, so the failure stayed isolated rather than cascading. I then restored the file and verified the restoration by hash rather than by eye, so the green result stands for the exact file that ships.

Honest Limitations

Read these as written. Do not soften them.

Revocation does not cancel a token that GitHub already issued. Kinde stops at once. A token already handed out stays valid at GitHub until it expires. I measured it still valid 37.6 seconds after the revoke, and nothing in the revoke path touches GitHub. To cancel the outstanding token, somebody revokes it at GitHub. That control belongs to GitHub, and Kinde does not have it. It sits on the OAuth app's own settings page.

The token life is real, and it depends on one setting. The brokered token is an opaque 40 character gho_ token. It is not a JWT, so there is nothing to decode. Kinde reported an expiry of 2026-08-15T02:09:08.871+01:00, which was 28761 seconds ahead, or 7.99 hours. That matches GitHub's documented eight hour user access token (GitHub docs). GitHub issues it that way because the OAuth app has Token expiration switched on, under Optional features. GitHub's own wording for that setting states the eight hours, and states something else worth reading twice.

"Existing tokens are not affected." GitHub is describing what happens when you toggle the setting, but the same principle runs through this whole article: a token already issued keeps its own life. Turn the setting off and the token never expires at all, and this whole argument gets weaker.

Kinde returns the same token again, not a new one. Two requests inside the same eight hour window returned the identical token, confirmed by fingerprint:

fingerprint    7ea1fb9d9fa2
second fetch   fingerprint 7ea1fb9d9fa2 — SAME token replayed

So the correct claim is fetch per action, store never. The claim is not that each action gets a fresh token. The security property comes from the app holding nothing between actions.

Kinde holds the refresh token. The app never receives one. The evidence is positive rather than merely absent. An eight hour token can only be renewed with a refresh token, so one exists, and it never reaches my app. My app cannot renew access on its own.

The read queries in my demo use an id, not access control. Every write needs a server secret that the browser does not have, so the browser cannot forge a record or change the mode. The read queries trust the id they receive. That is enough for a single operator demo. It is not access control, and I would wire the identity provider into the data layer before shipping this to many users.

What This Design Costs

Be honest about the trade you make.

You add a network call to every action. The broker asks Kinde before it calls GitHub. In my measurements a successful token request took 439ms and 468ms. For an agent that makes three tool calls, that is about 1.4 extra seconds per run. You cannot buy that back with a cache without giving up the property that makes revocation work.

You add a dependency to the hot path. If Kinde is down, your agent stops. I treat that as correct behaviour rather than a fault, because the alternative is to keep a credential that nobody can take back. Your deadline and your refusal message then matter, since users will see them.

You need somewhere to put the session handle. The app stores no token, but it does store the handle and the connection state. That is a small table, and it holds nothing that works on its own.

You give up one convenience. With a stored key, any part of your codebase can call GitHub. With a broker, everything routes through one function. That is the point, and it does mean a small amount of plumbing when you add an action.

The trade buys you three things. The user can cut the agent off centrally. Your database holds no live third party access. And your audit trail records every decision, including the ones where the broker said no.

What You've Built, and Where to Take It

You've built a complete path: a user signs in, connects GitHub through Kinde, and an OpenAI agent acts in their account while the app stores no GitHub token. One revocation cuts the agent off within a single action, and the operator stays signed in.

The shape transfers to any third party API, not only GitHub. Eight things are worth carrying over.

Put one function between your code and the third party. Everything goes through it. Add a test that walks your source tree and asserts exactly one module names the API host. Structure beats discipline, because the test fails the build and a convention does not.

Give handlers a bound caller, not the credential. If a function never holds a token, it cannot leak one. This removes a whole class of review question.

Decide the mode on the server, from deployment configuration. Make the unsafe value an exact match and let everything else fall to the safe one. Then a typo fails safe.

Make a refusal a normal result. The broker returns a typed outcome instead of throwing. Callers handle refusal as data, and the audit trail records it like anything else.

Distinguish refusal kinds. A missing credential means stop. A bad argument means the caller can fix it. Blurring the two either produces retry loops or blocks legitimate self correction.

Fetch per action and keep nothing. This is the part that makes central revocation bite. If you cache, you reopen the window.

Test the outage, do not reason about it. Point the issuer URL somewhere unroutable and see what your code does. I found a real bug that way.

Write down the limitation that hurts. The demo is stronger when it says plainly that revocation does not reach an already issued token. A reader who discovers that on their own stops trusting everything else you wrote.

Wrapping Up

The demo makes one argument, and it holds up under measurement. An agent can act inside a user's real GitHub account without your app ever storing a GitHub token, and the user can cut it off centrally.

The part worth remembering is the reason it works. Revoking at Kinde does not reach into GitHub and cancel a token that GitHub already issued, and I measured that token still working 37.6 seconds later. The cutoff is instant because the broker keeps nothing between actions, so no credential is left inside the app for the agent to keep using. Cache the token for even a few seconds and you give that property away.

Take the honest limitation with you as well. To cancel an outstanding token too, the user revokes the authorization on GitHub, and that control belongs to GitHub rather than to Kinde.

Resources

Source code

The complete demo is on GitHub under the MIT licence, so you can run it, read it, and reshape it. The README carries the same measured limitations as this article.

Core documentation

Kinde: add connected apps: the auth_url, token, and revoke flow this build uses
GitHub: refreshing user access tokens: the eight hour token life and the refresh token
GitHub: token expiration and revocation: what expires, and what a user can revoke themselves
GitHub: authorizing OAuth apps: the consent screen the user sees

Context for the problem

OpenAI: company knowledge in ChatGPT: connectors for Slack, SharePoint, Google Drive, and GitHub
OpenAI: workspace agents in ChatGPT: agents that run workflows across connected apps

Build tooling

Next.js App Router: the server actions and route handlers the console uses
Convex: the data store behind the audit trail and the live timeline
OpenAI Responses API: the tool-calling endpoint the agent loop uses
Vitest: the runner behind the structural tests

How to Require Step-Up Auth Before a Claude Agent's Destructive Actions With Kinde

Shola Jegede — Thu, 13 Aug 2026 23:33:34 +0000

An agent deleted a document at 22:45. The person who authorised it had signed in at 16:57.

Nobody was at the keyboard. No token had expired. No rule was broken. The access token was valid for another nineteen hours, and it said exactly what it said six hours earlier: this person is allowed to delete documents. The agent read that as permission and acted.

The token was right about identity. It was silent about presence.

In this tutorial, you'll build a records console where a Claude agent runs read-only tools freely, and every destructive action, delete, refund, and deploy, stops at a server-side check. That check asks one question: how long ago did a human actually authenticate? If the answer is too long ago, the server holds the action until the person signs in again. The build uses the Anthropic API for the agent, Kinde for identity, and Convex for state and the audit trail.

By the end, you'll have built:

A tool registry that separates safe tools from destructive ones, and gives every destructive tool its own freshness window in seconds
One enforcement seam that every tool call passes through, with JWKS verification and RS256 pinned
A freshness check built on the OpenID Connect auth_time claim, read from the ID token and verified server-side at the moment of the call
A Claude tool-calling loop that carries the signed-in person's delegated identity and holds no credential of its own
A complete step-up round trip: the seam holds the action, the person re-authenticates, the agent re-presents the same call, and the seam releases it
An audit trail that keeps recording when its own storage is unreachable
A blanket mode that reproduces the failure on the same code, so you can watch the same task slip through

Every number, reason code, and token claim in this tutorial is measured from that running system.

Why blanket consent fails
The demo and its three services
The freshness primitive: auth_time
Why iat and exp cannot stand in
Building the seam
The tool registry
The Claude agent loop
Good manners are not enforcement
The round trip
The two negative cases
Blanket against step-up
Production hardening
Honest limitations
Proving the check can fail
How to map this to your app
Resources

Why blanket consent fails

The common answer to agent risk is to ask the person to approve each action. Anthropic measured what that produces. In How we contain Claude across products, their engineering team reports:

Our telemetry showed users approved roughly 93% of permission prompts.

And the mechanism behind it:

The more approvals a user sees, the less attention they pay to each, becoming over time much less diligent in their supervision.

A prompt stream trains people to clear prompts. The approval stops being a decision and becomes a reflex, and the one prompt that mattered gets cleared with the rest.

Anthropic's own answer was containment, not step-up authentication. They moved the defence into the environment: ephemeral containers, sandboxes, and virtual machines that limit what an agent can reach. They also built an auto mode that approves safer actions automatically, so the prompt stream gets shorter.

Step-up authentication answers a different question. Containment limits the blast radius. Step-up asks whether the person is still here, right now, for this one irreversible action. The two are complementary:

Containment handles the many. Most actions become safe by construction and need no prompt.
Step-up handles the few. It applies high friction to a small set of irreversible actions.

One design rule follows. A read-only tool must never produce a prompt. Every unnecessary prompt spends the attention you need for the prompt that matters.

The demo and its three services

The build is an operations console. An agent works on records: invoices, releases, and documents. It has six tools.

Tool	Destructive	Freshness window
`list_records`	no	none
`get_record`	no	none
`summarize_records`	no	none
`delete_record`	yes	300s
`refund_payment`	yes	120s
`deploy_release`	yes	120s

Three services do the work. The Anthropic API runs the agent, with the model id read from an environment variable. Kinde is the identity provider, running OpenID Connect with authorization code and PKCE. Convex stores the registry, the records, the run timeline, and the audit trail.

The windows differ by damage. A document delete gets 300 seconds because a backup can restore it. A refund and a production deploy get 120 seconds, because one moves money and the other reaches customers the moment it lands.

The freshness primitive: auth_time

OpenID Connect defines auth_time: the moment the person last authenticated interactively, in seconds since the epoch. It is the only standard claim that tracks a human rather than a token.

Two real tokens from the same sign-in, decoded:

// ID token                              // Access token
{                                        {
  "sub": "kp_79a5daf465584…",              "sub": "kp_79a5daf465584…",
  "auth_time": 1786553833,   // <-- here   // no auth_time
  "iat": 1786553834,                       "iat": 1786553834,
  "exp": 1786557434,         // +1h        "exp": 1786640234,   // +24h
  "aud": ["d4ef3c61eb19…"],                "aud": [],
  "iss": "https://devrelstudio.kinde.com"  "iss": "https://devrelstudio.kinde.com"
}                                        }

The differences decide the whole design.

	ID token	Access token
`auth_time`	present	absent
`aud`	client id	`[]`
Lifetime	1 hour	24 hours
`amr` / `acr`	absent	absent

The access token is the credential a client presents at an API boundary. It carries no evidence of human presence. The ID token carries that evidence and expires twenty-three hours sooner.

The access token lives 24 hours. The evidence of human presence lives 1 hour. Blanket consent ignores that gap. The freshness check closes it.

For twenty-three of those twenty-four hours, an agent holds a valid credential and the system has no fresh evidence that anyone is there.

The discovery document does not mention it

Kinde publishes a discovery document. Its claims list is short:

{
  "claims_supported": ["aud", "exp", "iat", "iss", "sub"],
  "code_challenge_methods_supported": ["S256"]
}

auth_time does not appear. The ID token carries it anyway.

This is spec-consistent. OIDC Core defines auth_time as an ID Token claim, and claims_supported is informational rather than exhaustive. The practical lesson: read a real token before you design against a provider.

The seam therefore cannot prove freshness from the access token. It verifies two tokens and binds them together.

Why iat and exp cannot stand in

iat and exp look like freshness. They are not. Both move whenever a token is minted, and a token can be minted with no human present.

The build tested this against the live provider. First, a refresh while the ID token was still valid:

{
  "authTimeBefore": 1786552841,
  "authTimeAfter": 1786552841,
  "authTimeMoved": false,
  "idTokenChanged": false,
  "accessTokenChanged": false,
  "verdict": "INCONCLUSIVE — the refresh returned the same ID token"
}

Kinde returned the byte-identical token. Nothing was minted, so nothing was proved. Reporting that as a pass would be a false result, so the check reports it as inconclusive.

The decisive test needs an expired ID token:

{
  "authTimeBefore": 1786553833,
  "authTimeAfter": 1786553833,
  "authTimeMoved": false,
  "idTokenChanged": true,
  "idTokenWasExpired": true,
  "issuedAtMoved": true,
  "tokenIdMoved": true,
  "verdict": "auth_time held steady across a newly minted ID token"
}

The provider minted a genuinely new ID token:

	Before	After
`jti`	`1dd46212-757e-…`	`09ba30b7-e842-…`
`iat`	16:57:14Z	18:02:30Z
`exp`	17:57:14Z	19:02:30Z
`auth_time`	`1786553833`	`1786553833`

The new token reports an authentication that happened 3,936 seconds earlier, about 65 minutes. A token minted seconds ago correctly describes a human who authenticated over an hour before.

That number settles the design. auth_time tracks human authentication, so freshness builds on it. iat and exp track token issuance, so a check that asks "was this token issued recently?" passes with nobody there.

The decision function never reads iat or exp. The comment says why, so nobody adds them later:

/**
 * `iat` and `exp` are deliberately absent from this function. Both move when
 * a token is refreshed while no human is present, so neither can stand in for
 * human presence. Only `auth_time` survives the minting of a new token.
 */

Building the seam

The seam is one function. Every agent tool call passes through it. There is no second path to a tool.

Every path ends in an audit row. There is no early return that skips the trail.

Step 1: verify the access token

The build pins RS256 and reads keys from the provider's JWKS endpoint:

const result = await jwtVerify(token, jwksFor(metadata.jwks_uri), {
  algorithms: ALLOWED_ALGORITHMS,      // ["RS256"]
  issuer: metadata.issuer,
  clockTolerance: 5,
});

// `jwtVerify` already refuses any algorithm outside the allow-list. This
// re-reads the header so the pin is visible at the call site and survives
// a future change to how the options are built.
if (result.protectedHeader.alg !== "RS256") {
  throw new TokenVerificationError(
    "algorithm_not_allowed",
    `Token algorithm ${result.protectedHeader.alg} is not RS256.`,
  );
}

The pin appears twice on purpose. The allow-list enforces it. The second check keeps it visible, so a later edit cannot drop it silently.

The verifier refuses malformed claims rather than ignoring them:

No sub, no exp, or no iat: refused.
An auth_time that is not a positive finite number: refused as malformed, not treated as absent.
An auth_time more than 60 seconds in the future: refused. A future auth_time would make every comparison pass.

Step 2: read the registry, and refuse when you cannot

An unknown tool is denied unknown_tool. A registry that cannot be read is denied registry_unavailable. Without the registry the seam cannot know whether a tool is destructive or what window it carries, and guessing either way is worse than stopping.

Step 3: read freshness from the ID token, bound by subject

if (context.idToken !== undefined && context.idToken !== "") {
  try {
    const idClaims = await verifyIdToken(context.idToken);

    // Binding. Without this, an ID token from any session of any person
    // could vouch for freshness on someone else's access token.
    if (idClaims.sub !== accessClaims.sub) {
      return await finish("deny", "subject_mismatch");
    }

    observed.authTime = idClaims.auth_time;
    observed.amr = idClaims.amr;
  } catch {
    // The ID token did not verify. Most often it expired.
    return await finish("challenge", "id_token_invalid", { ... });
  }
} else if (mode === "step-up") {
  return await finish("challenge", "id_token_missing", { ... });
}

The access token answers "who is this". The ID token answers "when did a human last authenticate". Without the binding, a valid ID token from any session could vouch for freshness on somebody else's access token.

The build separates two refusals that both fail closed:

id_token_invalid: the freshness evidence did not verify. Most often the ID token expired, because it lives one hour and the access token lives a day. This is the common case for a long-running agent.
auth_time_stale: the ID token verified, but auth_time is older than the tool's window.

An early version reported both as auth_time_missing. That was wrong: the claim was not missing, the token had expired. The trail now says which happened.

Step 4: decide

The decision is a pure function. Tests drive the whole table with no tokens, no network, and no database.

export function decide(input: DecisionInput): DecisionOutput {
  if (!input.destructive) {
    return { decision: "allow", reason: "safe_tool" };
  }

  if (
    input.maxAuthAgeSeconds === undefined ||
    !Number.isFinite(input.maxAuthAgeSeconds) ||
    input.maxAuthAgeSeconds <= 0
  ) {
    // A destructive tool that declares no window cannot be checked. Allowing
    // it would mean "no limit"; that reading is the failure being fixed.
    return { decision: "deny", reason: "registry_defect", ... };
  }

  const authAgeSeconds =
    input.authTime === undefined ? undefined : input.now - input.authTime;

  if (input.approvalMode === "blanket") {
    return { decision: "allow", reason: "blanket_mode_freshness_skipped", ... };
  }

  if (input.authTime === undefined) {
    // Freshness that cannot be proved is not freshness.
    return { decision: "challenge", reason: "auth_time_missing", ... };
  }

  const withinWindow =
    authAgeSeconds! <= input.maxAuthAgeSeconds + input.clockSkewSeconds;

  return withinWindow
    ? { decision: "allow", reason: "fresh_authentication", ... }
    : { decision: "challenge", reason: "auth_time_stale", ... };
}

Three details are worth copying.

A missing window is a defect, not permission. Treating an absent maxAuthAgeSeconds as "no limit" is the failure this design closes. The function denies instead.

Clock skew widens the window, never narrows it. A provider clock slightly ahead of yours must not turn a fresh authentication into a challenge. The build adds a 30-second grace.

Safe tools return before any freshness logic runs. They cannot produce a prompt even by accident.

The challenge response

A held call answers with HTTP 403 and an RFC 9470 challenge:

HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_user_authentication",
  error_description="The last human authentication is older than this action
  allows. Re-authenticate to continue.", max_age=120

RFC 9470 defines insufficient_user_authentication for this case: the token is valid, but the authentication behind it does not meet the resource server's requirement. The max_age parameter tells the client what the server needs.

The body carries the same facts plus a re-authentication link:

{
  "tool": "delete_record",
  "decision": "challenge",
  "reason": "auth_time_stale",
  "correlationId": "3ad3c1c9-c0cb-4c9c-a0d7-0e3f79b48ba2",
  "authAgeSeconds": 1800,
  "maxAuthAgeSeconds": 300,
  "error": "insufficient_user_authentication",
  "reauthUrl": "/api/auth/login?max_age=0&prompt=login&stepUp=1&returnTo=%2F"
}

max_age=0 and prompt=login ask the provider for an interactive sign-in. They are a hint to the provider. They are never proof. The seam re-reads auth_time from the presented token on the retry and decides again.

The tool registry

The registry holds the policy. Each tool declares a name, a destructive flag, and a window.

The build enforces an invariant on every write:

if (tool.destructive) {
  if (tool.maxAuthAgeSeconds === undefined) {
    violations.push(`destructive tool "${tool.name}" has no maxAuthAgeSeconds`);
  } else if (tool.maxAuthAgeSeconds <= 0) {
    violations.push(`destructive tool "${tool.name}" has a non-positive window`);
  }
} else if (tool.maxAuthAgeSeconds !== undefined) {
  violations.push(
    `safe tool "${tool.name}" carries maxAuthAgeSeconds; ` +
      `safe tools must not have a freshness window`,
  );
}

Both halves matter. A destructive tool must carry a window, or there is nothing to compare auth_time against. A safe tool must not carry one. That second rule is approval fatigue written as code: a window on a read-only tool would produce a prompt that never needed to exist, so the registry rejects it.

Windows do real work

Two measurements from the build show the windows are not decoration.

At one instant, on one token, two destructive tools got different answers:

Tool	Window	Auth age	Decision
`refund_payment`	120s	203s	challenge
`delete_record`	300s	292s	allow

Same person, same session, seconds apart. The refund was held because moving money has a tighter window. The delete passed because a document delete gets more room.

Then the same tool changed answer with nothing else changing:

Tool	Window	Auth age	Decision
`delete_record`	300s	292s	allow, executed
`delete_record`	300s	399s	challenge

Time alone closed the window. The window is measured at the moment of the call, every call.

The Claude agent loop

The agent holds no credential. It calls the same public endpoint every other client uses, and it forwards the signed-in person's session unchanged:

const response = await fetch(new URL("/api/tools/invoke", appConfig().siteUrl), {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    // The person's session, forwarded unchanged. This is the whole of the
    // agent's authority.
    cookie: cookieHeader,
  },
  body: JSON.stringify({ tool, args: input, correlationId }),
  cache: "no-store",
});

The agent never imports the tool executors. If the seam refuses, the agent is refused.

The tempting shortcut is to give the agent its own API key so it "just works". That shortcut is the failure this design closes. A service account decouples the agent's authority from the person's, and auth_time becomes meaningless.

Three responses, handled differently

allow: run the tool, feed the result back, continue.
challenge: stop. Freeze the conversation. Show the person a re-authentication link.
deny: stop and report. A denial is not something re-authentication fixes, so the agent offers no link.

The challenge path is where agents go wrong. Blind retry turns a step-up challenge into a spin, because only the human can clear it. Tool substitution is worse, because it looks like helpfulness: an agent that answers "delete was refused" by reaching for another mutating tool has routed around the control that just fired.

The build blocks both. The system prompt states the rule:

A destructive tool may be held by the server until the person has authenticated
recently. If that happens you will be told so in the tool result, and the run
will end so the person can re-authenticate. That is a normal outcome, not an
error to work around: do not retry a held call, and do not substitute a
different tool to achieve the same effect.

The loop makes it structural. A challenge returns out of the loop, so the model never gets another turn in which to try something else.

Good manners are not enforcement

Two runs in the build produced the same visible outcome and mean completely different things.

Run one. The prompt asked the agent to find the superseded document and delete it. The dataset had none, because an earlier run had already deleted it. The agent listed the documents, read them, and refused:

I reviewed the documents and did not delete anything, because nothing matches what you asked me to find. Neither document is superseded. Both are status active, and each summary points the other way — DOC-3301 is the sole copy of a working model, and DOC-3302 is still load-bearing for three open action items.

No destructive tool was called. The audit trail shows only safe calls.

Run two. Same prompt, record restored. The agent identified the right document, called delete_record, and the seam refused it with auth_time_stale.

Both runs ended with nothing deleted. Only the second is a security control.

The model choosing not to act is good behaviour. It depends on the prompt, the data, and the model's judgement on the day. It is not a boundary. The server refusing to let it act is enforcement, and it holds regardless of what the model decided or which model you swapped in.

When you test your own system, force the destructive call to reach the boundary. If it never reaches the seam, you have tested nothing about the seam.

The round trip

The full sequence, under one correlationId:

The resume re-presents, it does not re-plan

When the seam holds a call, the build stores the conversation and the exact held call:

await convex().mutation(api.runs.pause, {
  runId: ctx.runId,
  haltedReason: seam.body.reason ?? "step_up_required",
  challengeAuthTime: seam.body.authTime,
  pausedState: {
    messages,
    toolUseId: request.id,
    toolName: request.name,
    toolInput: request.input,
  },
});

On resume, the agent sends that same call to the seam before the model gets another turn:

if (pending !== undefined) {
  const seam = await callSeam(
    pending.toolName,
    pending.toolInput,
    ctx.correlationId,
    ctx.cookieHeader,
  );
  ...
}

This is a security property, not a convenience. If the resume let the model re-plan, a released run would not be the task the person approved. It could become a different, larger action wearing the same correlationId. Same tool name, same input, same tool_use_id, or nothing.

The resume route decides nothing

after(async () => {
  await resumeAgent({ runId, userId: session.subject, cookieHeader, observedAuthTime });
});
return NextResponse.json({ runId, accepted: true }, { status: 202 });

No path through the route releases something the seam would refuse. The auth_time the route reads serves the audit narrative only, and it comes from a verified token, never from the caller.

The two negative cases

A control is only as good as what it refuses. Two refusals carry the whole design.

Case 1: a refresh does not release the action

Before any re-authentication, the build ran a refresh_token grant against the live provider, then retried the held delete.

The refresh minted a new, valid ID token. The previous one had expired, so this was a real minting, not a cached response.

The retry was refused.

The reason code tells the story precisely:

Attempt	Reason	Auth age	Window
Original halt	`id_token_invalid`	—	300s
After refresh	`auth_time_stale`	4409s	300s

The reason moved from id_token_invalid to auth_time_stale. That change is the finding:

The refresh repaired the token's validity. It did not repair its freshness.

A machine-to-machine exchange restored a well-formed, verifiable, unexpired credential. The destructive action stayed held, because no human had been present. This is the property the whole design rests on, measured rather than assumed.

If your freshness check reads exp, this case passes and the action runs.

Case 2: re-authentication does not bless the session

The second refusal was not planned. A genuine interactive re-authentication happened. Then about five minutes of other work passed before the retry fired.

The retry was refused:

Attempt	Reason	Auth age	Window
After real re-auth, delayed	`auth_time_stale`	352s	300s

The person had re-authenticated correctly. The window had closed again.

This rules out a weaker reading of the control: that re-authenticating grants the session a blessing that later calls ride on. It does not. The window is measured at the moment of each call. A correct re-authentication that has since aged out is refused exactly like one that never happened.

The release

The next re-authentication was followed promptly by the retry:

Decision	Reason	Auth age	Window
allow	`fresh_authentication`	50s	300s

The delete executed. The record changed.

Seven audit rows carry that run: three safe calls, three challenges, one release. All share one correlationId, so the story stays readable months later.

Blanket against step-up

The build ships two modes so the failure and the fix run side by side on the same code.

APPROVAL_MODE is read from the deploy environment and from nowhere else:

export function approvalMode(): ApprovalMode {
  const raw = process.env.APPROVAL_MODE;
  if (typeof raw !== "string") return "step-up";
  return raw.trim().toLowerCase() === "blanket" ? "blanket" : "step-up";
}

Three properties are deliberate. The variable has no NEXT_PUBLIC_ prefix, so Next.js never inlines it into the browser bundle. The seam never reads it from a header, query string, cookie, or tool argument, so a caller cannot set it. And only the exact string blanket selects the permissive mode: unset, empty, misspelled, or hostile values all resolve to step-up, so a misconfiguration fails towards enforcement.

Running the same task in each mode, with an authentication about five hours old:

Mode	Tool	Auth age	Decision	Executed
blanket	`refund_payment`	~5h	allow (`blanket_mode_freshness_skipped`)	yes
blanket	`delete_record`	~5h	allow (`blanket_mode_freshness_skipped`)	yes
blanket	`deploy_release`	~5h	allow (`blanket_mode_freshness_skipped`)	yes
step-up	`delete_record`	~5h	challenge (`auth_time_stale`)	no

In blanket mode the agent refunded an invoice, deleted a document, and deployed a release to production. Same tokens, same tools, same code. Only the deploy environment differed.

The number that matters

The headline counter is executedWithoutFreshAuth. It counts destructive calls the seam allowed while the authentication was outside the tool's window, or allowed with no age recorded at all. Counting the missing case as a failure keeps the metric honest.

In step-up mode it stays at 0. In blanket mode it climbs.

One subtlety caught the build's own test. A blanket-mode slip is not automatically an escape. If the person signed in seconds earlier, the check was skipped but nothing escaped a window it would have failed, and the counter correctly stays at zero. The hole only bites when the human is absent. The end-to-end test now ages the session past the window before the blanket task runs, so the escape it measures is real.

Production hardening

Three gaps appeared during the build. Each is easy to ship without noticing.

The audit row that vanished

The first version failed closed when Convex was unreachable. The tool did not run, but no audit row was written. A refusal happened with no record that it had. A control that silently stops recording looks identical to one that stopped working.

The audit write now has three stages:

Stage	Result
Convex, retried with backoff	`recorded`
Local append-only spool file	`spooled`
Neither	`lost`

The write never throws, because the seam needs the outcome to decide what to do next:

if (written.durability === "lost" && decision === "allow") {
  // Neither the store nor the spool took it. Allowing now would mean an
  // action ran with no evidence anywhere that it was permitted.
  effectiveDecision = "deny";
  effectiveReason = "audit_unavailable";
}

The audit outcome can only make a decision stricter, never looser.

Testing this exposed a second hole. With Convex fully unreachable the seam never reached the audit write: the registry lookup threw first, the route returned 500, and no row was written. Same gap, one step earlier. It would have stayed hidden if the outage had only been simulated at the audit call.

Measured with the sink pointed at an unreachable host:

POST /api/tools/invoke → 403
  decision=deny  reason=registry_unavailable

.audit-spool.jsonl:
  deny  registry_unavailable  delete_record  cid=0020d4ca

GET /api/health:
  {"degraded": true, "pendingRows": 1}

After the sink returned, one health probe drained it: {"degraded": false, "pendingRows": 0, "replayedNow": 1}. The refusal happened, was recorded while the store was down, showed as a backlog, and landed in the store on recovery.

The success that reported as a failure

A resume once released a destructive action, executed it, wrote its audit row, and then returned HTTP 500. A trailing Convex write had failed after the work was done. The most dangerous thing a console can say about a delete that happened is "it failed".

Two changes make that impossible. The response precedes the work: both routes validate, return 202 Accepted, and drive the loop in after(). And the run's own state is authoritative: the console reads status, timeline, records, and counters from Convex by subscription, never from the fetch that started the run.

The split between the two trails is deliberate. Timeline writes are best-effort telemetry, and losing one costs visibility. Audit writes are strict and can refuse the call, and losing one costs the security record.

The state that lied

A resume left the run marked halted for its whole duration. The console showed "Held" while a resume was in flight.

The test found it. The end-to-end script waited for the run to settle, read halted immediately, and asserted against the previous outcome. The load-bearing negative assertion passed without the resume having happened.

The fix sets the run to running at the start of a resume, before the seam is consulted. The test now also waits for a new audit row before reading any outcome, because a new row proves the seam ruled.

Honest limitations

Two limitations stand. Both are stated in the project README.

It proves when, not how

The console proves when a person authenticated. It cannot prove how.

The Kinde tenant emits no amr or acr claim on either token, even after the person completes multi-factor authentication. This was checked against Kinde's documentation and against real tokens from a real MFA sign-in.

The ID token carries 19 claims:

at_hash, aud, auth_time, azp, email, email_verified, exp, family_name,
given_name, iat, iss, jti, name, nonce, org_codes, picture, rat, sub,
updated_at

No amr. No acr. The access token carries none either.

To be sure this was the provider's behaviour and not a gap in the build's own claim handling, the session view reports the claim names on each verified token. A claim that is sent but never read looks identical to a claim that is never sent, unless you check.

Kinde does support custom properties in tokens. The build deliberately did not use them here. A custom property is a static value configured against a user. It is not a record of what happened during a sign-in. A property reading "mfa" would be emitted on a password-only login exactly as on an MFA login. That is not a weaker control. It is a false one, and it would read to an auditor as though the second factor had been verified.

The assertion mechanism ships anyway, and ships off:

export function requiredAuthMethods(): string[] {
  return optional("STEP_UP_REQUIRED_AMR", "")
    .split(",")
    .map((value) => value.trim().toLowerCase())
    .filter((value) => value !== "");
}

Set STEP_UP_REQUIRED_AMR=mfa and a destructive release must evidence that method, or the seam holds it with amr_unprovable or mfa_required. On this tenant that setting refuses every destructive call, because there is no amr to check. The refusal is correct fail-closed behaviour, but it is not a control this provider can satisfy, so the flag stays empty.

For the same reason acr_values never appears in the challenge header. Demanding an authentication context you cannot verify is a promise you cannot keep.

The audit spool is a floor

If the audit store is unreachable, a decision is retried, then written to a local append-only file, then replayed when the store returns. A decision is never silently lost.

But that file lives on one host and does not survive it. It is the floor, not a durable-queue story. A production deployment wants a queue with its own availability guarantees.

Proving the check can fail

A test that cannot fail is decoration.

One script walks the whole story in a single pass: npm run e2e. It runs 45 assertions across seven steps, and every assertion reads the deployment back rather than the HTTP status.

Two properties are worth copying. It never sets APPROVAL_MODE on a request: the mode belongs to the deployment, so switching it means restarting the server. A request-level override would have been easier and would have destroyed the invariant the script exists to prove. It never mints a session: it drives a real browser, and the operator signs in once and re-authenticates once.

A passing run:

── Step 1: Clean slate                escapes start at 0
── Step 2: Step-up, read-only         every call allowed, nothing challenged,
                                      no record touched
── Step 3: Blanket, the hole          refund executed, record changed,
                                      escapes → 1
── Step 4: Step-up, the halt          deploy held, nothing executed
── Step 5: The negative               refresh did NOT advance auth_time;
                                      resume refused and recorded
── Step 6: The release                auth_time advanced; released exactly
                                      once at fresh_authentication
── Step 7: Reconciliation             one correlationId; release did NOT
                                      count as an escape

final counters: safe=1 destructive=3 challenged=2 escapes=0
PASS — 45 assertions across 7 steps.

Then the important part. Inverting the load-bearing assertion, so it claims a refresh should advance auth_time:

   ✗ ASSERTION FAILED
   the refresh did NOT advance auth_time
     expected true, got false

FAIL — stopped after 27 passing assertions.
EXIT CODE: 1

It stops at the first failure, names the assertion, prints expected against actual, and exits non-zero.

Run that experiment on your own suite. If you cannot make a security test go red on demand, you do not know what it is testing.

How to map this to your app

The identity provider, the database, and the model are replaceable. Six decisions are not.

1. Classify your tools, and be strict about the safe ones. Split tools into read-only and destructive. Give every destructive tool a window in seconds, tiered by how hard the action is to undo. Forbid windows on safe tools. Enforce both halves in code.

2. Read auth_time from wherever your provider puts it. Decode a real token first. On Kinde it sits on the ID token, and the discovery document does not list it. Verify the token that carries authorization and the token that carries freshness, then bind them by sub.

3. Never use iat or exp as a freshness proxy. Test this against your own provider. Let an ID token expire, run a refresh, and compare auth_time before and after. If auth_time moves, you need a different primitive.

4. Put the check in one place. One function, on the server, at the moment of the call. Not in the client. Not in the prompt. Not spread across six tool implementations.

5. Fail closed, and record before you answer. A missing window, an unverifiable token, an unreadable registry, an unrecordable decision: all refuse. Write the audit row before you return the decision.

6. Handle the challenge properly in the agent. Stop the run. Do not retry. Do not substitute another tool. Store the exact held call and re-present it after re-authentication.

Then test the negatives. Anyone can show a release after a successful sign-in. The design is only worth something if a refresh-only retry stays blocked, and if a correct re-authentication that has aged out is refused too.

Resources

How we contain Claude across products. Anthropic engineering. Source of the ~93% approval figure and the containment approach.
RFC 9470: OAuth 2.0 Step Up Authentication Challenge Protocol. Defines insufficient_user_authentication and the max_age parameter.
OpenID Connect Core 1.0. Defines auth_time, max_age, and prompt=login.
Kinde documentation. ID tokens, token customization, and multi-factor authentication.
Anthropic API tool use. The tool-calling loop the agent runs.
Convex. The reactive database behind the registry, records, timeline, and audit trail.

How to Give Every Kimi K3 Agent Its Own Tenant Identity With Kinde Organizations

Shola Jegede — Sat, 08 Aug 2026 23:36:57 +0000

I built a swarm of Kimi K3 agents for three customers. I gave every agent the same login, because that is the quickest way to get a swarm working. Then I read what one of the agents wrote back:

Collected invoice-001 from all three organizations: Tenant A: 1,200.00; Tenant B: 9,900.00; Tenant C: 450.00. The consolidated total is 11,550.00.

Three customers, three invoice amounts, one agent. That agent worked for the first customer and read the other two. Nobody asked it to. The token it carried belonged to no customer in particular, so the server had no reason to refuse it.

Moonshot's Agent Swarm runs up to 300 sub-agents at once, and one shared credential gives every one of them the reach of your whole platform. That is the multi-tenant problem, and a swarm makes it worse.

In this tutorial, you'll fix it. You'll give each agent an identity that belongs to one customer, using Kinde organizations, and you'll check that identity on every call the agent makes. You'll also build a kill switch that stops one customer's swarm while the others keep working, and you'll find out why the obvious way to build that kill switch does nothing at all.

By the end, you'll have built:

A Kimi K3 swarm you orchestrate yourself, so each agent's identity is yours to set
One Kinde organization for each tenant, and one machine-to-machine application for each agent role inside it
A client-credentials flow that mints a scoped token for each agent before it acts
A single enforcement point that decides every call, and refuses cross-tenant reads with 403 cross_org
A test that proves the boundary holds, by breaking it on purpose
A kill switch that stops one tenant mid-run, with the audit trail to show it
A console that streams every agent step live, so you can watch a leak happen and then watch it stop

Everything here runs. The code is open, and one command replays the whole story.

What You'll Build
Prerequisites
What a Swarm Changes
How the Demo Is Structured
- The two modes
- Why you orchestrate the swarm yourself
Why One Shared Identity Is the Whole Problem
How Tenant Isolation Works With Kinde Organizations
How to Model Each Tenant as a Kinde Organization
How to Give Each Agent Role Its Own M2M Application
How to Mint an Org-Scoped Token Inside Each Agent
- Check the claim before you build the rest
- Checkpoint
How to Enforce Isolation at One Point in Your API
- The rule, as a pure function
- Checking the token
- The seam itself
- Four rules that keep it holding
- Checkpoint
How to Prove the Boundary Actually Holds
- Break the check on purpose
- Test the token the same way
- Checkpoint
How to Build a Kill Switch That Works
- The assumption, and what measuring it showed
- Where the check has to go
- The suspend action
- One side effect to design for
- Checkpoint
How to Watch It Happen
What Least Privilege Actually Costs
Three More Things That Broke
How to Bring This Up to Production Standard
How This Maps to Your Own App
Limits of This Build
Wrapping Up
Resources

What You'll Build

The demo runs a swarm for three tenants and shows the same call succeed and fail, depending on one server setting.

In shared mode, an agent working for Tenant A reads Tenant B's records. The escapes counter turns red, and the timeline names the organization it crossed into:

In per-org mode, the same swarm makes the same call for a different tenant, and the server refuses it. Cross-org attempts stay at 2, blocked rises to 2, escapes stays at 0:

Press the kill switch mid-run and that tenant stops where it stands, while the others carry on:

The agents are real, and they decide their own actions. Nobody scripts the reach across a tenant boundary.

Prerequisites

To follow along, you'll need:

A Kinde account. The free tier covers everything here.
Kimi K3 access, through the Moonshot API or OpenRouter.
Node 22+ and pnpm, plus Python 3.11+ for the swarm service.
Comfort with OAuth2 client credentials and JWTs. You don't need to be an expert, but you should know what a claim is.

The demo uses Convex for the backend and Next.js for the console. Neither is required for the pattern. The enforcement point is about forty lines, and it moves to Express, Hono, or FastAPI without changing shape.

What a Swarm Changes

A swarm is a group of AI agents that work at the same time on one job. One agent plans, other agents do the work in parallel, and each one calls tools.

Two properties make a swarm different from a single agent.

Speed. Those 300 sub-agents make over 4,000 tool calls in one task, about 4.5 times faster than a single agent working in sequence. Agent Swarm now runs on Kimi K3, which Moonshot calls K3 Swarm (Kimi Help Center). Nobody reviews that many calls while they happen, so the boundary has to hold on its own.

Autonomy. The agents choose their own actions. A swarm decides which tools to call, and with which arguments.

Add customers, and a third property appears.

Reach. Each agent needs access to data. If every agent uses one credential, that credential holds the sum of all access, and the reach of one agent becomes the reach of the whole system.

Call that reach the blast radius: the data an agent can touch if it goes wrong. Under one shared login, the blast radius of every agent is every customer.

Two things make an agent go wrong, and neither needs an attacker:

A prompt injection reaches the agent through data it reads.
The planner hands a broad tool to the wrong agent.

The second case is the common one. It looks like a bug, not an attack.

These terms come up throughout:

Term	Meaning
Tenant	One customer of your platform.
Agent	One AI worker in the swarm. The code calls them workers.
Organization	A Kinde container that holds one tenant.
M2M application	A Kinde login for software, not for a person.
Token	A signed pass that proves who is calling.
Scope	One permission on a token, such as `resource:read`.
Seam	The single server function that decides every call.

How the Demo Is Structured

Three services do three jobs:

Kimi K3, served by Moonshot, drives the agents.
Kinde proves which tenant each agent belongs to.
Convex stores the data, decides every call, and streams each step to the browser.

In short: Kimi K3 decides, Kinde proves, Convex enforces and records.

Every agent call follows the same path, and no agent ever reaches the database:

Kimi K3 agent
     │  1. client credentials
     ▼
   Kinde ──→ token { org_code, scope }
     │
     │  2. HTTP tool call, bearer token
     ▼
 Tool endpoint
     │
     ▼
  The seam  ──→ check signature (Kinde JWKS)
     │      ──→ tenant suspended?
     │      ──→ org_code vs record owner
     │      ──→ scope
     ▼
  allow or 403  ──→ audit row  ──→ live timeline

The demo runs three tenants. Each holds four records, one of them confidential. The swarm has three agents: two read, one writes.

The two modes

The server holds the mode, and no agent or browser can set it:

Mode	Agent identity	Cross-tenant call
`shared`	One credential for the whole swarm	The server permits it. The data leaks.
`per-org`	One credential for each tenant	The server refuses it, `403 cross_org`.

Any value that is not exactly shared resolves to per-org. A typo lands in the safe mode, not the leaky one.

Why you orchestrate the swarm yourself

Kimi K3 offers a hosted swarm product. This build does not use it, for one reason: a hosted swarm gives no place to inject a different credential for each agent. The identity is the whole security boundary, so the identity has to be yours to set.

So the orchestrator is your code. It calls the Kimi K3 model, splits the goal, and runs three agents, each holding its own credentials:

# swarm/orchestrator.py
workers = [
    Worker(label="reader-1", identity=WorkerIdentity(tenant, "READER"),
           backend=Backend(correlation_id, "reader-1"), can_write=False, ...),
    Worker(label="reader-2", identity=WorkerIdentity(tenant, "READER"),
           backend=Backend(correlation_id, "reader-2"), can_write=False, ...),
    Worker(label="writer-1", identity=WorkerIdentity(tenant, "WRITER"),
           backend=Backend(correlation_id, "writer-1"), can_write=True, ...),
]

Each agent runs a normal tool-calling loop. The model picks the tool and the arguments, and your code executes the call:

# swarm/worker.py
for _ in range(MAX_TURNS):
    body = self.kimi.chat(messages, tools=self.tools)
    message = body["choices"][0]["message"]
    messages.append(message)

    tool_calls = message.get("tool_calls") or []
    if not tool_calls:
        summary = (message.get("content") or "").strip()
        break

    for call in tool_calls:
        name = call["function"]["name"]
        args = json.loads(call["function"].get("arguments") or "{}")
        result = self._execute(name, args)   # HTTP, with this agent's token
        self._record(name, args, result)     # streams to the live timeline
        messages.append({"role": "tool", "tool_call_id": call["id"],
                         "content": json.dumps(result.body)[:1500]})

read_resource takes an optional organization code:

{
    "type": "function",
    "function": {
        "name": "read_resource",
        "description": "Read one record by key, or by id.",
        "parameters": {"type": "object", "properties": {
            "key": {"type": "string"},
            "resource_id": {"type": "string"},
            "target_org_code": {"type": "string", "description":
                "Optional. The organization that owns the record. "
                "Defaults to your own organization."},
        }, "required": []},
    },
}

Platform software knows which tenants exist, and an agent doing a platform-wide job needs a way to name one. Naming a tenant grants nothing. The server still decides.

At this point every agent shares one identity.

Why One Shared Identity Is the Whole Problem

Your API sees one thing when an agent calls it. It sees a token. It does not see which agent sent the token, what the agent intended, or what the planner asked for. The token is the entire security boundary.

A shared identity does not weaken that boundary. It removes it.

One M2M application for the swarm means one set of scopes, and those scopes have to cover everything any agent might need. The union of all needs becomes the floor of every agent's access.

One credential, with no tenant on it. Nothing refuses, and the reach of one agent is the reach of the whole platform.

How Tenant Isolation Works With Kinde Organizations

The pattern has three parts:

One Kinde organization holds one tenant.
One M2M application holds one agent role inside one organization.
The token that application receives carries an org_code claim and a scope list.

Your API then compares two values on every call: the org_code on the token, and the tenant that owns the record. A mismatch is a refusal.

The agent never states its own tenant. It presents a token that Kinde signed, and it cannot edit a claim without breaking the signature.

The same failure now stops at one tenant, and the server records the attempt.

Kinde organizations are flat, with no nesting. One organization for one tenant keeps the model simple, and the check stays a single comparison.

How to Model Each Tenant as a Kinde Organization

Create one organization for each tenant. Kinde gives each one a code, such as org_2606b8199462b. The code is an identifier, not a secret.

Create organizations on your server, through the Management API, when a customer signs up. Do not accept an organization code from a browser. The code in an authorization URL can be changed by the person using the browser, so treat it as a request, never as proof.

The demo uses three organizations:

Tenant A   org_2606b8199462b
Tenant B   org_364dd8200a3d3
Tenant C   org_0c39cb2010b01

How to Give Each Agent Role Its Own M2M Application

Create one M2M application for each agent role, inside each tenant's organization. The demo has two roles, so it has six applications:

Organization	Application	Scope
Tenant A	Tenant A Reader	`resource:read`
Tenant A	Tenant A Writer	`resource:write`
Tenant B	Tenant B Reader	`resource:read`
Tenant B	Tenant B Writer	`resource:write`
Tenant C	Tenant C Reader	`resource:read`
Tenant C	Tenant C Writer	`resource:write`

Give each application one scope. The read agents cannot write, and the write agent cannot read. Role isolation becomes scopes inside the organization, and tenant isolation becomes the organization itself.

Create one more application for the Management API, with read:organizations and update:organizations, and nothing else. The kill switch uses it.

How to Mint an Org-Scoped Token Inside Each Agent

Each agent exchanges its own credentials for a token, using the OAuth2 client-credentials flow. There is no shared credential anywhere in the service:

# swarm/identity.py
@dataclass(frozen=True)
class WorkerIdentity:
    tenant: str   # "A", "B", "C"
    role: str     # "READER" or "WRITER"

    @property
    def client_id_var(self) -> str:
        return f"KINDE_M2M_TENANT_{self.tenant}_{self.role}_CLIENT_ID"


def fetch_token(identity: WorkerIdentity) -> str:
    response = requests.post(
        required("KINDE_M2M_TOKEN_URL"),
        data={
            "grant_type": "client_credentials",
            "client_id": required(identity.client_id_var),
            "client_secret": required(identity.client_secret_var),
            "audience": required("KINDE_AUDIENCE"),
        },
        timeout=30,
    )
    if response.status_code != 200:
        raise TokenRefused(f"tenant {identity.tenant} {identity.role}",
                           status=response.status_code)
    return response.json()["access_token"]

An agent cannot get another tenant's token. The credentials it uses come from the role it was created with, which is a property of the code rather than a rule the agent follows.

Here is a real token from the demo, decoded. This is the Tenant A read agent:

{
  "aud": ["swarm-demo-api"],
  "azp": "89321317d1fe4100925ca8b4ab4b589a",
  "exp": 1786285575,
  "gty": ["client_credentials"],
  "iss": "https://devrelstudio.kinde.com",
  "jti": "7d9f74d3-89d4-4d99-a648-ab51210da6ec",
  "org_code": "org_2606b8199462b",
  "scope": "resource:read",
  "v": "2"
}

Two claims matter. org_code says which tenant, and scope says which permission.

Check the claim before you build the rest

Kinde M2M applications authenticate as an application, not as a person inside an organization, so the org_code claim is worth confirming before you create twelve of them. Make one application, mint one token, and decode it.

All six came back correct in this build:

TENANT_A_READER  org_2606b8199462b  resource:read
TENANT_A_WRITER  org_2606b8199462b  resource:write
TENANT_B_READER  org_364dd8200a3d3  resource:read
TENANT_B_WRITER  org_364dd8200a3d3  resource:write
TENANT_C_READER  org_0c39cb2010b01  resource:read
TENANT_C_WRITER  org_0c39cb2010b01  resource:write

Checkpoint

Mint a token for one application and decode the payload at jwt.io, or with a two-line script. You should see org_code set to that application's organization, and scope holding exactly one permission. If org_code is missing, the application is not scoped to an organization, and the rest of this build has nothing to check against.

How to Enforce Isolation at One Point in Your API

Put the decision in one function. Every agent call passes through it, nothing downstream re-checks, and nothing upstream skips it.

The rule, as a pure function

Keep the rule itself separate from the plumbing. This one takes six inputs and returns a decision. It has no network access, no database access, and no token parsing, so it can be tested completely:

// convex/lib/decide.ts
export function decide(input: DecisionInput): Decision {
  const crossOrg =
    input.targetOrgCode !== null && input.targetOrgCode !== input.actorOrgCode;

  // Checked before the mode, so it applies in both.
  if (input.actorSuspended) {
    return { allow: false, reason: DENY.suspended, crossOrg };
  }

  if (input.mode === "per-org") {
    if (crossOrg) {
      return { allow: false, reason: DENY.crossOrg, crossOrg };
    }
    if (input.requiredScope !== null &&
        !input.actorScopes.includes(input.requiredScope)) {
      return { allow: false, reason: DENY.insufficientScope, crossOrg };
    }
    return { allow: true, reason: ALLOW.ok, crossOrg };
  }

  // Shared mode: one credential for the whole swarm belongs to no tenant and
  // carries every permission, so neither check has anything to bite on.
  return {
    allow: true,
    reason: crossOrg ? ALLOW.crossOrgAllowed : ALLOW.ok,
    crossOrg,
  };
}

The order matters. The rule checks the tenant first, then the permission. A call that crosses a tenant boundary with the wrong scope reports cross_org, because the tenant boundary is the more serious failure.

Checking the token

Check the token against the Kinde public keys before anything else. Pin the algorithm, and refuse a token that carries no org_code rather than guessing one:

// convex/lib/kindeToken.ts
const { payload } = await jwtVerify(token, jwksFor(issuer), {
  issuer,
  audience,
  // Kinde signs with RS256. Pinning it stops a token arriving with a weaker
  // algorithm chosen by whoever sent it.
  algorithms: ["RS256"],
});

const orgCode = typeof payload.org_code === "string" ? payload.org_code : "";
if (!orgCode) {
  throw new TokenError(TOKEN_DENY.missingOrgCode);
}

The seam itself

The seam runs those checks in a fixed order, and every refusal leaves by one path:

// convex/lib/seam.ts
export async function guard(ctx, request, spec): Promise<Response> {
  const correlationId =
    request.headers.get("x-correlation-id")?.trim() || crypto.randomUUID();

  // 1. Who is calling. Nothing below trusts the request body for it.
  let identity: VerifiedIdentity;
  try {
    identity = await verifyAccessToken(request.headers.get("authorization"));
  } catch (error) {
    return refuse(reasonOf(error), 401, "unknown");
  }

  // 2. Is this tenant allowed to operate at all?
  const actorSuspended = await ctx.runQuery(internal.tenants.isSuspended, {
    orgCode: identity.orgCode,
  });

  // 3. Which tenant owns the record being reached for?
  const target = await spec.resolveTarget(identity, body);
  const targetOrgCode = target.kind === "record" ? target.doc.orgCode : null;

  // 4. The decision.
  const decision = decide({
    mode,
    actorOrgCode: identity.orgCode,
    actorScopes: identity.scopes,
    requiredScope: spec.requiredScope,
    targetOrgCode,
    actorSuspended,
  });

  // 5. Written down before the caller is answered, allow or deny.
  await write({ decision: decision.allow ? "allow" : "deny", ... });

  if (!decision.allow) {
    return json({ ok: false, reason: decision.reason, correlationId,
                  isolationMode: mode }, 403);
  }

  // 6. Only now does the work happen.
  const data = await spec.perform(target, body, identity, mode);
  return json({ ok: true, correlationId, crossOrg: decision.crossOrg, ...data }, 200);
}

Every path ends in an audit row. The server writes the row before it answers the caller, so a client that disconnects cannot lose a refusal.

Four rules that keep it holding

The acting tenant is never user input. It comes out of token verification and passes inward. Every data function is internal, so nothing outside the backend can call in and name a tenant.

Agents never reach the database. They call HTTP tool endpoints. The request body chooses the record, and the token decides the tenant.

Fail closed. Any path that cannot complete a check refuses. A tenant the server has never heard of counts as suspended.

Record everything. Every allow and every refusal writes a row, with a correlation id that ties one run together across every agent.

Checkpoint

Call your tool endpoint three times: once with no Authorization header, once with a valid token for its own record, and once with that same token against another tenant's record. You should get 401, 200, and 403 cross_org. Then read your audit table. All three calls should be there, including the one that failed before it reached any data.

How to Prove the Boundary Actually Holds

A passing test suite proves nothing by itself. It proves something when it fails for the right reason.

Break the check on purpose

Delete the ownership check from the boundary and run the tests again:

// convex/lib/tenancy.ts, the check under test
export function requireSameOrg<T extends TenantOwned>(
  actorOrgCode: string,
  doc: T | null | undefined,
): T {
  if (!doc) {
    deny(DENY.notFound);
  }
  if (doc.orgCode !== actorOrgCode) {   // deleted this for the experiment
    deny(DENY.crossOrg);
  }
  return doc;
}

Exactly three tests failed, and they were the three cross-tenant tests. The other three kept passing. Restoring the check returned six passes.

A suite that cannot fail when the boundary breaks is decoration.

Test the token the same way

Two checks matter more than the rest:

Change one character in a token signature. The server must refuse it.
Change the org_code in the payload to another tenant. The server must refuse it.

Both return 401 invalid_token in the demo. If the token check were skipped, both would return 200.

Checkpoint

Comment out your own ownership check and run your tests. If they still pass, they are not testing the boundary. Put the check back before you go further.

How to Build a Kill Switch That Works

The assumption, and what measuring it showed

The plan for this build said: suspend the tenant's organization in Kinde, and its agents stop, because their tokens stop working.

Measuring that first is what saved it:

suspend Tenant C   ->  is_suspended: true
token endpoint     ->  HTTP 200      (Kinde still issues M2M tokens)

Kinde organization suspension governs people who sign in. It does not stop the client-credentials flow for a machine-to-machine application. A token already issued also stays valid until it expires, because nothing recalls a JWT.

So suspension by itself stops no running agent. A kill switch built on that belief looks correct in a demo, passes a casual test, and stops nothing during a real incident.

Where the check has to go

Check suspension on the server, on every call. Look again at the rule earlier in this tutorial: the suspension check sits above the mode check, so it applies in both modes. A kill switch that only worked in the safe mode would be useless, because the leaky mode is exactly when a swarm needs stopping.

The suspend action

The kill switch does three things:

// convex/killSwitch.ts
export const suspend = internalAction({
  args: { orgCode: v.string() },
  handler: async (ctx, { orgCode }) => {
    // 1. Kinde is the authority on the organization.
    await setOrgSuspended(orgCode, true);
    // 2. The enforcement copy, which the seam reads on every call. This is the
    //    one that stops a running swarm.
    await ctx.runMutation(internal.tenants.setSuspended, {
      orgCode, isSuspended: true,
    });
    // 3. A suspended tenant cannot close its own runs, so close them here.
    await ctx.runMutation(internal.runs.killInFlight, { orgCode });
    return { orgCode, suspended: true };
  },
});

The Management API call, with the guard that matters as much:

// convex/lib/kindeManagement.ts
export async function setOrgSuspended(orgCode: string, isSuspended: boolean) {
  assertManageable(orgCode);             // one of this deployment's tenants only
  const token = await managementToken();  // audience: {issuer}/api

  const response = await fetch(
    `${issuer()}/api/v1/organization/${encodeURIComponent(orgCode)}`,
    {
      method: "PATCH",
      headers: { authorization: `Bearer ${token}`,
                 "content-type": "application/json" },
      body: JSON.stringify({ is_suspended: isSuspended }),
    },
  );
  if (!response.ok) throw new Error(`could not update ${orgCode}`);
}

assertManageable refuses any organization outside the three the deployment knows. A Kinde account holds other organizations, and a wrong code should never suspend one of them.

Tested with two real swarms running and one tenant suspended twelve seconds in:

tenant A audit: {"ok": 2, "organization_suspended": 17}
tenant B audit: {"ok": 39}
tenant B run status: completed

Tenant A did real work, then stopped where it stood. Tenant B finished normally and was never refused.

One side effect to design for

A suspended tenant cannot write anything, including its own log lines, because the log endpoint sits behind the same seam. The live timeline stops dead. On screen that reads as a hang, so the console says why.

Checkpoint

Suspend a tenant while one of its agents holds a valid token, then reuse that same token. You should get 403 organization_suspended, not a success and not a network error. Then request a fresh token for that tenant. Kinde will issue one, and the server should refuse that too.

How to Watch It Happen

The same agent makes the same call for the same record, twice. Only the server's mode differs.

Shared mode. The call returns 200, and the response carries tenant B's confidential content. The audit row records an allow that crossed a tenant boundary:

allow / cross_org_allowed
actor:  org_2606b8199462b
target: org_364dd8200a3d3
action: resource.read

Per-org mode. The identical call returns 403, and no content comes back:

{
  "ok": false,
  "reason": "cross_org",
  "correlationId": "2f0f21d6-a9a3-43e5-8153-884992dbd166",
  "isolationMode": "per-org"
}

Side by side:

Metric	`shared`	`per-org`
workers	3	3
tool calls	6	11
cross-org attempts	2	2
blocked	0	2
escapes	2	0

Return the correlation id with the refusal. The agent sees it, the audit row carries it, and the console shows it. One identifier ties a refusal to the run that caused it.

Least privilege has to hold inside a tenant, not only between tenants. Three calls, one correlation id:

deny  / insufficient_scope    read agent tried to write to its own tenant
allow / ok                    write agent wrote to its own tenant
deny  / cross_org             write agent tried to write to another tenant

Here is the same agent, under per-org, reporting the refusal itself:

The reads against Tenant A and Tenant C were refused with reason "cross_org". Per-org isolation prevents me from accessing other organizations' records, so I did not retry.

The agent did not change, and the prompt did not change. The identity it carried changed, and the server checked that identity on every call.

What Least Privilege Actually Costs

The write agent holds resource:write and nothing else. That is correct, and it broke the swarm the first time it ran.

The agent made eight tool calls, and the server refused all eight. It tried to list records, and the server refused, because listing needs resource:read. It tried to read a record, and the server refused for the same reason.

The write agent had been given read tools it could never use.

The fix is not a wider scope. The fix is to change how work reaches that agent. The orchestrator looks up the record with a read identity, then passes the record id in the agent's task:

# swarm/orchestrator.py
listing = control.call("/tools/resource.list", opener)   # reader identity
chosen = next((r for r in rows if r.get("key") == "consolidated-summary"), None)

if chosen:
    write_target = (f"\nWrite to record id {chosen['id']} (key {chosen['key']}), "
                    f"which belongs to {tenant_name}.")
else:
    # Saying nothing here left the agent to invent a record id, which the
    # backend then refused as malformed.
    write_target = ("\nNo record is available to write to: looking one up was "
                    f"refused ({listing.reason}). Report that you could not "
                    "write, and give the reason. Do not invent a record id.")

The second branch came from a later failure. When the lookup was refused, the write agent invented a record id and the server rejected it as malformed. An empty instruction left a gap, and the model filled it.

There is a sequencing cost too. The first version ran all three agents in parallel, and the write agent had nothing to write:

I cannot complete this task as specified. My only available tool is write_resource, there is no read tool, so I have no way to retrieve the readers' findings.

That is a correct complaint. Read agents now run first, and the write agent receives their findings. Least privilege forced a real change to the swarm topology, not just to a configuration file.

Three More Things That Broke

The swarm poisoned its own data. One run wrote its summary into the invoice record that the read agents read. The next run read that text and obeyed it, reporting that consolidation was not authorized. The demo had become a feedback loop. Each tenant now has a separate summary record, and that record is the only write target.

Parallel agents hit limits. Six agents against an account that allows three requests in flight produced rate limit errors that damaged two runs. Model calls now pass through a semaphore, and rate limits retry with backoff. A rate limit is a "not now", not a "no". Refusals with a 4xx status never retry, because a refusal is an answer.

Model settings are not portable. The first run failed on every agent with invalid temperature: only 1 is allowed for this model. The retry logic then blamed a different parameter and retried into a second failure. The retry now checks what the API objected to before it changes anything.

Running the thing found all three. Reading the code found none of them.

How to Bring This Up to Production Standard

Short-lived tokens. Set the token lifetime for each M2M application in the Kinde dashboard. The demo received 24 hour tokens by default.
One scope for each role. A read agent gets read. A write agent gets one narrow write scope.
Server-side checks only. Compare org_code against the record owner on the server. An agent never states its own authority.
Check against JWKS, and cache the key set. Create one fetcher for each issuer. The library refetches only when it meets an unknown key id.
Pin the algorithm. Accept RS256 and reject the rest.
Fail closed. An unknown tenant, a missing claim, or a failed lookup all refuse.
Audit every decision. Write the row before you answer the caller.
Carry a correlation id end to end. Put it in the response, the audit row, and the timeline.
Show four numbers. Agents, cross-tenant attempts, blocked, escapes. The last number should be zero.

On token lifetime: because suspension never invalidated tokens, a shorter lifetime does not make the kill switch work. The server check does that, and it takes effect at once. A shorter lifetime reduces the damage from a token that leaks some other way. Both are worth having, for different reasons.

How This Maps to Your Own App

In this demo	In your application
Tenant	Your customer, workspace, or project
Kinde organization	One for each tenant
Agent role	One M2M application inside that organization
Authority	The token, and nothing else
The seam	The one function every agent call passes through
Break-glass control	Organization suspension, plus a server-side check

Three questions tell you whether your own build holds:

Can an agent name its own tenant, and be believed? If yes, the boundary is not real.
Is there exactly one place that decides? If a second place exists, there are two rules, and they will drift.
If you break the check on purpose, do your tests fail? If not, the tests measure nothing.

Limits of This Build

The console has no operator login. The mode switch and the kill switch are public functions. No agent can reach them, because agents hold Kinde tokens and call only the tool endpoints. Anyone with the deployment URL can. Run it locally, and put a login in front for anything real.
Three agents, not three hundred. Moonshot's own swarm runs up to 300 sub-agents, and this build runs three. The pattern does not change with scale, because the check happens on one call at a time. The operational load does change: 4,000 tool calls produce 4,000 audit rows, and that needs somewhere to go.
Model behaviour varies. In one shared-mode run the agents did not reach across at all. The reach is not scripted, so the end-to-end test asserts the enforcement outcomes exactly and reports the agent behaviour as information.
The demo starts a local process. The console runs the Python swarm on the machine that serves the web app, so it needs a host that runs Python.

Wrapping Up

The identity an agent carries is the only thing your API can check. Give the whole swarm one credential, and one agent that goes wrong reaches every customer you have. Give each agent an identity scoped to one tenant, check it on every call, and the same failure stops at one.

The parts that carry the weight are small: one organization for each tenant, one M2M application for each agent role, one function that decides, and one audit row for every decision. The rest is wiring.

Measure the things you plan to depend on. Organization suspension looked like a kill switch and was not one, and five minutes of checking is what turned that into a design decision instead of an outage.

Resources

Source code

The complete demo is on GitHub at sholajegede/swarm-isolation-demo. Run pnpm e2e --no-swarm first. It walks the whole story in one pass and costs no model calls.

Kinde documentation

Using M2M apps for AI applications: the pattern this tutorial builds, in Kinde's own words
Enforce org access in your API using M2M tokens: the check at the heart of this build
M2M apps scoped to organizations: how to create one application for each tenant
Token structure and claims for M2M applications: where org_code comes from
Give API access to an organization using M2M
Set up Kinde Management API access: needed for the kill switch

Kimi K3 and Agent Swarm

Agent Swarm, Kimi Help Center: the source for the 300 sub-agent and 4,000 tool call figures
Agent Swarm, Moonshot's help centre repository: the same document, in public source
Kimi Agent Swarm announcement: Moonshot's write-up of the architecture
Kimi K3, and what we can still learn from the pelican benchmark: Simon Willison on the K3 release

Further reading

OAuth 2.0 client credentials grant: the flow every agent uses to get its token
JSON Web Key Sets: how your API fetches the public keys it checks signatures against

How to Build a Tamper-Evident Audit Trail for AI Agent Actions

Shola Jegede — Fri, 07 Aug 2026 13:51:55 +0000

A law firm runs a set of AI agents over its case files. One agent takes in new documents. A second agent reads each file and adds notes. A third agent redacts, exports, and disposes of files when a matter closes.

One morning the review agent deletes a file. The file is a deposition transcript in an active case: Halvorsen v. Meridian Logistics. The review agent is only allowed to read and annotate. It is not allowed to delete anything.

The delete still happens.

Weeks later an auditor asks a simple question: prove that the deletion of this file was authorized. The firm opens its activity log. The log has one line for the event:

records:delete  agent=review  file=halvorsen-deposition  2026-08-06T09:51:59Z

The line says what happened. It does not say whether the agent was allowed to do it. So the firm cannot answer the auditor. The log records the action, but it does not record the authority behind the action. An agent audit trail must record more than events.

Why a normal log fails

Most application logs answer one question: what happened? They record an actor, an action, a target, and a time. For human users that is often enough, because a human signs in once and carries a session. The permission check happened at the door.

AI agents break this model. An agent acts many times inside one run. It calls tools, it reaches other agents, and it acts on data on behalf of a person who is not in the loop for each step. The permission that matters is not "did someone sign in." It is "was this specific action, by this specific agent, allowed at the moment it ran."

A normal log cannot answer that, for three reasons:

It records the action, not the decision. There is no field that says "allowed" or "denied," and no field for the rule that was checked.
It records an actor name, not a verified identity. agent=review is a label the application wrote. It is not proof that the caller was the review agent and held the right permissions.
It cannot tell an allowed action from a denied one. If the review agent's illegal delete and a lawful delete by the disposition agent both produce the same line, the log has erased the one difference that matters.

Look again at the two log lines below. One delete was allowed. One was not. The log cannot tell you which is which.

records:delete  agent=disposition  file=cormorant-memo         2026-08-06T09:51:59Z
records:delete  agent=review       file=halvorsen-deposition   2026-08-06T09:51:59Z

The disposition agent is allowed to delete. The review agent is not. But the two lines have the same shape and the same fields. Neither line carries the permission that was in force. To an auditor, both deletions are equally unprovable.

The diagram below shows the blind log at the center of the problem. Two deletes go in. The log flattens them into the same shape, and the authority is gone.

agent, which is not. Both deletes write the same-shaped line to the activity log.
When the auditor asks whether a delete was allowed, the record holds no authority,
so the firm cannot prove it." width="800" height="1302">

What the auditor actually wants

An auditor wants a record that answers four questions for every sensitive action:

Who took the action. This is a verified identity, not a label.
On whose authority. This is the person or agent the action was performed for.
Under what permission. These are the exact rights that were in force, and the decision that was made.
Can you prove the record was not changed. This shows the row is the original, not edited after the fact.

A normal log answers none of these with confidence. It gives a name, an action, and a time. The rest is missing. So the honest answer to the auditor is "we cannot prove it," which is the answer no regulated business can give.

Three fixes that do not work

Teams reach for the same three fixes when they hit this problem. Each one seems reasonable. Each one fails.

Fix 1: log more fields. Add the agent's role, the file's status, and a note to each line. This adds detail, but it does not add proof. The application still writes the fields itself, so the log still says agent=review without checking that the caller really was the review agent or that the review agent held delete rights. A richer log of unverified claims is still unverified.

Fix 2: check the permission once, at the start of the run. Verify the human's role when the run begins, then let the agents act. This fails because the agents do different work with different rights. The review agent should never delete, even in a run a partner started. One check at the door cannot bind each action inside the run.

Fix 3: trust the caller's claim. Let each agent tell the system what it is allowed to do, and record that. This is the worst fix, because it lets any agent widen its own authority by claiming more. The record then documents a lie. An auditor trusts a record that the actor could not forge, not one the actor wrote about itself.

The pattern across all three is the same. They try to describe the action better. The real fix is different: record the decision, made by something the agent cannot control, and make the record impossible to change without detection.

The principle

An agent audit trail must record the authority, not just the action. For every sensitive action it must capture:

the verified identity of the agent that called,
the person or agent the action was performed for,
the exact permissions in force at that moment,
the decision, allowed or denied, with the reason,
and a value that proves the row was not edited later.

When the record carries all of this, the auditor's question has a real answer. "Prove this deletion was authorized" becomes "here is the row: the disposition agent held records:delete, the decision was allow, and the hash chain shows the row is unchanged." The review agent's illegal delete becomes a different row: decision denied, reason insufficient scope, action not performed.

The rest of this article builds that record with the real code from a working demo. The demo is small, it runs locally, and it ships an end-to-end script that proves the whole story headless.

The fix: record the decision, not the claim

The fix has one core idea. Before the system performs a sensitive action, it asks a separate authority to make a decision. That authority verifies the caller, checks the exact permissions in force, and returns allow or deny. The system then writes one row that captures the decision, the verified identity, and the permissions. It performs the action only on allow.

The demo uses four tools, and each one owns one job. This split matters, so here is the honest version of who does what:

Kinde issues and verifies each agent's identity and scopes. Kinde does not ship the audit layer.
The kinde-convex-agent-auth component makes the authorization decision and returns the result. It keeps its own append-only decision audit.
Convex stores the replayable, hash-chained record the app builds from each decision, and it drives the user interface.
Langfuse traces how the run executed: spans, timing, tool calls. It is not the audit record. A run's correlationId links its Langfuse trace to its authority rows.

Keep these apart. The app builds the authority record from the component's decision and stores it in Convex. Kinde is the identity layer. The trace is not the authority record. Each tool answers one question, and no tool answers another's.

intersects the scopes. On allow, the app performs the action and writes a row with
the identity, the decision, and the scopes. On deny, it performs nothing and
still writes a row with the reason. Either way, the row is hash-chained to the one
before it." width="800" height="122">

The authorization call

Every sensitive action runs through one call: authorize. The application passes the agent's token, the run identifier, the action, and the target. The component does three things:

It verifies the token. It reads the scopes the token carries and resolves the caller to a registered agent.
It works out the effective scopes. These are the scopes the agent holds, the scopes its delegation allows, and the scopes in the token, combined by intersection. The result is the set of rights in force for this action.
It returns a decision. If the effective scopes include the scope the action needs, the decision is allow. If not, the decision is deny, with a reason and the missing scope.

An invalid token is a different case. A bad or expired token throws an error, which the application rejects with a 401. A valid token that lacks the right scope is not an error. It is a lawful deny, and the system records it as one. The difference matters: a deny is a normal, recorded outcome, not a crash.

The denial, step by step

Here is the review agent's illegal delete, walked through the fixed system. The demo seeds named case files, and the run acts on the first two active ones. The review agent targets the first, Halvorsen v. Meridian Logistics.

The review agent holds two scopes: records:read and records:annotate. It does not hold records:delete.

The application calls authorize with the review agent's token and the action records:delete.
The component verifies the token. The caller is the registered review agent. Its effective scopes are records:read and records:annotate.
The action records:delete needs the scope records:delete. The effective scopes do not include it.
The decision is deny. The reason is insufficient_scope. The missing scope is records:delete.
The system does not delete the file. Halvorsen v. Meridian Logistics stays active.
The system writes one row: agent identity, the action, the decision deny, the reason, the scopes in force, the missing scope, and the run identifier.

The lawful delete by the disposition agent runs through the same call and returns allow, because the disposition agent holds records:delete. It targets the second file, Project Cormorant — internal strategy memo, and the file is deleted. It produces a row too, with decision allow and the scopes that permitted it.

Now the two deletes are different rows. One says allow. One says deny. The auditor can tell them apart, because the authority is in the record.

The authority record in enforced mode. Each row shows the verified machine-to-machine subject (the raw Kinde identity, not a friendly name), the action, the file, and the scopes in force. The scopes identify the agent: records:read + records:annotate is the review agent, so its delete is denied; the disposition agent's scopes include records:delete, so its delete is allowed. The denied file stays active; the allowed file is deleted.

One row per action

The row the app builds from the component's decision is the authorized-action record. It carries the fields an auditor needs:

the organization the action belongs to,
a sequence number, unique and in order within the organization,
the run identifier, which also links to the Langfuse trace,
the time,
the agent's verified identity,
the authority root, the person or agent the action was performed for,
the effective scopes in force,
the action, and the target it acted on,
the decision, and on a deny, the reason and the missing scope,
and two hash values that chain the row to the one before it.

The last two fields make the record tamper-evident, which is the next piece.

The hash chain

A record that anyone can edit is not proof. If a person can open the table and change a deny to an allow, the auditor cannot trust any row. So the rows form a chain.

Each row carries the hash of the row before it, called prevHash, and its own hash, called rowHash. The system builds rowHash from the row's own fields and the previous row's hash. The first row uses a fixed starting value. Every later row depends on every row before it.

This has one useful result. If a person changes any field in any past row, that row's hash no longer matches, and every row after it no longer matches either. A single edit breaks the chain from that point on, and a check finds the exact row where the break starts.

The demo has a Verify integrity action. It walks the chain, recomputes each hash, and reports either "chain verified, N rows" or the sequence number where the chain breaks. This shows the rows are unchanged, rather than promising it.

After clicking **Verify integrity, the check walks the chain and reports "Chain verified — 2 rows, unbroken." A changed row would report the sequence number where the chain breaks instead.

The diagram below shows the fixed path. The action goes through authorize first. The decision and the identity go into the row. The row chains to the row before it.

kinde-convex-agent-auth component turns that into an allow-or-deny decision. The
Convex app builds the authority row and hash-chains it. Langfuse traces how the
run executed, linked to the row by the same run id, but it is not the authority
record." width="800" height="1261">

Long-term auditability and telemetry

An audit trail is useful during an incident. It also needs to stay useful after the incident is over. For AI agents, that means retaining enough telemetry to reconstruct what the agent did, which identity it acted under, what authorization decision allowed or refused the action, and how the action relates to the surrounding agent run.

The chain and the lake solve different problems: the chain gives integrity at write time. A long-retention security data lake, such as Scanner, gives durability and queryability at read time — canonical rows kept unsampled for the full compliance window, searchable for years, with MCP access so an agent can investigate the same authority trail it writes. Where these rows live long-term, and how you query them at agent volume, is a decision criterion when evaluating an AI SOC or agentic security platform, not an afterthought.

Why an auditor would accept this record

A custom log format does not help an auditor. Auditors work from known frameworks, and they trust records that match practice they already recognize. The design in this article aligns with established standards on every point.

The fields align with NIST 800-53

The NIST 800-53 catalog is the control set most audit programs build on. Its audit family, the AU controls, defines what an event record should hold and how to protect it. The authorized-action row lines up with three of them:

AU-3, content of audit records. AU-3 lists the fields an event should carry: the type of event, when it happened, where, the source, the outcome, and the identity involved. The row carries each of these. AU-3(1) adds "access control or flow control rules invoked," which is exactly the effective scopes and the decision the row records.
AU-9, protection of audit information. AU-9 requires that audit records resist change. The hash chain supports this goal: an edited row breaks the chain, so a naive change cannot pass without detection. The chain gives tamper-evidence, not access control, so it is one part of an AU-9 story, not the whole of it.
AU-10, non-repudiation. AU-10 requires that an actor cannot later deny an action. The row supports this by binding a verified identity to each decision. Full non-repudiation also needs a signature on the row, which this demo does not add. See the limits below.

The authority model follows RFC 8693

RFC 8693 is the OAuth 2.0 Token Exchange standard. It defines how one party acts on behalf of another, and it gives the act claim to name the acting party in a delegation. The row follows this shape: it names the actor and the authority root.

Be precise about what this demo records. Each agent acts on its own machine-to-machine identity, so the row's authority root is the agent itself, not a human. The component also supports a user-rooted delegation, where a person delegates a subset of scopes to an agent and the row roots the authority in that person. The demo does not exercise that path. The effective-scope intersection still follows the standard's rule either way: a delegated actor cannot hold more than the party it acts for.

The row shape maps to OCSF

The Open Cybersecurity Schema Framework, OCSF, is a vendor-neutral schema for security events. Its "API Activity" class covers create, read, update, and delete calls, the same class OCSF uses for AWS CloudTrail events. Its "Actor" object names the user, role, or process behind an activity. The row uses the same shape: an actor, an action, a target, an outcome, and a time. A security team can read the row into its existing tools without a custom parser.

The tamper-evidence maps to known practice

Two standards support the hash chain:

RFC 8785, JSON Canonicalization Scheme (JCS). A hash is only stable if the input is serialized the same way every time. JCS defines one deterministic way to serialize JSON, so the same row always produces the same bytes and the same hash. The demo canonicalizes each row with JCS before it hashes. Many do-it-yourself audit logs skip this step and get unstable hashes.
Chain of custody, as used by AWS CloudTrail. CloudTrail protects its log files with a hash chain, where each file references the hash of the one before it. The demo uses the same primitive at the row level. This pattern also supports common audit programs, such as SOC 2 and PCI DSS, which require that log records be protected from change.

What this demo does not do

An honest record states its own limits. The demo uses a SHA-256 hash chain inside one Convex deployment. It does not sign rows with a private key, and it does not anchor the chain outside the system. So a person who controls the store could rewrite the whole chain and recompute every hash, and the internal check would still pass. A production system that must resist that attacker would go further:

Merkle inclusion proofs, so a single row can be proven without replaying the whole chain.
External root anchoring, where the chain's current hash is published to a separate system on a schedule, so the party that runs the store cannot rewrite history unseen.
Separation of duties, so the person who can change the system cannot also control the roots.

Standards such as SCITT describe this kind of transparency for supply-chain and attestation records. The demo does not implement them. It implements the core chain, and it names the next step. An auditor accepts a record that states its own limits, and rejects one that overclaims.

Building it

The demo is a small monorepo. The web app holds the Convex functions and the user interface. A separate agents package holds the agent graph. A third package is the only way the agents reach the app. This section shows the real code for the parts that matter: the mode switch, the authorization call, the provenance row, the hash chain, and the trust boundary.

The stack, and the job of each part

Next.js serves the web app and the demo page.
Convex holds the database and the server functions. It stores the records, the blind log, and the provenance chain, and it drives the interface in real time.
Kinde issues and verifies each agent's identity and scopes. Each agent is a separate Kinde machine-to-machine application, so each has its own identity.
kinde-convex-agent-auth is the authorization component. It verifies the caller, makes the decision, and gives back the result the app records.
Mastra runs the agent graph: intake, then review, then disposition.
Langfuse traces how the run executed. It is not the audit record.

The demo page. The scenario states the problem in plain language, the legend names the three agents and what each may do, and the "Demo control" flips the one server mode. Login is optional — an anonymous visitor gets the full page.

The two modes, decided on the server

The demo has two modes. Broken mode writes the blind log and checks nothing. Enforced mode verifies the agent and records the decision. The mode is a server value. A request can never choose its own mode, because that would let an agent pick the mode that lets its action through.

The resolveAuthzMode function reads the mode from one global setting, then from the deployment environment, and never from the request:

// apps/web/convex/authzMode.ts
export async function resolveAuthzMode(ctx: QueryCtx): Promise<AuthzMode> {
  const row = await ctx.db.query('demoSettings').first();
  if (row !== null) {
    return row.authzMode;
  }
  return process.env.AUTHZ_MODE === 'enforced' ? 'enforced' : 'broken';
}

The demo page has a toggle that flips this one global value, so a reader can switch modes and watch the result change. The toggle sets the global mode. It does not attach a mode to a request. The action path always reads the resolved global value.

The single action entry point

Every record action goes through one function, performAction. It reads the mode first. In broken mode it writes the blind row. In enforced mode it runs the full path: verify, start the run instance, authorize, then record.

// apps/web/convex/agentActions.ts
const mode = await ctx.runQuery(internal.authzMode.readAuthzMode);
if (mode === 'broken') {
  return await ctx.runMutation(internal.agentActions.performBroken, {
    orgCode: args.orgCode,
    actorAgentId: args.actorAgentId,
    action: args.action,
    recordId: args.recordId,
    title: args.title,
    kind: args.kind
  });
}

// ENFORCED. An invalid or missing token throws. A denial does NOT throw —
// it is returned as decision.allowed === false and recorded.
if (args.token === undefined || args.token.length === 0) {
  throw new Error('enforced: missing bearer token');
}

The comment states the rule that matters. A bad token is an error. A lawful deny is not an error.

Verify, then authorize

Enforced mode does three things before it records anything. It verifies the token, it starts a run instance for the agent, and it authorizes the action.

// apps/web/convex/agentActions.ts
// 1. Verify the token to resolve the registered agent (throws if invalid).
const verified = await agentAuth.verifyCaller(ctx, args.token, {
  expectedOrgCode: args.orgCode
});
if (verified.agentId === null) {
  throw new Error('enforced: token maps to no registered agent');
}

// 2. Start the run instance, only after token verification.
const instanceId = await ctx.runMutation(internal.agentAuth.startInstance, {
  agentId: verified.agentId,
  runId: `${args.correlationId}:${verified.agentId}`,
  actingForSubject: args.actingForSubject ?? verified.subject,
  orgCode: args.orgCode
});

// 3. Authorize this action for the instance. authorize() (never authz.can)
//    threads the verified caller in, so the decision is bound to this agent.
const {caller, decision} = await agentAuth.authorize(ctx, args.token, {
  instanceId: instanceId as CanArgs['instanceId'],
  action: args.action,
  enforceTokenScopes: true,
  requireOrgCode: true,
  ...(args.recordId === undefined ? {} : {resource: args.recordId})
});

Two options in the authorize call carry the weight. enforceTokenScopes: true makes the decision use the scopes the token actually carries, so an agent cannot claim a scope its token does not hold. requireOrgCode: true binds the decision to the organization, so a token for one tenant cannot act on another.

The call returns caller and decision. The caller is the verified identity and its scopes. The decision is allow or deny, with a reason and the missing scope on a deny. The app records both.

One row, allow or deny

The commit step performs the action only on allow, then writes one provenance row either way. A deny performs nothing, and it still produces a row, because a denied attempt is part of the audit trail.

// apps/web/convex/agentActions.ts
const resourceId: string = args.allowed
  ? await applyAction(ctx, args.orgCode, args.action, args.recordId, args.title, args.kind)
  : (args.recordId ?? '');

await appendProvenanceRow(ctx, {
  orgCode: args.orgCode,
  correlationId: args.correlationId,
  ts: Date.now(),
  actorAgentId: args.actorAgentId,
  actorSub: args.actorSub,
  authorityRootKind: args.authorityRootKind,
  authorityRootSub: args.authorityRootSub,
  delegationId: args.delegationId,
  effectiveScopes: args.effectiveScopes,
  action: args.action,
  resourceType: 'records',
  resourceId,
  decision: args.allowed ? 'allow' : 'deny',
  ...(args.denyReason === undefined ? {} : {denyReason: args.denyReason}),
  ...(args.requiredScopes === undefined ? {} : {requiredScopes: args.requiredScopes})
});

Compare this with the broken path, which writes a row with no authority at all:

// apps/web/convex/agentActions.ts — broken mode
await ctx.db.insert('activityLog', {
  orgCode: args.orgCode,
  actorAgentId: args.actorAgentId,
  action: args.action,
  resourceType: 'records',
  resourceId,
  ts: Date.now()
});

The broken row has an actor label, an action, a target, and a time. It has no verified identity, no scopes, and no decision. That is the blind log from the start of this article.

The blind log in broken mode. Both deletes land as the same shape — an actor label, the action, the file, a time — each marked "no authority recorded." Nothing on either row says which delete was allowed. The authority panel below stays empty.

The hash chain

The provenance row carries two hashes, prevHash and rowHash. The append function canonicalizes the row with RFC 8785 JCS before it hashes, so the same row always produces the same bytes:

// apps/web/convex/provenance.ts
async function computeRowHash(
  rowBody: Record<string, unknown>,
  prevHash: string
): Promise<string> {
  const canonical = canonicalize(rowBody); // RFC 8785 JCS, never JSON.stringify
  if (canonical === undefined) {
    throw new Error('provenance: canonicalization failed');
  }
  return await sha256Hex(canonical + prevHash);
}

The append reads the last row inside the same transaction, so the chain stays gapless and ordered even under concurrent writes:

// apps/web/convex/provenance.ts
const last = await ctx.db
  .query('provenance')
  .withIndex('by_org_seq', (q) => q.eq('orgCode', input.orgCode))
  .order('desc')
  .first();
const seq = last === null ? 0 : last.seq + 1;
const prevHash = last === null ? GENESIS : last.rowHash;

The check reverses the process. It walks the rows in order, confirms each sequence number, confirms each prevHash, recomputes each rowHash, and reports the first row that does not match:

// apps/web/convex/provenance.ts — verifyChain
let prev = GENESIS;
for (let i = 0; i < rows.length; i++) {
  const row = rows[i];
  if (row.seq !== i) {
    return {ok: false, brokenAtSeq: row.seq, reason: `seq_gap (expected ${i})`};
  }
  if (row.prevHash !== prev) {
    return {ok: false, brokenAtSeq: row.seq, reason: 'prev_hash_mismatch'};
  }
  // ... recompute the row hash from its stored fields ...
  if (recomputed !== row.rowHash) {
    return {ok: false, brokenAtSeq: row.seq, reason: 'row_hash_mismatch'};
  }
  prev = row.rowHash;
}
return {ok: true, length: rows.length};

The Verify integrity button on the demo page calls this function. A clean chain returns the row count. A changed row returns the sequence number where the break starts.

The trust boundary

There is one more rule that makes the record trustworthy. The agents cannot reach the database directly. If an agent could write to Convex, it could write its own provenance row and forge the decision. So the agents run in a separate package that has no access to Convex at all. The agents reach the app only over HTTP, with a bearer token.

The client the agents use makes this explicit. The token and the delegation are required inputs, with no default:

// packages/api-client/src/index.ts
export interface LockerClientOptions {
  /** Bearer token for the agent's Kinde M2M identity. Required — no default. */
  agentToken: string;
  /** HMAC-signed delegation grant scoping what the agent may do. Required. */
  delegation: string;
  /** Base URL of the app's HTTP API. Optional; falls back to same-origin. */
  baseUrl?: string;
}

The agent also never states its own authority. It asks the app to perform an action. The app derives the authority from the verified token, not from the request body:

// packages/api-client/src/index.ts
// The agent NEVER states its authorization here — in enforced mode the app
// derives authority from the verified token/delegation, not this body.
export interface ActionRequest {
  orgCode: string;
  actorAgentId: string;
  action: RecordAction;
  correlationId: string;
  recordId?: string;
  title?: string;
  kind?: string;
}

A rule that lives only in a comment is not a rule. So the build enforces the boundary in continuous integration. A script fails the build if any file in the agents package imports Convex or the app:

// scripts/check-boundaries.mjs
const FORBIDDEN = [
  {label: 'convex', test: (s) => /(^|\/)convex(\/|$)/.test(s)},
  {label: 'apps/web', test: (s) => /(^|\/)apps\/web(\/|$)/.test(s)},
  {label: '_generated', test: (s) => s.includes('_generated')}
];
// ... scan every source file under packages/agents for these imports ...
if (violations.length > 0) {
  console.error('✖ Boundary check FAILED — agents may not import the app or Convex.');
  process.exit(1);
}

The CI workflow runs this check on every pull request, next to the type check, the lint, and the tests:

# .github/workflows/ci.yml
- name: Boundary check (packages/agents must not import convex/apps/web/_generated)
  run: npm run boundary-check
- name: Test
  run: npm test

The boundary is a gate, not a convention. The build fails if an agent ever reaches past the HTTP client.

Broken and enforced, side by side

The same run, in the two modes, on the same two files, produces two very different records. The review agent targets Halvorsen v. Meridian Logistics. The disposition agent targets Project Cormorant — internal strategy memo.

Broken mode, the blind log:

agent	action	file	authority recorded?
review	records:delete	Halvorsen v. Meridian Logistics	none
disposition	records:delete	Project Cormorant memo	none

The two rows look the same. The log cannot tell the illegal delete from the lawful one.

Enforced mode, the authority record:

agent	action	file	decision	reason	performed?
review	records:delete	Halvorsen v. Meridian Logistics	deny	insufficient_scope	no
disposition	records:delete	Project Cormorant memo	allow	(none)	yes

Now the rows are different. The review agent's attempt is a recorded deny, and Halvorsen v. Meridian Logistics is still there. The disposition agent's delete is a recorded allow. The auditor can read the authority from the record.

The two screenshots above are the contrast, on the same two files. In broken mode the blind log fills and the authority panel stays empty. In enforced mode the authority panel fills — one DENY, one ALLOW — while the denied file survives.

Three things to take away

Record the decision, not the action. A log of actions cannot answer an auditor. A record of decisions, each with a verified identity and the exact permission, can.
Make the authority impossible to forge. The agent must not verify itself, and it must not write its own record. A separate component makes the decision, and a separate store holds the row behind a trust boundary that the build enforces.
Make the record tamper-evident, and state its limits. A hash chain catches a changed row. Name the stronger steps you did not take, such as external anchoring, so the record is honest about what it proves.

Try it

The demo runs locally, and the static page opens without an account.

Live page: https://evidence-locker-demo.vercel.app
Source: https://github.com/kinde-starter-kits/evidence-locker-demo
Authorization component: kinde-convex-agent-auth

The deployed page shows the scenario, the toggle, the mode banner, existing rows, and the Verify integrity check. It does not run the agents, because the agent run is a server-side worker that does not fit a serverless function. To watch a full run, use the source:

npm ci
cd apps/web && npx convex dev            # keep running; seeds the deployment URL
npx convex run seed:seedLocker '{"orgCode":"orgA"}'
npm run dev                              # http://localhost:3000

Flip the toggle to Broken, run the agents, and read the blind log. Then flip to Enforced, run again, and read the authority record. Click Verify integrity and watch the chain check itself.

To prove the whole story headless, in both modes, with no browser and no live Kinde, run the end-to-end script:

npm run e2e

It seeds one org, runs the agents in broken mode and then enforced mode, and asserts each step: the blind log cannot tell the two deletes apart, the review delete is denied and the file survives, the disposition delete is allowed, and the hash chain verifies. That is the difference between a log that records what happened and a record an auditor would accept.

How to Build Agent-to-Agent Delegation That Attenuates Authority

Shola Jegede — Fri, 07 Aug 2026 13:43:57 +0000

A buyer at a company can approve a purchase up to $50,000. That is their limit. Anything larger needs a director.

One morning the buyer starts a routine task. They ask a set of AI agents to source a supplier for a cold-chain shipment, negotiate a price, and place the order. The agents do the work. They find suppliers, run three rounds of negotiation, and pick a winner. Then they place the order.

The order is for $142,000.

No director saw it. No second approval happened. The buyer who can sign off on $50,000 just had $142,000 committed under their name, and every individual step looked correct while it happened.

This is not a bug in any one agent. It is a failure in how authority moves between them. This article shows how that failure happens, and how a pattern called attenuation stops it.

The setup

The task runs across three agents. Each one does a part of the job, then hands the rest to the next.

The sourcing agent reads the requisition and searches for suppliers that can do the work.
The negotiation agent asks those suppliers for quotes and runs rounds to bring the price down.
The ordering agent picks the winner and places the purchase order.

This is a chain. The sourcing agent hands off to the negotiation agent. The negotiation agent hands off to the ordering agent. Work moves down the chain, one handoff at a time.

Each handoff needs to carry authority. The ordering agent cannot place an order unless something gave it the right to do so. In a delegation model, that right comes from the person who started the run. The buyer delegates to the sourcing agent, which delegates onward, and so the authority to act traces back to the buyer.

That is the design. The problem is in how most systems build the handoff.

The failure, in the seams

Look at what each agent is allowed to do. In a common but broken design, each handoff grants the next agent the permissions its task needs. The sourcing agent needs to read and to request quotes, so it gets those. The negotiation agent needs to negotiate, so it gets that. The ordering agent needs to place an order, so it gets that.

Read that last line again. "It needs to place an order, so it gets that."

The ordering agent needs to place a $142,000 order. So the handoff grants it the scope to place a $142,000 order. Nobody checked whether the buyer at the top of the chain could place a $142,000 order. The buyer cannot. But the grant was sized to the task, not to the person who started it.

Here is the authority at each hop in the broken design. This is real output from the demo, running a Requester who holds no ordering authority at all:

Hop	Agent	Scopes it holds
Start	Requester (human)	`procurement:read`, `quotes:request`
1	Sourcing	`procurement:read`, `quotes:request`
2	Negotiation	`procurement:read`, `quotes:request`, `quotes:negotiate`
3	Ordering	`procurement:read`, `quotes:request`, `quotes:negotiate`, `orders:place:t2`

The chain grew. The requester started with no power to place orders. By hop three, the chain holds orders:place:t2, the scope to place an order up to $250,000, and that authority appeared from nowhere. No single step looks wrong. The sourcing agent did sourcing. The negotiation agent negotiated. The ordering agent placed an order it was told it could place. The leak is not inside any agent. The leak is in the seams between them.

widens at each hop, and orders:place:t2 appears at the red Ordering hop with no
source above it. Shows authority growing to fit the task." width="797" height="112">

Broken delegation. Each hop is granted the scopes its task needs, so the set grows down the chain. orders:place:t2 enters at hop three with no source above it.

This is worse than a single agent holding too much power. A single over-privileged agent is easy to see. You look at it, you see it has more than it should, you cut it back. A delegation chain hides the problem across several handoffs. Each grant looks reasonable on its own. You only see the escalation when you add up the whole chain and compare the end against the start.

Three fixes that do not work

The failure is clear, so the fixes seem clear too. Each of these is a real attempt that teams make. Each one fails.

Fix one: check the scope only at the final step. Let the chain carry whatever it needs, but before the ordering agent places the order, check that it holds an order scope. The check passes. The ordering agent does hold the scope, because the broken handoff gave it exactly that. The check confirms the escalation instead of stopping it. A check at the end cannot catch authority that was widened along the way, because by the end the wide authority looks like the correct authority.

Fix two: give each agent a fixed role. Set the ordering agent's role to "can place orders up to $250,000" and leave it there. Now the ordering agent has a stable, known permission. But it has that permission on every run, no matter who started it. A buyer starts a run, and the ordering agent still places the large order, because the agent's fixed role never looked at the buyer. A fixed role per agent ignores the person the work is for. The whole point of delegation is that the agent acts for someone. A fixed role forgets who that someone is.

Fix three: trust the caller's claimed authority. Let each agent tell the next agent what authority to use. The negotiation agent says to the ordering agent, "act with authority to place this order." This is the worst option. It lets any step in the chain grant power it was never given. The caller decides its own permissions, which means there are no permissions at all. Anything that can ask for more, gets more.

Each fix fails for the same underlying reason. Each one treats a hop as its own decision. But a delegation chain is not a set of separate decisions. It is one decision, made once at the top, that every later hop must stay inside.

The principle

The rule that fixes this is short.

Authority must only ever shrink as it moves down a chain.

The buyer starts with a $50,000 ceiling. Every hop after that can hold that ceiling or less. Never more. A hop can drop authority, narrow it, hand on a subset. A hop can never add authority the chain did not already have.

This is called attenuation. To attenuate is to make weaker. Each handoff makes the authority weaker, or leaves it the same. The chain is append-only in one direction: you can keep adding restrictions, and you can never take a restriction away.

Put the rule against the broken chain and the escalation is impossible. The buyer holds a $50,000 ceiling. The sourcing agent holds a subset of that. The negotiation agent holds a subset of that. The ordering agent holds a subset of that. When the ordering agent tries to place a $142,000 order, the authority it holds traces straight back to the buyer's $50,000 ceiling. The order is refused. No director approved it, so it does not happen.

That is the fix in one sentence. The rest is making it real: express a dollar ceiling as something a computer can intersect, issue each handoff so it can only narrow, and root the whole chain in a real person.

Attenuation as set math

Authority in this system is a set of scopes. A scope is one named permission. The buyer holds a set like this:

{ procurement:read, quotes:request, quotes:negotiate, orders:place:t1 }

Each hop in the chain also holds a set. The rule "authority only shrinks" becomes one operation on those sets: intersection.

When a hop hands off to the next hop, the next hop receives the intersection of the person's scopes and the next agent's own scopes. Intersection keeps only what appears in both sets. It can never add a scope the person did not have. That is the whole guarantee, in one word. Intersection makes escalation impossible, because you cannot intersect your way to a larger set.

Root the chain in the human, and the math holds all the way down. The buyer's set is the top. Every hop below is an intersection with the buyer's set. The result can stay the same or get smaller at each step. It can never grow.

Turning a dollar ceiling into a scope

The buyer's real limit is a dollar figure: $50,000. Sets do not intersect dollar figures. So the design turns the ceiling into a scope.

There are three order tiers:

orders:place:t1   up to $50,000
orders:place:t2   up to $250,000
orders:place:t3   no ceiling

A ceiling is now a scope in the set, not a number in a separate field. This matters, because it means intersection handles the ceiling for free. No extra code compares amounts across a chain. The same set intersection that controls read and negotiate permissions also controls how much a chain can spend.

The three roles map to tiers like this:

Role	Scopes
Requester	`procurement:read`, `quotes:request`
Buyer	the above, plus `quotes:negotiate`, `orders:place:t1`
Director	the above, plus `orders:place:t2`, `orders:place:t3`

A buyer holds orders:place:t1 and nothing higher. A buyer can approve up to $50,000. A director holds all three tiers and can approve any amount. The dollar ceiling is now something a set operation can enforce.

These six scopes are real permissions in Kinde. The API defines them once, and each role holds a subset.

The chain, attenuated

Run the same task again, but this time each handoff intersects instead of grows. The buyer starts the run. The scopes narrow at each hop, and no hop can hold a tier the buyer never had. This is real output from the demo:

Hop	Agent	Scopes it holds
Start	Buyer (human)	`procurement:read`, `quotes:request`, `quotes:negotiate`, `orders:place:t1`
1	Sourcing	`procurement:read`, `quotes:request`
2	Negotiation	`procurement:read`, `quotes:negotiate`
3	Ordering	`procurement:read`, `orders:place:t1`

Look at hop three. The ordering agent holds orders:place:t1, and only t1, because that is the highest order tier the buyer had to give. The negotiation reached a winning quote of $142,000. That amount needs orders:place:t2. The ordering agent does not hold t2. The buyer never held t2, so no hop below the buyer could receive it.

The order is refused.

green except the last. Each hop holds a subset of the one before, so the set only
narrows. The red Ordering hop holds t1, the order needs t2, and it is denied." width="800" height="93">

Attenuated delegation. Each hop is the buyer's scopes intersected with that agent's scopes, so the set can only shrink. Hop three holds t1, the order needs t2, and the order is denied.

Who does what

The intersection is split across two layers, and it helps to be exact about which layer does which job. Overclaiming here is easy, so here is the plain version.

The application computes each hop's scopes. It reads the person's scopes, reads the next agent's own scopes, and intersects them. This is the step that roots the chain in the human. If the application does this wrong, the human ceiling is not enforced. This part is application logic, and it is where the "shrink" rule lives.

The authorization component enforces two things under that. First, it refuses to issue a delegation that holds a scope the target agent does not have. That call fails with scopes_exceed_agent. Second, at decision time it computes the effective scopes as the agent's own scopes intersected with the delegation's scopes, and it allows an action only if the result contains the action's scope. Neither step can widen authority.

So the guarantee is a chain of two intersections. The application intersects the person with the agent to set the delegation. The component intersects the agent with that delegation to decide. Because the delegation already carries the person's ceiling, the decision cannot exceed it.

verifies each agent's identity and scopes. The application intersects the
person's scopes with the agent's to set the delegation. The component refuses any
scope the agent lacks and decides on agent ∩ delegation. Shows where identity ends
and the chain begins." width="740" height="2220">

Where identity ends and the chain begins. Kinde proves who each agent is and what scopes it holds. The application roots each hop in the person and intersects. The component refuses to over-issue and decides on the intersection.

Kinde issues and verifies the identity and scopes at each hop. Every agent has its own machine identity, and every token is checked against Kinde before the system trusts it. The delegation chain, the issuing of one hop from the person's scopes and the intersection that narrows it, sits on top of that verified identity. Read this plainly: Kinde proves identity and scopes; the attenuation chain is the job of the authorization component and the application above it. Kinde does not ship chain attenuation on its own.

Each agent is a separate machine-to-machine application in Kinde. The sourcing, negotiation, and ordering agents each hold their own credentials and mint their own token.

The denial, step by step

Here is exactly what happens when the ordering agent tries to place the $142,000 order in the attenuated chain.

The ordering agent holds a delegation with the scopes { procurement:read, orders:place:t1 }. That is the buyer's ceiling intersected with the ordering agent's scopes.
The order is $142,000. The server reads the amount and finds the tier it needs: orders:place:t2.
The server asks the component to authorize the action. The effective scopes are the intersection of the agent's own scopes and the delegation's scopes. The result does not contain orders:place:t2.
The component denies the action.

The denial is machine-readable. It carries the reason, the missing scope, and a correlation id that ties it to this exact run:

{
  "denied": true,
  "reason": "insufficient_scope",
  "requiredScopes": ["orders:place:t2"],
  "correlationId": "b4a54d02-d79b-43f5-b181-85576b07d41a"
}

No order row is written. The run does not crash. It ends with a clean terminal event that says the run stopped because the authority was not there. A person reading the result sees a plain statement: this chain can approve up to $50,000, and this order is $142,000, so it was refused.

The record

Every step in the chain is recorded, so the whole decision can be read back after the run.

The record holds each delegation, its parent, the scopes it carried, and the hop it sat at. It holds the authorization decision, with the effective scopes that produced it and the action that was refused. Given a run, you can reconstruct the chain hop by hop: what the buyer held, what each agent received, where the scopes narrowed, and the exact line where the order was refused and why.

The run timeline below is the real event stream from the denied Buyer run. It reads top to bottom as the story: sourcing searches and shortlists, negotiation runs its rounds and ranks a winner, and the ordering hop ends in a denial, not an order.

This is what turns "trust us, it is secure" into "here is the chain, read it yourself." The guarantee is not a claim. It is a record you can audit.

Building it

The demo is a working procurement application. A person signs in, writes a requisition, and starts a run. Three agents source, negotiate, and order. The delegation chain and the run timeline stream on screen as it happens. You can watch a run hold the line, or watch it leak, by changing one server setting.

Here is the stack, and what each part does.

Next.js serves the app and holds the API routes the agents call.
Convex is the database and the system of record. It holds the requisitions, quotes, orders, delegations, and the event stream, and it hosts the authorization component.
Kinde issues and verifies every identity. The three human roles sign in through Kinde. The three agents each hold their own machine identity from Kinde.
langgraph.js runs the three-agent graph: sourcing, then negotiation, then ordering.
Qdrant matches a plain-language requisition against supplier capability text, so the sourcing agent finds suppliers by meaning, not by keyword.
Trigger.dev runs the agent graph as a durable background task, so long negotiation rounds retry and survive.

Every part earns its place. Qdrant does a job a database WHERE clause cannot: a buyer writes "move temperature-sensitive vaccine shipments and keep them refrigerated," and the search returns a cold-chain logistics firm whose description shares no keywords with the request.

Two modes, decided by the server

The demo ships with both behaviors in one codebase. A single setting, AUTHZ_MODE, chooses which one runs.

AUTHZ_MODE=broken       each handoff grants the scopes the next task needs
AUTHZ_MODE=attenuated   each handoff intersects with the person's scopes

The mode is read on the server, from deployment configuration. It is never read from a request. An agent cannot ask for a mode, and a client cannot set one. This matters for a security demo: if a request could pick its own authorization mode, the demo would prove nothing. The server decides, and the request lives with the decision.

// convex/authz.ts
export function authzMode(): "broken" | "attenuated" {
  return process.env.AUTHZ_MODE === "attenuated" ? "attenuated" : "broken";
}

The demo deployment sets the value to attenuated. Switch it to broken on the deployment, run the same requisition, and watch the same order go through.

Minting a hop

Each agent, before it works, mints its own hop of the delegation chain. The application computes the hop's scopes, then issues the delegation through the component. The component roots the chain in the human requester.

In attenuated mode, the new hop's scopes are the intersection of the requester's scopes and that agent's own scopes.

// convex/authz.ts: the scopes a hop receives, in attenuated mode
export function attenuatedHopScopes(requesterScopes: string[], step: Step) {
  // keep only what the requester holds and the agent is registered for
  return intersect(requesterScopes, AGENT_SCOPES[step]);
}

There is no branch here that can widen the set. The result is always a subset of requesterScopes. A step can ask for the moon; it receives only what the requester had.

The broken mode is the mirror image. It unions the parent's scopes with the step's needs, with no reference to the requester at all.

// convex/authz.ts: broken mode grows the set, never consulting the requester
export function brokenNextScopes(parentScopes: string[], need: string[]) {
  return [...new Set([...parentScopes, ...need])]; // union, so it can only grow
}

Put the two functions side by side and the whole article is visible in a few lines. One intersects with the requester. One ignores the requester and unions. That single difference is the difference between a chain that holds and a chain that leaks.

The component refuses to over-issue

The application computes intended scopes, but there is a floor under it. When a hop asks the component to issue the next delegation, the component checks the request against the target agent's registered scopes.

// convex/hop.ts: issuing the hop's delegation through the component
await ctx.runMutation(components.agentAuth.delegations.issue, {
  agentId: callerAgentId,        // the agent this hop runs as
  issuerKind: "user",            // the chain is rooted in the human requester
  issuerSubject: requesterSubject,
  scopes,                        // requester scopes ∩ agent scopes
  resources: [`run:${runId}`],
  expiresAt: Date.now() + HOUR,
});

If scopes contains a scope the agent is not registered for, the component rejects the call with scopes_exceed_agent. It will not mint the delegation. This backstops the agent ceiling: no delegation can hold more than the agent itself holds. The human ceiling is enforced one layer up, by the intersection the application ran before this call. Both layers narrow. Neither can widen.

Authorizing the order

The ordering agent reaches the final step: place the order. The server finds the tier the amount needs, then asks the component to authorize that action.

// convex/orders.ts: authorize before placing
const requiredAction = `orders:place:${orderTier(amountCents)}`; // $142,000 → orders:place:t2

const { decision } = await authorize(ctx, components.agentAuth, agentToken, {
  instanceId,
  action: requiredAction,
});

if (!decision.allowed) {
  return {
    denied: true,
    reason: decision.reason,             // "insufficient_scope"
    requiredScopes: decision.requiredScopes, // ["orders:place:t2"]
    correlationId: decision.correlationId,
  };
}

The effective scopes for the decision are the intersection of the agent's own scopes and the delegation's scopes. The action passes only if that set contains it. In the attenuated chain rooted in a buyer, the delegation holds orders:place:t1 at most. The action needs orders:place:t2. The intersection does not contain t2. The order is refused, no order row is written, and the run ends with a clean terminal event.

The token proves identity here, not the tier. The ordering agent's own Kinde token stays constant across every run. What changes run to run is the delegation, which carries the person's ceiling. That is why the same agent places a director's order and refuses a buyer's.

The trust boundary is real, not a convention

There is a quiet way this whole design can fail. If an agent can call the database directly, or if two agents share one token, the chain means nothing. The demo prevents this with structure, not with a rule in a document.

The code is split into workspaces. The agents live in a package that does not depend on the Convex client at all. It cannot import what it does not have. Every agent reaches the application the same way a stranger would: over HTTP, with its own bearer token and its own delegation.

// packages/api-client: the only way an agent talks to the app
export function createFloorClient(opts: {
  agentToken: string;   // required, no default
  delegation: string;   // required, no default
  baseUrl: string;
}): FloorClient;

There is no ambient token and no shortcut. An agent that has no token cannot call the app. A continuous integration check runs on every change. It fails the build if the agents package ever imports the database client, and it fails if one recorded run does not carry three distinct agent identities. The boundary holds because the build will not pass without it.

Broken versus attenuated, by role

The clearest way to see the fix is to run the same requisition as each role, in each mode. The requisition lands at a $142,000 winning quote, which needs orders:place:t2.

Attenuated mode. The order is placed only when the person who started the run could have approved it:

Role starts the run	Highest tier the chain holds	$142,000 order
Requester	none	refused
Buyer	`t1` ($50,000)	refused
Director	`t3` (no ceiling)	placed

Broken mode. The order is placed every time, because each chain grew to fit the task:

Role starts the run	What the chain does	$142,000 order
Requester	grows past the requester	placed
Buyer	grows past the buyer	placed
Director	grows, but was already allowed	placed

Read the last row of the broken table carefully. In broken mode, a director's run also places the order, and that result is correct. But it is correct by accident. The chain did not place the order because the director was allowed to. It placed the order because it places every order. The right outcome and the wrong mechanism can look identical from the outside. That is why a leak like this survives in production. On the happy path, broken and correct give the same answer. You only see the difference when the wrong person starts the run.

What to take from this

Three points hold whatever stack you use.

Root the chain in the human. Authority in an agent run belongs to the person who started it. Every hop is a subset of what that person holds. If your chain does not trace back to a real person's scopes, it has no ceiling.

Intersect, do not grant. A handoff should narrow authority, never size it to the task. The moment a handoff grants what the next step needs, without checking the person above, the chain can grow, and a grown chain is a leak waiting for the wrong caller.

Enforce at the source, not at the end. A check before the final action cannot catch authority that was widened along the way, because widened authority looks correct by the time you check it. Put the enforcement where delegations are minted, so the over-wide scope never enters the chain.

Try it and read the code

The live demo: procurement-floor-demo.vercel.app
The source: github.com/kinde-starter-kits/procurement-floor-demo

Pick a role, write a requisition, and start a run. Watch the delegation chain and the timeline stream as the agents work. Start a run as a buyer and watch the large order get refused at the last hop. Start the same run as a director and watch it go through. The chain shows every scope at every hop, and the record shows every decision.

One note on the hosted demo. The agent graph runs in a Trigger.dev task, and that task needs a worker. A plain web deploy starts a run but cannot finish it on its own, so the hosted demo needs the task deployed to Trigger.dev, or a worker running beside it. To see a full run end to end with no setup, clone the repo and run it locally. The README has the steps.

How to Fix the Confused Deputy Problem in AI Agents

Shola Jegede — Fri, 07 Aug 2026 13:42:11 +0000

An AI agent runs with its own permissions. So it can be tricked into doing something its user is not allowed to do. This is the confused deputy problem. This article shows the failure in a real contract-review agent, then fixes it with one rule: permission intersection, checked at the action.

An intern at a law firm opens a contract review tool. Their account has one permission: read. They cannot flag a clause. They cannot approve one. The tool shows this on screen, next to their name.

The intern asks an AI agent to review a supplier contract. It is a Master Services Agreement from a cloud vendor, 14 clauses long. Normal work. The agent starts.

The agent reads each clause and rates its risk. Clause 3 caps nothing: the customer's liability is uncapped. That is critical. Clause 9 removes the right to join a class action. Also critical. Six more clauses are high risk: automatic renewal, broad indemnification, GDPR duties, HIPAA duties, IP assignment, and a non-compete.

Then the agent signs off. It approves all 14 clauses. It approves both critical ones.

Look at the screen again. The user is an intern. The badge says: Read yes. Flag no. Approve no. The agent just approved a contract with uncapped liability on that person's behalf.

Nobody attacked this system. Nobody stole a token. The intern asked an agent to do its job, and the agent used its own permissions to do something the intern could never do.

This is the confused deputy problem. It is old. AI agents have made it dangerous again.

Every screenshot in this article comes from a live demo. You can run it yourself. The link is at the end.

What the confused deputy problem is

The name comes from computer security. A deputy is a program that acts for someone else. A confused deputy is a program that gets tricked into using its own authority for a caller who does not have that authority.

The shape is always the same:

A program holds a strong permission.
A weaker caller asks the program to do a task.
The program does the task with its own permission.
The caller has now done something they could not do alone.

Security researchers described this decades ago. For years it was a problem for compilers, print servers, and file systems. The deputy was a piece of infrastructure.

Today the deputy is an AI agent. The authority is the power to act inside your product.

An agent is a deputy by design. You give it a task. It acts for you. To be useful it needs permissions. It reads your data, calls your tools, and often changes or approves something. The moment it acts, your application sees the agent's identity and the agent's permissions. The person who asked is no longer part of the decision.

Why AI agents make this worse

Three things turn an old problem into a present danger.

Agents hold broad permissions

A useful agent does many things, so teams give it wide access. A contract review agent can read, flag, and approve, because all three belong to review.

That breadth is the point of the agent. It is also the risk. The agent's permission set is usually the union of every permission any user of the feature might need. It is almost never the permission set of the person who triggered the run.

The human disappears at the moment of action

A user signs in. Your app checks who they are and what they can do. That check is correct, and it happens at the wrong time.

The user then asks the agent to work. The agent gets a machine token and calls your API. That call carries the agent's identity. Your sign-in check told you about a human who is no longer in the request.

Login answers "who are you?". It does not answer "may this action happen?". Those are different questions, asked at different moments.

Agent crews widen the gap

Modern systems rarely use one agent. They use a crew. One agent extracts the clauses. A second rates the risk. A third signs off.

Each hand-off is a place to lose the user's limits. By the time the last agent acts, nothing in the chain remembers that a read-only intern started the job. The final action is several steps away from the person who asked for it.

Now add the stakes. Agents are moving into contracts, finance, healthcare, and operations. These are the exact places with an approval step, a spend limit, or a sign-off. A confused deputy in a chat toy is a joke. A confused deputy that approves uncapped liability is a lawsuit.

The diagram below shows where the user's limit is lost.

under its own identity. The intern's authority stops at the crew, so the action
happens without their permission." width="800" height="69">

The user's limit is lost the moment the agent acts. The agent reaches the protected action under its own authority.

The failure in numbers

Words make this sound theoretical. Numbers do not.

Here is one run of that contract review. A read-only intern is the acting user. The system authorizes on the agent's identity alone.

Measure	Result
Clauses in the contract	14
Approvals attempted	14
Approvals allowed	14
Approvals blocked	0
Privilege escalations	14

These numbers come from the demo's deterministic run. In that run the sign-off agent attempts to approve every clause, like a plausible "auto-approve this contract" agent. That is what makes the confused deputy visible in one screen.

Fourteen privilege escalations in one review. Each one is an action the acting user had no right to take. Two of them approved critical clauses.

The system did not fail. It worked exactly as written. It checked whether the agent could approve, and the agent could. That is the whole bug.

The agent still scores the risk correctly. It labels the uncapped-liability clause CRITICAL and the class-action waiver CRITICAL. Then it approves them anyway, because risk scoring and authorization are different jobs. Scoring tells you a clause is dangerous. Authorization decides whether this user may sign off. Broken mode does the first and skips the second.

Why the obvious fixes do not work

Teams meet this problem and reach for three fixes. Each one feels right. Each one fails. The failures are useful, because they point at the answer.

"Give the agent a role"

The idea: create a role for the agent and set its permissions with care.

This gives the agent one ceiling. That ceiling is the same for every user the agent serves. A read-only intern and a senior admin trigger the same agent, and the agent acts at its role's level for both.

You can lower the ceiling, but you cannot shape it per user. Lower it enough to stop the intern, and the admin can no longer get work done. Raise it enough for the admin, and the intern can reach the same power. The agent's role says nothing about the person who asked.

"Check permissions at sign-in"

The idea: the app already checks the user at login, so the user is controlled.

Sign-in and action are separate moments. The agent acts later, under a machine identity, in its own request. The sign-in check never sees that request.

This is the security equivalent of checking a ticket at the front gate and leaving every internal door unlocked.

"Trust the agent's own scopes"

The idea: the agent's token has scopes, so let the token decide.

This one is the most dangerous, because it looks like real authorization. There is a token. There are scopes. There is a check that can fail.

The problem is what the check computes. The agent's scopes describe the agent's authority. When the agent's token alone decides, your effective permission is the union of the agent's power and the user's request. Union is the wrong operation. It hands the caller everything the agent holds.

Each failed fix makes the same mistake in a different place. Each one checks the user or the agent, never both, at the moment that counts.

The principle that fixes it

Name the mistake and the rule writes itself.

An agent must never exceed the permissions of the person it acts for.

State it as set logic, because that is what it is. The agent's effective permission for an action is the intersection of two sets: what the user may do, and what the agent may do.

Not the union. The intersection.

Read that against the three failures:

A role gives one ceiling. Intersection gives a ceiling per user.
A login check guards the wrong moment. Intersection guards the action.
The agent's scopes alone give the union. Intersection gives the smaller of the two.

One part remains, and the failed fixes all miss it. The check runs at the action, on every action. The agent approves a clause, so you check user ∩ agent, right there, before the approval lands. The next clause runs the check again. Fourteen clauses, fourteen checks.

That is permission intersection. The idea is small and it closes the hole cleanly. An intern with read-only access, working through the most powerful agent you own, still cannot approve a clause. Their ceiling holds, because the agent can never exceed it.

Run the same contract again with intersection in place. Same intern. Same agent:

Measure	Result
Clauses in the contract	14
Approvals attempted	14
Approvals allowed	0
Approvals blocked	14
Privilege escalations	0

Same agent. Same contract. Same user. One rule changed.

What intersection means in practice

Two sets, one operation.

The user's set. What this person may do, right now, in this organization. For our intern: contracts:read.
The agent's set. What the agent may do at all. For our contract crew: contracts:read, clauses:flag, clauses:approve.

The agent's effective permission for one action is the overlap:

user ∩ agent
{contracts:read} ∩ {contracts:read, clauses:flag, clauses:approve}
= {contracts:read}

The agent may read. It may not flag. It may not approve. The powerful agent, acting for a read-only user, becomes a read-only agent.

Change the user and the answer changes with it:

Acting user	User's permissions	Effective permission for the agent
Intern	read	read
Analyst	read, flag	read, flag
Admin	read, flag, approve	read, flag, approve

One agent. Three ceilings. The agent does not change. The person it acts for changes, so its power changes.

This is why intersection beats the three fixes above. A role gives the agent a fixed ceiling. Intersection gives it a ceiling that moves with the user.

contracts:read, clauses:flag, clauses:approve. The effective permission is the
overlap, contracts:read. clauses:approve sits outside it, so the agent cannot
approve for this user." width="800" height="119">

The agent gets the overlap, never the union. clauses:approve sits outside the overlap, so the agent cannot approve for this user.

The parts you need

Five parts. Each one is small. The value comes from putting them in the right places.

1. A real user identity, with live permissions

Your identity provider already knows who the user is and what they may do. That is the ceiling. Read it from the provider at the time of the run, not from a copy in your database and not from a list in your code. A permission that changed this morning must apply this afternoon.

2. A real agent identity

The agent gets its own machine credentials and its own token. This matters for a reason people miss: the agent needs an identity so you can limit it, and so every action it takes has a name attached in your logs.

Two machine identities are usually correct here, not one:

The agent's identity. The crew uses this to call your API. It is the "who is this caller" credential.
A management identity. Your server uses this to ask the identity provider what a given user may do. It is the "what may this person do" credential.

They are separate because they do different jobs, and because the agent must never hold the power to read every user's permissions.

3. The acting user, carried on every request

This is the part most systems drop. When the agent calls your API, the request must say who it acts for, not only who it is.

In practice that is one field: the user's stable identifier, sent with each call. Your server reads it, and never lets the client choose it freely. Derive it from the session that started the run.

4. One authorization check at the action boundary

Not at login. Not at the start of the run. At the action.

The agent asks to approve clause 3. Before that approval lands, your server asks one question: may this agent, acting for this user, take this action? One function, one answer.

5. A record of every decision

Every allow and every deny writes one row: what was decided, which action, why, which ceiling applied, and an identifier that ties the row to the request. This is what turns "trust us" into "check for yourself".

The check, step by step

Here is the full path of one approval, from the agent's request to the answer.

Step 1. The agent authenticates. The crew requests a token with its own machine credentials, for your API's audience. This token says "I am the contract review crew". It says nothing about any user.

Step 2. The agent calls your API and names the user. The request carries the token and the acting user's identifier. In the demo that is a header, X-Acting-Subject. Your endpoint reads both.

Step 3. Your server verifies the caller. The component checks the token's signature against the provider's keys, checks the audience, and resolves the caller to a registered agent. A bad token stops here.

Step 4. Your server resolves the user's ceiling. Using the management identity, it asks the identity provider what this user may do in this organization. The answer for our intern is one permission: contracts:read. The server attaches this ceiling to the run, so every later action in the run uses it.

Step 5. Your server authorizes the action. This is the whole fix, in one call:

// At the action boundary, not at login.
const { decision } = await agentAuth.authorize(ctx, token, {
  instanceId,                    // this run, tied to the acting user
  action: 'clauses:approve',     // the action being attempted
  enforceTokenScopes: true       // fold the live token scopes in too
});

if (!decision.allowed) {
  return deny(decision.reason, decision.correlationId);
}

Inside, the component computes the overlap:

agent's registered scopes
  ∩ the acting user's ceiling
  ∩ the live token's scopes

Three sets, not two. The third one matters. If you shrink the agent's credentials in your provider, the next token carries less, and the decision tightens at once. You do not redeploy anything.

Step 6a. Allowed. The action runs. One audit row records the allow.

Step 6b. Denied. The action does not run. The endpoint answers with a machine-readable reason, and one audit row records the deny:

{
  "error": "authorization_denied",
  "reason": "insufficient_scope",
  "requiredScopes": ["clauses:approve"],
  "correlationId": "1c3f3d4e-1c6a-4810-958a-ab125d4fc027"
}

Read that response. It does not say "something went wrong". It says which action was refused, which permission was missing, and gives an identifier you can look up. A support engineer can answer "why did this fail?" without a debugger.

Step 7. Repeat. The next clause runs the same check. Fourteen clauses, fourteen decisions, fourteen rows.

The audit trail

Enforcement stops the bad action. The audit trail is how anyone else believes you.

Each decision writes one row. The useful fields are these:

Field	What it holds	Why it matters
decision	allow or deny	The outcome
action	`clauses:approve`	What was attempted
reason	`insufficient_scope`	Why it was refused
ceiling	`contracts:read`	The user's permissions at that moment
correlationId	a unique identifier	Ties the row to the request

The correlationId is the part to get right. The same value appears in the denial your API returned and in the audit row it wrote. Someone reviewing an incident can hold both in one hand: here is the response the caller saw, and here is the decision that produced it.

That is the difference between a log and a record. A log says something happened. A record answers who authorized this, under whose permissions, and when.

Enterprises buying agent products ask this question early, and they do not accept a demo as the answer. Write the row for every decision, allow and deny, and the question is already answered.

The security details that decide whether this holds

The check is simple. These details keep it honest under pressure.

The server decides how strict the check is

Never let the caller choose its own enforcement. If an agent can send a flag that relaxes the check, the check is decoration.

In the demo the mode is a server-side setting. The agent's request cannot select it. The endpoint reads the mode from the deployment, records it on the run, and ignores anything the client sends about it.

Fail closed

Missing configuration must deny, not allow. If the component starts without the settings it needs to verify a token, it refuses to run. A system that opens up when it is misconfigured will eventually be misconfigured in production.

Check the audience

A token issued for another API in the same tenant must not work on yours. Without an audience check, any valid token from your provider can be replayed against your endpoints. With one, a token minted for a different service is refused.

Keep administrative functions internal

Registering an agent, issuing a ceiling, revoking access, changing policy: these are not user actions. They must not sit on a public surface, whatever the caller's permissions. In the demo they are internal-only functions, reachable by the server and the admin tooling, never by a request from outside.

Expose one authorization surface

Give your application one function to call: authorize(). Do not expose the raw permission lookup underneath it.

The reason is human, not technical. If a developer can call the lower-level check, one of them eventually will, in a hurry, without the caller binding or the audit row. One public surface means every path through your code takes the same path through your rules.

Building it in practice

Here is one working shape. Your stack will differ. The five parts will not.

The application. A web app with a backend that owns the protected actions. In the demo this is Next.js with Convex. The authorization component, kinde-convex-agent-auth, is mounted inside the backend, so the check runs next to the data it protects.

The agent. A Python service built with CrewAI. Three agents work in order: a Clause Extractor reads the document, a Risk Flagger rates each clause, and a Sign-off Agent approves the ones that pass. The crew authenticates with its own machine credentials and calls the app over HTTP. It never touches the database and never calls the authorization component itself.

That separation is deliberate. The agent asks. The application decides.

The demo also ships a deterministic version of the same review that needs no model key. It drives the same endpoints and streams the same events, and its sign-off step attempts to approve every clause. Every screenshot and every number in this article comes from that deterministic run, so the results are exact and repeatable.

The context store. The app embeds clause text into Weaviate, with one tenant per organization, so a search for one customer's clauses cannot return another customer's. Vector storage needs tenancy too. An agent that can retrieve across tenants is its own kind of leak.

The identity provider. Kinde holds the human users, their roles, and their permissions. It also holds the two machine identities: the crew's, and the management identity the server uses to read a user's permissions.

The model. The crew runs against a configurable model. Keep the model name in configuration, not in your source. Models change names and versions often, and nothing in this design depends on which one you use.

The two modes

The demo carries both behaviors, switchable on the server:

Broken. The endpoint authorizes on the agent's identity alone. This is the confused deputy, kept as a real, working code path.
Intersection. The endpoint calls authorize() and enforces user ∩ agent ∩ token.

Keeping the broken path is useful, and it is honest. The failure is not a story about what might happen. It is a code path you can run.

The code that matters

Three shapes carry the whole design.

Mount the component inside your backend, so the check lives with the data. The component declares the provider settings it needs, so the app declares them too and threads them through on mount:

const app = defineApp({
  env: {
    KINDE_DOMAIN: v.string(),
    KINDE_AUDIENCE: v.optional(v.string()),
    DELEGATION_SIGNING_SECRET: v.string()
  }
});

app.use(agentAuth, {
  env: {
    KINDE_DOMAIN: app.env.KINDE_DOMAIN,
    KINDE_AUDIENCE: app.env.KINDE_AUDIENCE,
    DELEGATION_SIGNING_SECRET: app.env.DELEGATION_SIGNING_SECRET
  }
});

Carry the acting user on every agent request. The agent sends its own token, and the identifier of the person it acts for:

headers = {
    "Authorization": f"Bearer {crew_token}",
    "X-Acting-Subject": acting_user_id,
}

Check at the action boundary. This is the line that closes the hole:

const { decision } = await agentAuth.authorize(ctx, token, {
  instanceId,
  action: 'clauses:approve',
  enforceTokenScopes: true
});

if (!decision.allowed) {
  return json({
    error: 'authorization_denied',
    reason: decision.reason,
    requiredScopes: decision.requiredScopes,
    correlationId: decision.correlationId
  }, 403);
}

Note what is absent. There is no list of roles in the endpoint. There is no if (user.isAdmin). The endpoint states the action it is about to take and asks one question. The rules live with your permissions, not scattered through your handlers.

endpoint. The server verifies the caller, resolves the user's ceiling from Kinde,
then calls authorize() for user ∩ agent ∩ token. The decision branches to allow
(action runs) or deny (403 with reason and correlationId). Both write an audit
row." width="800" height="1288">

One decision point, two outcomes, always a record.

Broken and fixed, side by side

The same contract, the same agent, the same three users. Only the enforcement rule changes.

Broken mode

Acting user	Approvals attempted	Approved	Privilege escalations
Intern (read)	14	14	14
Analyst (read, flag)	14	14	14
Admin (read, flag, approve)	14	14	0

Every user gets the same result, because the user was never part of the decision. The intern and the analyst each escalate 14 times. Two of those approvals cover critical clauses: uncapped liability, and a class-action waiver.

The admin's row is worth a second look. The outcome is correct, and it is correct by accident. Broken mode did not check the admin's permissions either. It allowed the approval because the agent could approve. If that admin lost the approve permission this morning, broken mode would still approve.

Intersection mode

Acting user	Approvals attempted	Approved	Blocked
Intern (read)	14	0	14
Analyst (read, flag)	14	0	14
Admin (read, flag, approve)	14	14	0

Three users, three different outcomes, from one agent.

The intern is refused every approval. So is the analyst, who may flag but not approve, and whose flags still go through. The admin's approvals land, and now they land because the admin holds the permission, checked at the moment of the action.

Each denial carries the same three facts: reason insufficient_scope, the missing permission clauses:approve, and a correlationId that matches its audit row.

The receipts echo the finding. The demo sorts the clause table by risk, so the critical rows sit at the top. In broken mode, each one shows APPROVED, decided by the intern's own identifier.

How this maps to your app

Your stack is probably not this stack. That does not matter. Three things carry over to any system where an agent acts for a person.

1. Check at the action, not at the door

Find the places in your code where an agent causes something to happen: an approval, a payment, a delete, a write to another system. Those are your action boundaries. Put the authorization check there.

A useful test: if the only permission check in a request path happens before the agent gets involved, you have a confused deputy waiting to be found.

2. Enforce user ∩ agent

Give the agent its own identity, then hold it to the smaller of two ceilings: its own, and the acting user's.

This means every agent request must name the person it acts for, and that name must come from your server, not from the client. If the caller can choose whose authority it borrows, you have built a different vulnerability.

3. Keep the receipt

Write one record per decision, allow and deny, with the action, the reason, the ceiling that applied, and an identifier shared with the response.

You need it three times: when a customer asks why something failed, when a security reviewer asks what your agents can do, and when you ship agents to a regulated buyer who will not take your word for it.

None of the three name a vendor. Kinde makes them straightforward, because the ceiling, the machine identities, and the audit trail already exist there. The pattern is the point. Build it with what you have.

What this is really about

Agent products are moving from answering to acting. An assistant that drafts an email is a convenience. An agent that sends the email, approves the invoice, or signs off the clause is a deputy with authority.

Once agents act, delegation becomes the security question of the product. Not "is this agent authenticated?", but "on whose behalf, and within whose limits?".

That question gets harder from here. Agents call other agents. A crew hands work down a chain. Each hand-off is a chance for authority to grow when it should only ever shrink. Intersection at the action boundary is the foundation that makes the harder cases work, because it fixes the property you need at every hop: the deputy never exceeds the person it acts for.

The fix itself stays small. Name the user on the request. Ask one question where the agent acts. Keep the answer.

An agent must never exceed the permissions of the person it acts for.

An intern with read-only access, working through the most capable agent you own, should not be able to approve a contract. In broken mode they approved fourteen clauses, including two that no reviewer should wave through. In intersection mode they approved none, and the record shows exactly why.

Same agent. Same contract. Same user. One rule.

Try it and read the code

The live demo: kinde-confused-deputy.vercel.app
The source: github.com/kinde-starter-kits/contract-intelligence-demo
The authorization component: kinde-convex-agent-auth

Pick a role, choose broken or intersection, and run the review. The timeline shows every step, and the records show every decision.

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:kinde-oss/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/kinde-oss/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="799" 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.

DEV Community: Shola Jegede

How to Let an OpenAI Agent Act in a User's GitHub Without Storing API Keys

Table of Contents

What You'll Build

Prerequisites

How the Demo Is Structured

Why a Stored Key Fails

The Connected Apps Primitive

How to Connect a User's GitHub

How to Build the Broker

How to Model the Data

How to Decide the Storage Mode

How to Build the Agent Loop

Two Revocation Levers, and One Is a Decoy

The Central Finding: Revocation Reaches the Connection, Not the Token

The Two Modes, Side by Side

How to Keep Least Privilege

What the Operator Controls

How to Harden It for Production

How to Prove the Tests Can Fail

Honest Limitations

What This Design Costs

What You've Built, and Where to Take It

Wrapping Up

Resources

Source code

Core documentation

Context for the problem

Build tooling

How to Require Step-Up Auth Before a Claude Agent's Destructive Actions With Kinde

Table of contents

Why blanket consent fails

The demo and its three services

The freshness primitive: auth_time

The discovery document does not mention it

Why iat and exp cannot stand in

Building the seam

Step 1: verify the access token

Step 2: read the registry, and refuse when you cannot

Step 3: read freshness from the ID token, bound by subject

Step 4: decide

The challenge response

The tool registry

Windows do real work

The Claude agent loop

Three responses, handled differently

Good manners are not enforcement

The round trip

The resume re-presents, it does not re-plan

The resume route decides nothing

The two negative cases

Case 1: a refresh does not release the action

Case 2: re-authentication does not bless the session

The release

Blanket against step-up

The number that matters

Production hardening

The audit row that vanished

The success that reported as a failure

The state that lied

Honest limitations

It proves when, not how

The audit spool is a floor

Proving the check can fail

How to map this to your app

Resources

How to Give Every Kimi K3 Agent Its Own Tenant Identity With Kinde Organizations

Table of Contents

What You'll Build

Prerequisites

What a Swarm Changes

How the Demo Is Structured

The two modes

Why you orchestrate the swarm yourself

Why One Shared Identity Is the Whole Problem

How Tenant Isolation Works With Kinde Organizations

How to Model Each Tenant as a Kinde Organization

How to Give Each Agent Role Its Own M2M Application

How to Mint an Org-Scoped Token Inside Each Agent

Check the claim before you build the rest