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!