Proposal: Agent authentication securityScheme for OpenAPI

[razashariff]

As AI agents become primary API consumers, OpenAPI needs a way to describe agent-specific authentication requirements.

Current gap: securitySchemes supports apiKey, http, oauth2, openIdConnect -- all designed for human users or static services. None capture agent identity, trust level, or behavioural authorization.

Proposed securityScheme: agentAuth

securitySchemes:
  agentTrust:
    type: agentAuth
    description: Agent must present cryptographic identity with minimum trust level
    properties:
      identityMethod: challengeResponse
      minimumTrustLevel: L2
      sanctionsScreeningRequired: true
      spendLimit: 10000

This enables API providers to declare: "this endpoint requires a verified agent with trust level L2+ and sanctions screening clearance."

Every API gateway (Kong, Apigee, AWS API Gateway) could enforce this natively.

Reference: IETF draft-sharif-agent-payment-trust-00 defines the trust level framework.

[miqui]

@razashariff - Thanks for submitting this idea. If you don't mind, please re-create this in the Discussion area of the repo.

Question: Can you provide additional tech details on the proposed scheme? Describe the flow of this (Its the first time I see the draft IETF record). There are a lot of folks out there coming up with security schemas for Agents, A2A, MCPs....etc. so, lets see where this all fits.

[handrews]

@miqui @razashariff it's possible to convert issues to discussions, so I went ahead and did that. @razashariff the reason is that we are trying to only file issues when things are ready for a PR, and a proposal like this will need significant consideration before it gets to that point as it introduces new concepts to the OAS. We do probably still have some old issues that should be moved to discussions which makes it a bit confusing.

[razashariff]

Thanks @miqui -- here are the technical details.

This is documented and approved by OWASP, with three IETF Internet-Drafts covering the protocol.

Authentication Flow

1. Agent → API:  POST /auth/challenge  { agent_handle, public_key }
2. API → Agent:  { challenge: <random_nonce>, expires: <timestamp> }
3. Agent → API:  { challenge, signature: ECDSA_sign(challenge, private_key) }
4. API:          Verify signature against registered public key
                 Check trust_level >= endpoint minimum
                 Screen agent_handle against sanctions lists (OFAC/HMT)
5. API → Agent:  { token: <JWT>, trust_level: L3, permissions: [...] }

The JWT contains standard claims plus agent-specific ones:

{
  "sub": "payment-bot.acme.agentpass",
  "agent_trust_level": 3,
  "agent_owner": "did:web:acme.com",
  "agent_capabilities": ["payments.create", "payments.read"],
  "agent_sanctions_clear": true,
  "agent_sanctions_checked_at": "2026-03-26T15:00:00Z"
}

Proposed securityScheme

securitySchemes:
  agentTrust:
    type: agentAuth
    properties:
      identityMethod: challengeResponse
      minimumTrustLevel: L2
      sanctionsScreeningRequired: true
      spendLimit: 10000

paths:
  /payments:
    post:
      security:
        - agentTrust: [payments.create]

Where this fits vs other approaches

Approach	Scope	Agent Identity	Trust Scoring	Sanctions
OAuth 2.0	Human/service auth	No	No	No
Google A2A	Agent-to-agent comms	Partial (Agent Cards)	No	No
SPIFFE/SPIRE	Workload identity	Service-level	No	No
This proposal	Agent-to-API auth	Yes (cryptographic)	Yes (L0-L4)	Yes

Standards backing

• OWASP: MCP Security Cheat Sheet Section 7 -- approved and live
• IETF:
  • draft-sharif-mcps-secure-mcp -- message signing
  • draft-sharif-agent-payment-trust -- trust framework and payment authorisation
  • draft-sharif-openid-agent-identity -- OpenID Connect agent identity claims

Happy to go deeper on any part of this.

[handrews]

@razashariff you've done the right thing by publishing IETF drafts, but as they were published just this month, we'll want to keep an eye on them but not act on them immediately.

That said, we are planning significant updates to how Security Schemes work in 3.3. I'm in the process of reviewing our existing proposals in this area, and I will include this one. We are more likely to "support" this by making it easier to register security-related extensions (and not just single extension fields) in the near term, and wait until any RFCs are closer to ratification before adding any dedicated features. (while we do depend on JSON Schema drafts, JSON Schema's perpetual draft status is unusual, not to be emulated, and now finally being worked on via proper IETF channels).

Regarding MCP, we're still trying to figure out how to best engage with that specification, particularly given that it moves much faster than we do (our tooling ecosystem is large, complex, and can't absorb new versions as quickly as newer ecosystems).

[razashariff]

Thanks @handrews -- understood. We'll keep progressing the IETF drafts and happy to stay engaged as the 3.3 security scheme work evolves. If it's useful at any point, we can provide input on what agent-specific patterns we're seeing in the wild as you shape the extension model.

[handrews]

@razashariff that would be very helpful!

[0xbrainkid]

This is exactly the right direction. The IETF drafts referenced here (draft-sharif-agent-payment-trust) map well to what we're seeing in production.

Some data points from RSAC 2026 last week that validate this:

• 200+ vendors launched agent identity/security products — all enterprise-scoped, none handle cross-org agent auth
• BeyondTrust Phantom Labs: 466.7% YoY growth in AI agents inside enterprise
• CSA: 68% of organizations can't distinguish agent from human in API calls
• Vorlon (500 CISOs surveyed): 89% claim strong OAuth governance, 27% still breached through OAuth

The minimumTrustLevel: L2 field is critical. We've implemented a working version of this in the Solana Agent Trust Protocol — trust levels derived from on-chain verifiable actions rather than self-asserted claims. The L1-L5 framework in draft-sharif-agent-payment-trust aligns well.

Practical question for the proposal: how do you envision API gateways (Kong, Apigee) bootstrapping the initial trust verification? In our implementation, the first call includes a challenge-response against the agent's Ed25519 key, with trust level resolved from on-chain state. This adds ~50ms to first call, zero to subsequent (session token cached).

Would be valuable to see this formalized in OpenAPI 3.3 — every API gateway enforcing agent trust natively would be a massive step forward.

[razashariff]

Thanks @0xbrainkid — useful data points, particularly the CSA stat on agent/human distinction in API calls. That validates the need for agent-specific authentication at the gateway level.

On the API gateway bootstrapping question:

We use a pluggable trust resolution step at the gateway. First call includes a signed identity token (ECDSA P-256), gateway verifies the signature, resolves trust level from a configurable provider, then issues a cached session token for subsequent calls. The trust provider is intentionally decoupled — on-chain resolution, federated registry, or self-hosted all work as backends. The gateway just needs a trust level back within a timeout window.

Your ~50ms first-call overhead is consistent with what we see. Session caching eliminates it for subsequent calls.

For OpenAPI formalisation, the security scheme would define the trust verification endpoint contract and response format, letting gateway vendors choose their own resolution backend. That keeps it implementation-agnostic while giving the ecosystem a standard interface.

[razashariff]

@handrews -- here is a working implementation.

Live demo: https://x-agent-auth.fly.dev/
OpenAPI spec with extension: https://x-agent-auth.fly.dev/openapi.yaml
JWKS key discovery: https://x-agent-auth.fly.dev/.well-known/agent-trust-keys

The extension (works with OpenAPI 3.0 / 3.1 today):

x-agent-auth:
  algorithm: ES256
  trustLevels: [L0, L1, L2, L3, L4]
  issuerKeysUrl: /.well-known/agent-trust-keys

Per-endpoint trust requirement:

paths:
  /v1/charges:
    post:
      x-agent-trust-required: L2

API side -- one middleware line:

const { verifyAgentTrust } = require("mcp-secure");
app.use(verifyAgentTrust({ minTrust: "L2" }));

How it works:

1. Agent carries a signed trust token (JWT-structured, ECDSA P-256)
2. API middleware verifies the signature locally using cached issuer public key (JWKS pattern)
3. Reads trust level (L0-L4) from token payload
4. Compares against endpoint requirement
5. No remote call. No gateway required. No vendor dependency.

Trust levels (defined in draft-sharif-agent-payment-trust):

Level	Meaning	Typical access
L0	Unknown agent	Reject
L1	Identity verified	Read-only
L2	Trust established	Read + write
L3	Highly trusted	Read + write + execute
L4	Fully trusted	Full access

The demo has 5 agents (L0 through L4) and 4 endpoints with different trust requirements. Try the L0 agent (sanctions-flagged) against any endpoint to see rejection. Try L4 against admin to see full approval.

Same token works for REST APIs (via this extension) and MCP servers (via MCPS). One agent identity, both protocols.

Additional IETF drafts since our last exchange:

• Agent identity claims (extending OpenID Connect patterns)
• Agent transport protocol (async store-and-forward for agents)
• Agent audit trail (submission #161719, formalises logging requirements)

The OWASP MCP Security Cheat Sheet covers the message integrity requirements in Section 7. CIS is developing an MCP Security Benchmark due May 2026.

API gateways (Kong, Apigee) can enforce this too, but they are not required. Any Express/FastAPI/Rails app verifies directly with one middleware line.

Available as an x- extension today. Ready to evolve into a dedicated agentTrust security scheme type for 3.3. Happy to contribute to the security scheme working group.

[razashariff]

@handrews -- thank you, this is really helpful context. I've opened a PR to register the extension: OAI/spec.openapis.org#67

The registry approach makes a lot of sense for the transition -- x-agent-auth works today, and a Security Scheme registry in 3.3 would give it a natural upgrade path without breaking existing adopters. Happy to contribute to the Security Scheme architecture work when the time comes.

Appreciate the transparency on the TSC process. Will keep the IETF drafts progressing in the meantime.

[handrews]

For those wondering if they missed a step, I replied to an off-github email (that I guess was just a cc of a github comment) inviting the registry contribution, and saying that I hope to add a registry for Security Schemes to make extensibility easier in this area, which requires a clearly extensible Security Scheme architecture. But also that such decisions are ultimately up to the TSC. I'm researching and writing proposals for this rather than making the final decisions, so don't take this idea as a commitment! It will be discussed in this repo, so stay tuned!

[earth2marsh]

I want to make sure I understand the human problem being solved, because the technical mechanism is clear but the "for whom and why" is less so.

Today, when a person wants software to act on their behalf with an API, we have delegation patterns — OAuth's on-behalf-of flows, token exchange, scoped API keys. These all preserve a clear line: a human authorized this, here's the scope, here's the chain. What's the specific scenario where those patterns fail for agents? I'd find it helpful to see the motivating user story written out — who is the person, what are they trying to do, and where does the current model break down for them?

My hesitation with agent-as-principal (independent identity, trust levels, autonomous authentication) is that it inverts the accountability model in ways that create real problems for people:

Consent can't be automated. Accessing an API typically implies acceptance of terms of service. An agent can't agree to terms. And a person deploying an agent can't pre-consent to terms of services the agent hasn't discovered yet. Making it frictionless for agents to authenticate to new APIs creates a consent gap — not a technical one, but a legal and ethical one.

Identity isn't accountability. The trust levels verify that an agent is who it claims to be, which is useful. But the harder question is whether a person authorized this specific action. Without a mandatory link from agent action back to human authorization, you get what I'd call behavior washing — the agent intermediation creates a layer of indirection that dilutes responsibility. "Authenticated at L3" doesn't tell you whether a person approved the transaction.

Access expansion should have a human in the loop. An agent acting within scopes a person already authorized is delegation. An agent independently discovering and authenticating to new services is something different — it's access expansion, and I think that should require a person's involvement.

I'd be genuinely interested in a proposal that strengthened the delegation model for agents — making human authorization more explicit and traceable — rather than one that gives agents independent standing. But I may be missing the scenario where delegation truly doesn't work, so I'd welcome hearing it.

[0xbrainkid]

@earth2marsh — your framing is right that delegation is the foundation. The specific scenario where it fails is cross-organizational.

Delegation works within a trust boundary. When Agent A uses Human H's OAuth token on Service S, the chain is clear: H authorized A, S trusts H, accountability is traceable. This covers most agentic use cases today.

Where it breaks: Agent A from Org X operating on Service S at Org Y.

Org Y has no prior relationship with Org X, no OAuth flow with H (who lives at Org X), no mechanism to evaluate A's trustworthiness. Options:

1. Deny all external agents (not scalable as agents become primary API consumers)
2. Trust self-declared identity (the consent + accountability problem you've identified)
3. Require portable behavioral reputation — trust A has earned across other interactions, independently verifiable

Your concern about behavior washing is exactly right. "Authenticated at L3" without accountability is insufficient. The solution isn't to give agents independent standing — it's to ensure behavioral reputation requires prior human-authorized interactions to have occurred. An agent with high trust score has demonstrably completed previous actions within authorized scopes. The score is a proxy for "this agent has a track record of working within human authorization."

On consent: the right design is agent presents reputation → service decides at what tier to grant access → human controls scope at delegation time. Behavioral trust informs the service's risk decision; it doesn't bypass the human.

For the OpenAPI spec: the x-agent-auth extension could require a human_authorization_ref alongside trust level — behavioral reputation as a secondary signal, not a replacement for the delegation chain. The two compose: delegation answers "was this authorized by a human?" and behavioral trust answers "does this agent have a verified track record of working within that authorization?"

This is precisely where cross-org agent identity differs from within-org delegation. You need a trust signal that's portable across org boundaries and independently verifiable — not a new authentication scheme, but a reputation layer that assumes and strengthens the delegation model.

[razashariff]

@earth2marsh — appreciate you pushing on this carefully. Some of what you're flagging is exactly right and I want to engage it head-on, but I think the framing of "we already have delegation patterns" doesn't quite capture where the gap sits, so I want to push back on a couple of things too.

The motivating story. A finance operator at a regulated company authorizes an agent to reconcile payments overnight, within a defined scope. The agent runs at 3am — hours after the human authorized it, in a different context — calls a payments service through a couple of gateways and an audit collector, and processes 200 transactions. One of those transactions goes through that the human would not have intended. The next morning, when the team and the regulator try to reconstruct what happened, the audit log shows "the agent had payments:write and made the call". We can prove the agent had permission. We cannot prove the human intended that transaction. That's the failure mode I'm trying to address — not that the agent lacks permission, but that after the fact we cannot prove any specific action was actually within the human's intent. Only that it was within a broad scope.

On "we already have delegation patterns". OAuth is fine for what it does — and yes, refresh tokens, offline access, and client credentials cover plenty of asynchronous and unattended flows. The gap I'm pointing at is narrower than that: OAuth scopes and bearer tokens do not bind authorization to specific request content. A token with payments:write says the bearer can call the payments endpoint. It does not say "the human authorized this specific recipient and this specific amount". For human-mediated flows that's usually fine — the human is in the loop step by step. For agentic flows operating across thousands of actions per day, often hours after the original authorization, that gap becomes the regulator's problem and the incident responder's problem.

On intermediaries. This is the part where the bearer-token assumption silently weakens. Bearer tokens survive every TLS hop because they sit in the Authorization header. Request body integrity does not survive any of those hops. TLS terminates and re-originates at every gateway, sidecar, audit collector, and proxy. The body is plaintext at each hop. If a compromised intermediary modifies the recipient or the amount, the receiving service has no way to detect it — the bearer token still verifies, the OAuth scope still passes, the request still looks legitimate. Catching that class of attack requires a different layer of defence — in practice, a signature over the request content itself.

On consent vs per-action authorization. I think these are getting conflated and it's worth separating. ToS acceptance is a legal precondition that a human handles once at deployment time. Per-action authorization is an operational concern that happens thousands of times per day after that. They're different problems and need different solutions. "Agents can't agree to ToS" is true and it's a valid argument against autonomous service discovery — which I agree is bad, and which this proposal does not enable. It isn't an argument against giving the operational layer cryptographic proof of what was authorized.

On "identity isn't accountability". Agreed in spirit, with one nuance. Identity verification is a necessary condition for accountability — without it you can't even ask "who did this and was it authorized". It isn't a sufficient condition, and nothing in this proposal claims it is. Trust levels are evidence in the audit chain, not authorization grants. The authorization decision still happens at the policy layer — OAuth scopes, AuthZEN, application logic. What this primitive adds is the cryptographic link between "the human delegated this" and "this exact request body arrived at the destination".

Where I think you're completely right. Autonomous discovery and authentication to new services should require human approval — full stop, and nothing here enables it. And "authenticated at L3" by itself does not tell you authorization happened — that's correct, and treating trust levels as anything more than evidence in the audit chain would be a mistake.

On the framing. Reading your comment back, I think the noun I've been using ("agent authentication") is genuinely less useful than what your concerns are pointing toward. Something like delegation receipts might capture it better — per-action cryptographic proofs that link back to the human authorization that produced them, that survive intermediaries, that an auditor can verify after the fact. That keeps the delegation model human-rooted and just makes it traceable per-action. If that lands better I'd be willing to revise the language in the IETF drafts and this proposal — it's a noun change, not a content change, and it captures the actual intent more accurately.

The reason I'm pushing back on "we already have delegation patterns" specifically is that I've watched this fail in production multiple times — in financial services, in healthcare, and more recently in agentic AI deployments where the bearer-token model stops providing end-to-end integrity guarantees once intermediaries are in the path. The delegation model is right. The implementation primitives we have today don't survive that operating environment. That's the gap — not giving agents independent standing, but giving humans a cryptographic record of what they actually authorized.

Happy to keep this going — this is the kind of conversation the spec benefits from.

Sorry for the slightly long response — wanted to make sure I covered all your points.

Raza Sharif
CyberSecAI Ltd