Tier Claims in the Token Versus a Lookup per Call

Forget the token-versus-lookup framing for a moment and name the real variable: the maximum interval during which a downgraded caller can still act on the old tier. Every design has one. Write it down before you pick.

If the tier is a token claim, that interval is the token's remaining lifetime. Keycloak's access token lifespan defaults to five minutes, with a realm-wide SSO session idle default of 30 minutes and a session maximum of 10 hours (Skycloak on JWT lifecycle). Short access tokens in the 5 to 15 minute range are the standard advice precisely because expiration is the one revocation mechanism that always works when validation never phones home.

Do the arithmetic. A five-minute access token with a support tier that lets the user finish the current job means the worst case for a downgrade is roughly five minutes, not zero. If your support desk tells a customer "your access changes immediately," and the token lives five minutes, the desk is wrong by up to five minutes. That gap is not a bug to be fixed by wishful thinking; it is a number to be chosen and written into the runbook.

A per-call lookup has a staleness window of one policy cache TTL, which you also choose. Okta's guidance for least privilege asks that policies be re-checked on sensitive actions and revocation paths and that claims be treated as advisory when the underlying permission can change during the token's life (Okta on least privilege for agents).

The hybrid row deserves an example. Suppose a reading agent can call search_repo and read_file. The tier claim gates both, no lookup, so p99 stays flat. The same agent can also call git push, which the policy hard-denies without human review (AI SDK policy tool approvals). No amount of token freshness makes that a safe claim-only decision, because the action is irreversible. The rule that falls out of this: the cheaper the decision is to reverse, the longer you can trust a claim.

Revocation is where token claims earn their bad reputation. A signed token is valid until it expires unless something actively invalidates it, and most stateless verifiers have no such mechanism. That means a downgrade from a paid tier to free does not stop the agent's writes until the token rolls over, and a user removed from a project keeps reading until the same moment.

Three levers shorten this, and you should know which ones you have:

1. Short exp. The blunt instrument, and the one that always works. Five-minute access tokens make the worst case small enough to explain to a customer (Skycloak).
2. Session invalidation. Identity providers can kill server-side sessions and refresh tokens immediately, since refresh tokens are tied to session state while access tokens are not. A not-before push or back-channel logout cuts sessions that are still alive.
3. A freshness check on high-impact calls. This is the only one that makes a downgrade take effect on the next tool call rather than the next token issuance.

Microsoft's guidance frames revocation lag as a containment problem: test the revocation path, including disabling the agent, rotating credentials, invalidating tokens and removing stale permissions, because tokens that persist and shared keys make incident response slow (Microsoft on least privilege for AI agents). If you cannot answer "how do we invalidate a tier in under a minute" in one sentence, the lookup-on-every-call design is the safer starting point.

The subagent case is worse than the user case, because the child may have its own token that the parent cannot revoke. The reported behavior in the Claude Code issue tracker, where subagents spawned via the Task tool ran commands the parent's deny list should have blocked, is an inheritance failure rather than a token lifetime failure (issue 25000). The fix pattern is a token broker that mints child-bound, scope-minimized credentials tied to a delegated approval, not a longer-lived copy of the parent's (Permit).

This is the part the first search result usually skips, and it is the part that decides how angry the incident review gets. A refusal you cannot explain is indistinguishable from a bug, and a reviewer reading a log line that says only "denied" will assume the policy is broken.

A defensible refusal log has, at minimum:

• the decision (deny or requires-approval), with the policy's stated reason, which the AI SDK surfaces back to the model or the approver (AI SDK)
• the principal: agent identity, the "on behalf of" user, and the parent or subagent relationship
• the tool name and argument digest, not the raw arguments if they may contain secrets
• the tier or role that was claimed, and the tier the policy says the caller actually holds
• the token's issue time and expiry, so a reviewer can see the decision rested on a claim issued 41 minutes earlier
• the policy version or bundle hash, so "the rule changed last Tuesday" is a verifiable statement
• a correlation ID linking the tool call, the model turn and the downstream resource access

Microsoft's control list asks for logs that capture agent identity, role, effective scope, action, resource, correlation ID and the on-behalf-of user, then goes further: test that these records exist before you need them (Microsoft). The NHI glossary entry on callable testing subagents makes the same point from the audit side, that the evidence should record which checks ran, which tools were accessed and which exceptions were raised (NHI glossary).

Here is a log line shape that satisfies the list without leaking data:

{
  "event": "tool_decision",
  "correlation_id": "run_8842:step_11:call_3",
  "decision": "deny",
  "reason": "writes above tier ceiling require approval",
  "principal": {"agent": "reporter-v2", "on_behalf_of": "user_5512", "parent": "orchestrator"},
  "tool": {"name": "refund.create", "args_digest": "sha256:9c1f..."},
  "entitlement": {"claimed_tier": "pro", "policy_tier": "free", "source": "token"},
  "token": {"issued_at": "2026-10-14T09:12:03Z", "expires_at": "2026-10-14T09:17:03Z"},
  "policy": {"bundle": "agent/call/decision", "version": "sha256:41ab..."}
}

The line that does the most work in a review is token.issued_at next to policy_tier. It converts the argument from "the policy is wrong" into "the claim was 41 minutes stale and the log shows it," which is a conversation about token lifetimes rather than about correctness.

Two places can refuse a call: a centralized gateway in front of the tools, or the tool server itself. A gateway is a single place for baseline authentication, authorization, throttling and request validation, while service-level policy handles the decisions that depend on the target object, tenant or data field (NHI on gateway versus service enforcement). The same split shows up in AI practice: Azure API Management's AI gateway handles model access, token limits and the MCP traffic contract as the governed boundary, while the application runtime keeps orchestration (Microsoft Tech Community on the AI Gateway tier).

For a tier decision this gives a clean division. The gateway validates the token, checks the coarse tier against a route table and rejects obviously out-of-plan calls early, cheaply and in one place. The tool server owns the final say on anything that touches a specific customer record, a refund or a delete, and that is where a fresh check earns its cost. Putting the fresh lookup only at the server keeps the hot path for reads fast and keeps the precision where the data lives.

The trap is treating the route table as full authorization. An allowlisted server can still expose a destructive operation to a subagent whose task prompt said draft a reply; the server was reachable, the intent was never checked (Permit). Coarse gateway checks plus per-call policy at the server is the layering that avoids it.

Use this as the rule to put in the design doc:

Carry the tier in the token only if you can bound the token's remaining lifetime to the interval you are willing to be wrong about a downgrade, and log the claim's issue time next to every refusal. Otherwise do a lookup per call, or a lookup cached per caller for a few seconds with an explicit invalidation on tier change.

Now run it on a concrete case. A support agent runs inside a customer's helpdesk with three tools: ticket.search, ticket.reply and billing.refund. The product tiers are free (search only), pro (search and reply) and enterprise (all three). Marketing promised that a downgrade stops replies "immediately."

The sales pitch and the engineering answer diverge, and the numbers show it. With a five-minute access token, "immediately" is up to five minutes for ticket.reply, which is probably acceptable if the reply can be recalled. For billing.refund it is not, because money left the account. So the rule produces a split: claim-only for search and reply, fresh lookup plus required approval for refund, with the claim still checked first to reject callers who are on free tier outright. The refusal log carries the claim's issue time so a reviewer can distinguish a stale claim from a mis-set tier. If the team cannot shorten the token or push invalidation, the answer for reply flips to cached lookup with a five-second TTL, and marketing gets told the real number.

The hybrid that most systems land on follows the same shape: a coarse claim gate that fails fast, a short per-caller cache for anything that changes, and a policy call on the destructive minority. AI SDK's policy callback fits this well because the decision can inspect the full message history and running totals, so "approve a second write in one run" or "deny a third irreversible action in this conversation" are expressible as policy rather than as bespoke code (AI SDK).

If you are building this gate and want a single endpoint to test it against before you wire your own policy engine, Quanta Inference exposes text, image, video, audio and embedding models through one OpenAI-compatible API key, which is enough to drive tool-calling loops end to end while you decide where the decision belongs.