DEV Community: Shola Jegede

How to Stop an AI Agent That Lies About Its Own Spending

Shola Jegede — Wed, 23 Sep 2026 00:54:29 +0000

In September 2026, Mandiant described a failure in its AI Risk and Resilience report, drawing on data from Google's Threat Intelligence Group. An accounting agent entered a runaway loop where it fired more than 15,000 API calls, burning about $50,000 in cloud spend in under an hour, and yet no attacker had touched it.

This failure points at a specific gap that we will discuss in this article. A token issued to an AI agent proves who issued it, but tt does not say who owns the spending it causes, or how much that owner has left to spend.

To reproduce the failure mode described by Mandiant, we will be building a demo application with two products: Kinde, which is an identity provider that issues signed access tokens for machine callers and can attach custom data to them, and Convex, a backend platform with a reactive database that runs the server that checks every call.

The map, in one screen

In our demo, three agents will call the same Convex route. What changes is which claims their Kinde token carries, and whether the server checks those claims against its own ledger or against the request itself.

One agent's token carries no owner and no spend limit. The server treats it as unattributed and uncapped. A second agent's token carries both claims. The server reads them from the verified token and checks them against a running total it keeps in Convex. A third agent reuses the second agent's own token. The server still verifies the signature, but its enforcement route reads the spend total from the request instead of the ledger.

During the test, both agents made the same calls, one at a time, against a real Kinde tenant and a real Convex deployment, each call priced at $2.50. The unmetered agent made 8 calls. All 8 went through, for $20 spent, with no ceiling in sight. The metered agent made the same calls with a $10 limit set on its token. The first 4 went through, taking it to exactly $10. The server denied every call after that with a 402.

The live dashboard mid-run: the unmetered agent's total climbing past $20, the metered agent capped at $10, and the naive control still reporting $0 claimed spend.

Why doesn't a valid signature stop overspending?

A JSON Web Token, or JWT, is a signed, verifiable claim. Kinde signs every access token it issues. Any server that trusts Kinde can check that signature without calling Kinde back.

A valid signature goes on to answer one question: did Kinde issue this token, and has it expired? It does not answer the second question that we have for this test: has this agent already spent its budget? And that second question needs its own check, written into the server, on top of signature verification.

const { payload } = await jwtVerify(token, getJwks(), {
  issuer: requiredEnv("KINDE_ISSUER"),
  audience: requiredEnv("KINDE_M2M_AUDIENCE"),
});
const mode = modeForClientId(payload.azp as string | undefined);
const owner = readProperty(payload.application_properties, "agent_owner") ?? "unattributed";
const spendLimitRaw = readProperty(payload.application_properties, "agent_spend_limit_usd");

jwtVerify throws if the signature is wrong or the token expired. Everything after that line is this build's own code, not Kinde's. It reads two claims off the verified token: who owns this call, and what that owner's limit is.

How does Kinde attach an owner and a limit to a token?

Kinde stores custom data on an M2M application as Properties. A Property has one of three types: single line text, multi line text, or boolean. There is no number type, so a spend limit gets stored as text and parsed with Number() on the server.

A Property must be scoped to Applications to attach to an M2M app. Its Private toggle must be off, or it never appears in a token. From there, the application's Properties tab sets a value, and its Tokens tab, under Token customization, turns that Property on for the M2M token.

The unmetered application's Properties tab: empty, so the server treats every call from it as unattributed and uncapped.

The metered application's Token customization tab: both the owner and spend-limit properties switched on, so they ride along in every access token this app issues.

A token that carries these claims does not carry them as plain values. Each one arrives wrapped:

{ "agent_owner": { "v": "finance-ops" }, "agent_spend_limit_usd": { "v": "10.00" } }

The server has to read .v off each claim, not the claim itself.

What happens when the server trusts the caller instead of the ledger?

The metered agent's enforcement route reads its spend total from Convex. While, a second route in this build, built only to test the failure mode, reads the spend total from a claimedSpend query parameter on the request instead.

Both routes check the same math against the same kind of token. Only the source of the number changes.

// The metered agent's route, checked against the ledger Convex itself wrote
allowed = currentTotal + args.costUsd <= args.spendLimitUsd;

// The naive route, checked against what the caller claims
allowed = args.claimedSpendUsd + args.costUsd <= args.spendLimitUsd;

The test for the naive route fired 20 calls at it with the metered agent's own token, each one claiming $0 already spent. Each call cost $2.50. The ledger was reset to zero before the run, so the result could not be explained by leftover balance from an earlier session.

The naive route trusts the number in the request. The metered route reads the number it wrote itself.

All 20 calls returned 200. The claimed spend stayed $0.00 the whole time. Real spend, tracked in the background by the same ledger the metered route uses, reached $50.00 against the agent's own $10.00 limit.

A clean result here could lie two ways. If the route never wrote to the ledger at all, a $0 claimed-spend result would only mean nothing got recorded, not that the check passed. If the test forgot to reset the ledger before the run, an early denial could look like the limit working when it was really an old balance carried over. This build hit exactly that second bug once. An early version of the metered agent's own proof script reused a ledger balance left over from a previous run, and the agent looked capped from call one, before any of the fix under test had run. Resetting the ledger before every run fixed it.

Does concurrency break the count?

The metered agent's ledger check runs inside a Convex mutation. Convex queues mutations and runs them one at a time, even when many calls arrive at once. That queuing should keep the total correct under concurrent load. It says nothing about which specific calls get to be part of that total.

The concurrency test settled that directly. It fired 20 calls at the real, ledger-enforced route at the same instant, using the same $10 limit and $2.50 cost as the sequential test. The math says exactly 4 calls should be allowed, since 4 times $2.50 is $10.

Exactly 4 calls were allowed. The count was correct on every run.

The 4 calls that won were not the first 4 to arrive. They were calls 20, 7, 5, and 19, in that order, based on the order Convex actually processed them in. If a system assumed a correct total also meant first-come-first-served fairness, this build would have proven that assumption wrong. Convex's mutation queue guarantees the total. It does not guarantee arrival order.

Limitations

This build ran on one Convex deployment. It did not test enforcement split across multiple deployments or regions.

Kinde stores the spend limit as text, not a number. The server parses it before comparing it, and a malformed value would need its own check. However, this build assumes an operator sets the Property correctly.

The mutation that resets a ledger before each proof run exists only for testing. No production request path in this build calls it.

The naive route exists only inside this demo. Kinde did not cause it, and nothing about Kinde's tokens encourages it. This build's own server code chose to trust a claimed number instead of its own ledger, on purpose, to show what that choice costs.

The concurrency test fired 20 calls at once. It did not test hundreds or thousands of simultaneous calls, or calls arriving across more than one server instance.

Where this leaves things

A signed token proves Kinde issued it. It does not prove the number attached to a call is true. The only number a server can trust is the one it wrote itself, in its own ledger, after its own check. Everything else is something the caller said.

FAQ

What is the difference between the unmetered and metered agent in this build?
The unmetered agent's token carries no owner or spend-limit claim, so the server treats every call as unattributed and uncapped. The metered agent's token carries both claims, and the server checks them against a running total it keeps for that owner in Convex.

Why does the naive agent's token still pass signature verification if it is lying about its spend?
A JWT's signature only proves Kinde issued the token and it has not expired. It says nothing about the rest of the request. The naive route reads a claimed spend value from a query parameter the caller controls. Signature verification has no way to catch that, because checking a claimed dollar amount is not what a signature check does.

Why store the spend limit as a Kinde Property instead of a custom claim somewhere else?
A Kinde Property attaches directly to an M2M application. Token customization can include it in every token that application issues. No separate lookup is needed to find which agent owns which limit. The tradeoff is Kinde's Property types, which store text, not numbers, so the server parses the value before comparing it.

What happens if two calls arrive at the same instant?
Convex queues mutations and runs them one at a time. Both calls still get a correct answer: whichever one Convex processes first sees the lower ledger total and may be allowed, and the other sees the updated total and may be denied. The total stays correct. Which specific call wins is not guaranteed to match the order the calls arrived in.

Does this pattern work with an identity provider other than Kinde, or a backend other than Convex?
Yes. Any provider that lets an application attach custom, scoped claims to an M2M token can take Kinde's place here. Any backend that runs writes safely under concurrent load, keeps a database, and can verify a JWT can take Convex's place.

Why not just rate-limit each agent to a fixed number of calls per minute instead of tracking total spend?
A call-count limit says nothing about cost. One agent's calls might cost $0.10 each. Another's might cost $4.00 each. A spend ledger caps what actually matters: money spent, not requests made.

Reproduce it

Set up two Kinde M2M applications. Give one no Properties. Give the other an agent_owner and an agent_spend_limit_usd Property, both turned on under Token customization.
Set KINDE_ISSUER, KINDE_M2M_AUDIENCE, and each application's client ID and secret on the Convex deployment itself with npx convex env set. Convex's HTTP actions read the deployment's own environment, not .env.local.
Run npm run prove:spend-cap to see the unmetered and metered agents run their sequential calls.
Run npm run prove:naive-bypass to see the claimed-spend route accept 20 calls it should have denied after 4.
Run npm run prove:concurrency to fire 20 calls at the real, ledger-enforced route at the same instant.

Full source: github.com/sholajegede/agent-token-ownership-demo

Every number here came from three real scripts against a real Kinde tenant and a real Convex deployment. Clone the repo and run them against your own tenant. If your own naive route somehow keeps real spend under the limit anyway, or your own concurrency test lets through more calls than the math allows, tell me why in the comments.

How to Stop a Leaked AI Agent Key From Still Working With Kinde Access Tokens

Shola Jegede — Sat, 19 Sep 2026 02:20:21 +0000

In September 2026, VentureBeat reported that AI agents had used exposed credentials to breach 395 organizations. The report made a simple point: identity systems still treat an agent's credential the way they treat a human's password. Nobody expects a human to type a password every few minutes, so nobody had built agent credentials to expire that fast either. And this was a gap the attackers saw and used. A separate breach at Hugging Face traced back to the same failure: an agent held a credential that outlived the task it was issued for.

Most AI agents get one machine-to-machine (M2M) access token at start-up and keep it for the life of the process. If that token ends up in a log file, a support ticket, or a copied environment variable, it stays valid for however long its issuer configured it. For most identity providers, that is somewhere between one hour and one day.

To try to solve this problem, I built two versions of the same agent against Kinde, an identity provider that issues M2M access tokens and verifies every call against them. Kinde also lets you set, per application, how long an access token lives before it expires. One agent in my build takes Kinde's default and never checks it again. The other agent treats its token as something with a short shelf life, and rebuilds it before that shelf life runs out.

Then I'm going to try to steal both tokens and reuse them again.

Why the leaked token still works

An M2M credential in Kinde has two parts: a client ID and a client secret, and an access token that Kinde issues when an app presents that ID and secret. The access token is what the app actually sends on every API call. Kinde signs it, and any server that trusts Kinde can verify that signature without calling Kinde back.

The client ID and secret rarely change. Most teams set them once, in an environment variable, and leave them alone. The access token is supposed to be different: Kinde gives it a lifetime, after which it stops working no matter who holds it.

The problem is what an agent's code does with that access token after Kinde hands it over. A static agent fetches one token when it starts, stores it in memory, and reuses it for every call until the process restarts. If that process runs for hours or days, so does the token. If someone copies the token during that time, they hold something that is still good.

A rotating agent does the opposite. It checks the token's age before every call. And before the token gets close to expiring, the agent throws it away and asks Kinde for a new one. A copy of that token, made at any point in its short life, stops working within minutes.

Both agents get their tokens the same way: a client-credentials grant. The agent sends its client ID and client secret directly to Kinde's token endpoint. There is no human and no browser involved in this process. Kinde sends back a signed access token. This is the standard OAuth flow for service-to-service calls, and it is the same flow whether the token that comes back lives for two minutes or two days. The grant itself does not decide how long the token is good for. The application's settings in Kinde do.

The enforcement seam

Both agents in this build call the same API, and that API runs the same check on every request, with no branch for which agent is calling.

sequenceDiagram
    participant Agent as Agent (static or rotating)
    participant Kinde
    participant API as Records API (Convex)

    Agent->>Kinde: client_credentials grant
    Kinde-->>Agent: access_token (24h or 120s expiry)
    Agent->>API: GET /api/records?action=... (Bearer token)
    API->>Kinde: verify signature via JWKS
    API-->>Agent: 200 + data, or 401 if expired/invalid

    Note over Agent,API: Later, an attacker replays a captured token directly
    Agent->>API: same token, no agent involved
    API-->>Agent: static: 200 (still valid) / rotating: 401 (expired)

The API is a single Convex function. It reads the bearer token from the request, checks its signature against Kinde's public key set (JWKS), and checks that the token has not expired:

const { payload } = await jwtVerify(token, getJwks(), {
  issuer: requiredEnv("KINDE_ISSUER"),
  audience: requiredEnv("KINDE_M2M_AUDIENCE"),
});
const mode = modeForClientId(payload.azp as string | undefined);
if (!mode) return await deny(403, "token not issued to a known agent client");

The jwtVerify call, from the jose library, throws the moment a token's signature is wrong or its exp claim has passed. That single check is what turns a Kinde-configured expiry into an actual rejection. Nothing about this function knows or cares which agent sent the request; it treats every token the same way, and the token's own expiry decides the outcome.

The only difference between the two agents lives in Kinde's dashboard, not in this code. The static agent's Kinde application keeps the default access token expiry: 86,400 seconds, one full day. The rotating agent's application is set to 120 seconds. Change that one number, and the identical verification code above starts rejecting tokens on a different schedule, with no redeploy of its own.

Two credential managers, one verification function

The static agent's credential manager fetches a token once and holds it:

let staticToken: CachedToken | null = null;
export async function getStaticCredential(): Promise<CachedToken> {
  if (staticToken) return staticToken;
  staticToken = await fetchM2MToken(
    env("STATIC_AGENT_CLIENT_ID"),
    env("STATIC_AGENT_CLIENT_SECRET"),
  );
  return staticToken;
}

The rotating agent's credential manager checks the token's age before every use, with a 15-second safety margin, and fetches a new one if the old one is close to expiring:

const ROTATION_SAFETY_MARGIN_MS = 15_000;
let rotatingToken: CachedToken | null = null;
export async function getRotatingCredential(): Promise<CachedToken> {
  const now = Date.now();
  if (rotatingToken && now < rotatingToken.expiresAt - ROTATION_SAFETY_MARGIN_MS) {
    return rotatingToken;
  }
  rotatingToken = await fetchM2MToken(
    env("ROTATING_AGENT_CLIENT_ID"),
    env("ROTATING_AGENT_CLIENT_SECRET"),
  );
  return rotatingToken;
}

Neither function knows about the other, or what the API on the other end will do with the token. The only thing that changes the outcome is how long Kinde told each token to live, and whether the calling code respects that.

A third file in the build, a closed action registry, lists the only three calls either agent may make: list_records, read_record, and export_records. The API rejects any other action before it even looks at the token. This keeps the demo's scope narrow: the test here is about token lifetime, not about which actions an agent should be allowed to take.

The bug I found during hardening

During a review of the API's verification code, a bug turned up. When a request carried no token, or a token from an application the API did not recognize, the logging code defaulted that request's log entry to mode: "static". An anonymous or malformed request would then show up in the dashboard as if the static agent had made it.

This did not affect the proof numbers below, since every call in this build came from one of the two known agents. It got fixed before the proof ran, though: unattributed requests now log as mode: "unknown", a separate value from "static" and "rotating".

Live proof

With both Kinde applications configured (24 hours for static, 120 seconds for rotating), the proof works in four steps. First, each agent asks Kinde for a token. Second, both tokens are captured at the same instant, the way a log scraper or a support-ticket screenshot would capture them. Third, the script waits past the rotating agent's 120-second window. Fourth, both captured tokens get replayed, unmodified, straight against the API, without going through either agent's own code.

Static Agent's app, at the default 86,400-second expiry:

Rotating Agent's app, set to 120 seconds:

The live dashboard, built with Convex, shows both agents' history in real time as each call happens:

The replay produced these results:

Agent	Token expiry	Replay result	Status	Latency
Static	24h (default)	still works	200	1353ms
Rotating	120s	dead	401	938ms

A stolen token's usable window: a day vs two minutes

The static agent's leaked token authenticated successfully more than two minutes after it was captured, using the exact same replay the rotating agent's token failed. It will keep authenticating for the rest of its 24-hour life, because nothing in this build, or in most production setups, checks whether a token has been copied. Kinde's own JWT verification only checks whether a token is signed correctly and has not expired. It has no way to know the token in front of it is a copy.

The rotating agent's leaked token failed after 120 seconds, the same limit set on its Kinde application. Whoever captured it had, at most, two minutes to use it before Kinde's own signature check started returning 401 on every attempt.

The gap between those two numbers, a day against two minutes, is the entire value of short-lived credentials. Nothing about the attack changes. Nothing about the API's verification code changes. Only the answer to "how long is a copy of this token worth anything" changes, and that answer comes from one number set on one screen in Kinde's dashboard.

What I think about all of this

Kinde already gives every M2M application a token with an expiry, and most teams never touch that setting. I don't think that is a Kinde problem. Most agent code never checks the expiry either; it just holds whatever Kinde handed back at start-up. Short-lived credentials are not a feature you have to add. The primitive already exists. What is missing is code that treats the expiry as real, instead of code that mints a token once and assumes it will always still be good.

The fix in this build took two changes: setting one number in Kinde's dashboard, and writing a credential manager that checks the clock before it checks a cache. Neither change touched the API's verification logic at all.

I would argue the harder habit to build is not the code. It is remembering that a credential an agent holds in memory is a credential that can leave that memory. Developers on Hacker News asked whether they would trust an agent with an API key at all. Most kept landing on the same answer: give the agent a temporary, narrowly scoped credential, issued through something that logs when it was requested. Not a long-lived key sitting in an environment variable. A short access token from an identity provider that already tracks every issuance is a plain way to get that, without building a separate credential broker.

Limitations

Kinde documents rotating an M2M application's client secret as a manual action, triggered from the dashboard or the Management API, not something Kinde does on a schedule. This build rotates the access token, which Kinde issues fresh on every client-credentials request. That is the layer that matters for a leaked-token scenario, but it is a different mechanism from secret rotation, and the two should not be confused for each other.

120 seconds is a number chosen so this proof runs in a couple of minutes, not a production recommendation. A production window more commonly sits between 5 and 15 minutes, traded off against how often a workload can tolerate a refresh call.

The API's JWT verification returns a generic 401 for every failure case. It does not tell a caller whether their token expired, or whether it came from an application the API does not recognize. That is fine for this demo. A real audit trail would need to tell those cases apart.

Code and sources

Full source: github.com/sholajegede/rotating-credentials-demo

Every number in this article came from a live run against a real Kinde tenant and a real Convex deployment. Clone the repo, run the same proof against your own tenant, and drop your numbers in the comments. If your static agent's leaked token survives longer than 24 hours, or your rotating agent's dies in under 120 seconds, tell me why.

How to Auto-Revoke a Claude Agent's Access When a User Is Offboarded With Kinde Webhooks

Shola Jegede — Thu, 17 Sep 2026 01:36:32 +0000

Imagine this scenario, someone on your team gets offboarded while their AI agent is still mid-task. Nobody remembers the agent is even running. It's just doing what it was told, on behalf of someone who, as of a minute ago, doesn't work at your company or on your team anymore.

Does it stop?

Well, I built a small app to test that scenario, using Kinde to handle sign-in and to hold the record of who's still active. I signed a real user in, handed their agent a task, and while the agent was still working through it, suspended that same user, in Kinde's dashboard, mid-run, to see what the agent would do next.

Unsurprisingly, the agent kept working on the task.

You see, suspending or deleting a person changes how Kinde itself sees that user, but it doesn't touch the access token their agent is already holding, because nothing about a suspension reaches back into a token that was already signed and handed out before it happened. The token still verifies exactly as it did before the suspension, so the agent has no way to know anything changed.

Everything I am going to talk about in this article is about closing that gap, and about what I actually found while doing it: webhook deliveries measured live, a production bug that could have left an offboarded user's record looking active forever, and a hard number for how long an offboarded person's agent keeps acting before anything catches it.

Why a suspended user's token still works

Let's start with what an access token actually is, because the whole gap follows from it. An OAuth access token isn't a receipt you hand back to check against a ledger. It's a signed claim, a small JSON payload with a cryptographic signature attached, and whatever's checking it just verifies that signature against a public key rather than calling home to ask if the token's still good. That's the entire appeal of the design: an API can confirm a token is genuine without a database round trip on every request.

Which means suspending a user in Kinde only changes a row in Kinde's own database. It doesn't reach the token at all, because there's nothing there for it to reach: the token was already handed out, already signed, already valid until whatever expiry it was minted with. Revoking it properly would mean tracking every issued token in a lookup table somewhere, which throws away the entire point of signing one in the first place, or it would mean just waiting for the thing to expire on its own.

I suspended a signed-in test user mid-session, and the app's own check kept reporting that user's access token as valid, seconds after Kinde had already suspended them.

So that gap isn't a bug in Kinde, and it isn't a bug in OAuth either. It's just what a stateless credential is, by design, and the real question is what you build on top of it.

The shape of the fix

Two pieces close the gap. A webhook tells the app when Kinde's view of a user changes, and a check runs before every single agent action, reading the app's own record of that user instead of trusting whatever was true when the session started.

The agent itself is a small Claude Messages API loop, working through a closed set of three tools against a demo set of internal resources: list_resources, read_resource, write_resource. None of what follows is specific to what the agent does. It's specific to the one place every tool call has to pass through before it's allowed to run at all.

Building the seam

First, we start with the registry that defines those three actions, because it's closed by construction rather than by convention. An action that isn't in this table doesn't half-exist somewhere in the code, waiting to be called by accident. It just doesn't exist:

export const ACTION_REGISTRY: Record<ActionName, ActionDefinition> = {
  list_resources: { name: "list_resources", destructive: false, params: {} },
  read_resource: {
    name: "read_resource",
    destructive: false,
    params: { resourceId: { type: "string", required: true } },
  },
  write_resource: {
    name: "write_resource",
    destructive: true,
    params: {
      resourceId: { type: "string", required: true },
      title: { type: "string", required: false },
      body: { type: "string", required: false },
    },
  },
};

Both the tool schema handed to Claude and the enforcement check are built from this same table, so the two can never quietly drift apart from each other the way a schema and a permissions list usually do once someone forgets to update one of them.

Every tool call the model makes passes through a single function, enforceToolCall, which looks up the acting user's current status and hands it to a small, pure decision function underneath it:

export function decideAccess(input: {
  mode: EnforcementMode;
  userStatus: UserStatus;
}): { decision: SeamDecision; reason: SeamReason } {
  if (input.mode === "naive") {
    return { decision: "allow", reason: "naive_mode_no_check" };
  }
  if (input.userStatus === "active") {
    return { decision: "allow", reason: "user_active" };
  }
  if (input.userStatus === "offboarded") {
    return { decision: "refuse", reason: "user_offboarded" };
  }
  return { decision: "refuse", reason: "user_unknown" };
}

Naive mode allows every call without ever looking at that status, which is the vulnerability this whole piece is about, reproduced on purpose so both modes can run side by side against the exact same code and prove the point cleanly. Enforced mode is stricter in a way that matters: it allows exactly one case, a confirmed active user, and refuses everything else, including a status the seam couldn't even resolve because a read to Convex failed. An unknown status doesn't get the benefit of the doubt.

That status comes from a webhook. Kinde sends a signed event on user.updated and user.deleted, the receiver verifies the signature, and then it does one more thing that has nothing to do with the signature at all:

export function isFreshWebhookEvent(
  event: WebhookEvent,
  now: number = Date.now(),
): boolean {
  const eventTime = Date.parse(event.timestamp);
  if (Number.isNaN(eventTime)) return false;
  return Math.abs(now - eventTime) <= MAX_CLOCK_SKEW_MS;
}

A valid signature only proves Kinde signed this payload at some point. It says nothing about when that was, so without this check, a captured event replayed months later would sail straight past signature verification, since the signature itself never expires, and past deduplication too, because dedup only catches an event id it's already seen before. MAX_CLOCK_SKEW_MS is five minutes. Anything older than that gets rejected the same way a forged signature would.

The bug the build actually found

Hardening this receiver turned up a real ordering bug. The first version recorded the webhook's delivery, for deduplication, before it applied the actual effect of marking the user offboarded. That ordering has a quiet failure mode: if the effect write failed right after the delivery had already been logged, a retried webhook would look like a duplicate of one already handled and get skipped. The user would never actually get offboarded, and nothing about the system would ever try again.

The fix took one line of reordering, but it only works because of one property underneath it: the effect, markOffboarded, is idempotent, so running it twice is always safe. That's why it now runs first, unconditionally, ahead of the bookkeeping whose entire job is to stop it from running a third or fourth time. Recording the delivery first and applying the effect second felt like the more natural order to write. It was also the less safe one.

Proving it, live

scripts/e2e-narrative.ts runs one task against one real Kinde test user, twice: once with the seam in naive mode, once enforced, suspending that same user for real, mid-run, both times. Nothing in this script is simulated. It drives a real agent loop, fires a real suspend call at Kinde, and waits on the actual webhook to arrive over a tunnel before it checks what actually happened.

	naive	enforced
actions allowed after offboarding	2	0
where the run stopped	it didn't, ran to completion	step 2, reason `user_offboarded`

The same story shows up in the operator console, so I ran it once more while writing this, offboarding the signed-in user on purpose partway through a task:

Step one lands while the user's still active. The offboard request goes out. Step two refuses, user_offboarded, with a cutoff latency of 2697ms measured from when the offboarding itself landed in the database, not from when the run started. Every one of those decisions lands in an audit log under a shared correlation id, so a run's full timeline can be pulled back up after the fact, not just watched live:

The numbers that matter more than the demo

Across every live webhook delivery in this build, latency ran from 652ms to 2058ms, across suspends, restores, deletes, and role changes alike. That's not instant. Most people assume it is.

The enforcement check itself doesn't belong anywhere in that number. It's one indexed read against Convex, and next to webhook delivery it's close enough to free that it doesn't move the total.

So the more honest way to describe total revocation speed is this: it's webhook delivery latency, plus however long until the agent gets around to its next real action, and that second part isn't a fixed system number at all. An agent moving faster, with no artificial pacing between steps or several tool calls requested in the same turn, gets caught just as fast on its very next call, without any extra mechanism needed to catch it sooner. The floor here is roughly one model round trip, not the enforcement check sitting underneath it.

A webhook can also be missed or delayed, because that's what "best-effort delivery" actually means in practice, so I built a reconciliation sweep on top: a cron job checking every active user's live status directly against Kinde every five minutes. I tested it against a forced scenario: suspended a real user, then manually pushed the app's own record back to active, simulating a webhook that never arrived at all. The cron caught the drift and corrected it on its own, before I ever triggered a manual run.

Here's what I think

"Revocation" is the wrong word for what any of this does, and I think that matters more than it sounds like it should. Nothing here revokes anything. What actually happens is a live check gets bolted on top of a credential that was never revocable to begin with, and I'd rather describe it that way than pretend otherwise, because that's closer to what every system in this space is doing under the hood, whatever the marketing copy on top of it calls it.

I'd also argue this check shouldn't be the thing you bolt on during a hardening pass once the demo already works, which is exactly the order it happened in during this build. The seam existed early on, but the reconciliation backstop and the timestamp check both came later, as production polish, and I think that ordering is backwards for anything that runs unattended. A browser session gets re-validated more or less by accident, on every page load, because there's a human sitting there generating new requests the whole time. An agent loop doesn't get that for free. It holds one credential, validated once at the start, and then it acts on that credential in a loop nobody's watching in real time. If the check isn't built into that loop from the first line, there's no accident later that adds it back in.

The usual objection to this is cost: a database read on every single tool call sounds expensive once an agent's task means dozens of calls instead of one. But this build's own numbers say that objection doesn't hold up, at least not with an indexed lookup like the one here. The check disappears next to webhook latency, and webhook latency itself disappears next to how long a person actually takes to notice someone's gone and go click suspend. The genuinely expensive part of this whole system is the five to fifteen minutes between someone walking out the door and someone else noticing. Nobody optimizes for that number, even though it's the one that actually decides how exposed you are.

What this doesn't solve

The token-still-valid gap from the top of this piece is real, and nothing here closes it. This build works around it, by checking liveness on every call, instead of trying to make the token itself stop working. A system that actually needs the token revoked needs a different mechanism entirely, like short-lived tokens or an introspection endpoint hit on every use, and both of those trade away the exact stateless-verification benefit that made a signed token worth using in the first place.

The reconciliation sweep is a five-minute backstop, not the primary path, and if the webhook's doing its job, the sweep never finds anything to correct.

runs.timeline, runs.get, and the audit queries in this build are also unauthenticated Convex reads. A run id or a correlation id is enough on its own to read that run's whole timeline, which is fine for a single-user demo console and not fine at all for anything with untrusted users in it.

And the action registry here covers exactly three read and write actions on a demo resource. That's enough to prove the pattern holds. It's nowhere near enough to prove the pattern scales to a real authorization model with real permission boundaries between real resources.

Where this leaves the agent

Back to the opening scene: someone gets offboarded, and their agent is mid-task. Whether its next few tool calls go through was never actually a question about the token. The token was always going to keep working right up until it expired on its own, offboarding or not, because that's just what it is. The real question was always whether anything standing between the agent and the action it's about to take bothered to check, right then, whether the person behind it was still around.

Code and sources

The full build, the enforcement seam, the webhook handler, the reconciliation cron, and scripts/e2e-narrative.ts, is on GitHub: sholajegede/offboarding-revocation-demo.

The webhook signing and delivery model comes from Kinde's own webhooks documentation, and the suspend and restore actions used throughout the demo follow Kinde's Management API and its notes on suspending and deleting users.

The reconciliation sweep runs on Convex's cron jobs, and the agent loop follows Anthropic's tool use documentation for the Messages API. Every number in this piece came from runs.timeline and auditLog in that same Convex deployment, read straight off the live runs.

Clone it, wire it up against your own Kinde tenant, and offboard a test user mid-run. Your webhook latency might not match mine, your reconciliation sweep could catch different drift, and that's the point really. Drop your numbers in the comments and let me know what you find.

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.

DEV Community: Shola Jegede

How to Stop an AI Agent That Lies About Its Own Spending

The map, in one screen

Why doesn't a valid signature stop overspending?

How does Kinde attach an owner and a limit to a token?

What happens when the server trusts the caller instead of the ledger?

Does concurrency break the count?

Limitations

Where this leaves things

FAQ

Reproduce it

How to Stop a Leaked AI Agent Key From Still Working With Kinde Access Tokens

Why the leaked token still works

The enforcement seam

Two credential managers, one verification function

The bug I found during hardening

Live proof

A stolen token's usable window: a day vs two minutes

What I think about all of this

Limitations

Code and sources

How to Auto-Revoke a Claude Agent's Access When a User Is Offboarded With Kinde Webhooks

Why a suspended user's token still works

The shape of the fix

Building the seam

The bug the build actually found

Proving it, live

The numbers that matter more than the demo

Here's what I think

What this doesn't solve

Where this leaves the agent

Code and sources

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