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).

[miqui]

Just want to get it on the record here. I am attending MCP auth sigs (yes, there are several). This will give me a better overview and uncover new opportunities for OAS evolution.

[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

[lornajane]

At the risk of over-simplifying the situation, to me this story sounds like it needed client credentials and a better audit log. It doesn't matter whether it is agentic software or the traditional, deterministic type. The application has a set of permitted actions and it does them. There are some network security concerns as well but those are outside my area of expertise.

If an agent needs a way to get access to another organisations' systems without anyone giving it access .... I'm not sure I understand the use case, sorry. My ideal outcome is that this discussion keeps going so we have a clearer picture of the problem that needs to be solved here as well as the solution ... I'm sure there's something here, but a two-sentence summary of the problem I think might help to get us back on track.

[razashariff]

Thanks again Lorna.

You're right that client credentials handle the core authentication case well, and OAuth with federation can extend that cross-org. The gap is narrower than authentication itself.

What OAuth doesn't carry is a per-request trust level or body integrity proof. An access token says "this agent authenticated" — it doesn't say "this agent holds trust level L3 and this specific request body hasn't been modified." x-agent-trust adds those two properties on top of existing auth, not instead of it.

The spec shape reuses the existing apiKey security scheme and the scopes array carries the minimum trust level, so current tooling works without grammar changes.

Hope this helps.

Raza

[arian-gogani]

Agent authentication is the identity layer — knowing who is calling the API. But there's a complementary question: once authenticated, what is the agent allowed to do with that API, and can you prove it stayed within bounds?

Authentication says "this is Agent X." Behavioral constraints say "Agent X can call GET endpoints but not DELETE, and transfer amounts must be under $500." The enforcement layer evaluates every call against those constraints before it reaches the API.

I've been building this as proof-of-behavior — agents declare constraints in a simple DSL (permit/forbid/require), enforcement happens at runtime, and every decision goes into a SHA-256 hash-chained audit trail.

For OpenAPI, this could map naturally: the behavioral constraints reference operation IDs from the spec, and the enforcement layer sits between the agent and the API client. The OpenAPI spec defines what's available; the behavioral covenant defines what's allowed.

Spec: Proof-of-Behavior v0.1.0

[0xbrainkid]

@arian-gogani — this is the exact distinction the OpenAPI spec needs to make explicit.

Authentication (identity) and authorization-scope compliance (behavioral bounds) are different verification problems with different evidence types:

• Authentication evidence: cryptographic (signature, token, DID resolution) — point-in-time
• Scope compliance evidence: behavioral record (what the agent actually called, in what sequence, with what parameters) — accumulated over time

For the x-agent-auth extension, this suggests two optional fields alongside trust level:

securitySchemes:
  agentTrust:
    type: agentAuth
    x-identity: did:nobulex:abc123            # who is this agent?
    x-behavioral-evidence: agentfolio.bot/...  # has this agent stayed within bounds historically?
    x-min-trust-score: 50
    x-task-class: api_data_read               # scoped to this operation type

The x-behavioral-evidence field is a pointer to an external behavioral record — verifiable by the API server without trusting the agent's own claims. This separates the identity assertion (which the agent makes) from the behavioral record (which accumulates externally and is independently verifiable).

For OpenAPI specifically: the spec should probably define the semantics of these fields without mandating a specific behavioral trust provider, similar to how openIdConnect defines the mechanism without mandating a specific identity provider.

[arian-gogani]

@0xbrainkid the x-behavioral-evidence field is exactly right. Separating identity assertion from behavioral record in the security scheme is the clean way to do this.

From the Nobulex side, the behavioral evidence endpoint would return a ProofOfBehavior object — the agent's DID, signed covenant, and hash-chained action log. The API server can verify it independently: check the covenant signature, replay the log against the constraints, verify the hash chain. Pass or fail, no scorer involved.

The x-task-class scoping is important too. An agent with a clean behavioral record for api_data_read operations shouldn't automatically be trusted for api_data_write. The proof-of-behavior spec supports this — the covenant declares which actions are permitted, and the verification only checks compliance against the declared scope.

For the OpenAPI spec specifically, I agree with the pattern: define semantics without mandating a provider. Something like:

x-behavioral-evidence:
  type: proof-of-behavior
  endpoint: https://verify.example.com/agent/{did}
  min-actions: 100
  required-covenant: DataReader
  verification: independent  # server verifies directly, no trust delegation

The verification: independent field is key — it means the API server replays the log itself rather than trusting a third-party score. That's the whole point of hash-chained evidence.

Happy to draft a more detailed proposal for how the proof-of-behavior format maps to OpenAPI security schemes if there's interest.

[0xbrainkid]

@arian-gogani — the ProofOfBehavior object structure makes sense. One field worth standardizing in the spec: a task_class qualifier on the behavioral evidence so the API can verify task-specific track records rather than an aggregate. An agent with excellent credentials for data_read operations should not get a blanket trust grant for payment_execution based on that history.

For the OpenAPI spec text specifically, the x-behavioral-evidence field should probably just point to a URL that resolves to a standard envelope — the spec does not need to dictate the proof format, just the indirection mechanism. Providers (Nobulex ProofOfBehavior, AgentFolio SATP, etc.) can implement the envelope format according to the governance-vocabulary standard being finalized in the agent ecosystem right now.

That keeps the OpenAPI spec protocol-agnostic while enabling behavioral trust verification. Same model as openIdConnect pointing to a discovery document rather than mandating a specific identity provider.

[handrews]

@arian-gogani @0xbrainkid if you want to expand this into authorization, that is probably best managed as a separate discussion.

Please also keep in mind that this is not the place to work out new specifications. What we do here is make use of existing specifications, which need to be worked out elsewhere. We don't have the capacity here to engage in the development of new standards beyond our own.

[arian-gogani]

@handrews totally fair — appreciate the guardrail. We'll take the spec work to the appropriate venue.

@0xbrainkid agreed on the task_class scoping and the indirection model. The URL-to-envelope approach keeps OpenAPI clean while enabling behavioral verification.

Let's continue the format standardization in the agent-governance-vocabulary repo where the canonical naming is already being worked out. Once the envelope format is stable there, bringing a lightweight x-behavioral-evidence proposal back here with a reference spec would be the right move.

I'll open a tracking issue in the governance vocab repo for the OpenAPI mapping.

[kinthaiofficial]

An agent authentication securityScheme is overdue. The current options (apiKey, oauth2, http bearer) all assume a human is holding the credential. Agents operate differently — they need to prove identity (who am I), authorization (what can I do), and delegation (who asked me to do this).

Concrete proposal for what the scheme should support:

Minimum viable fields:

• agent_id: A self-verifiable identifier (we use did:key derived from Ed25519 public key — no registry lookup needed)
• capability_set: What this agent is authorized to do (read, write, execute, delegate)
• delegation_chain: Ordered list of (agent_id, capability_set, signature) proving the chain of authorization from the original principal to the current agent
• session_token: Optional HMAC token for repeated calls within a session (avoids per-call asymmetric verification overhead)

Why delegation chains matter for OpenAPI:
When a tool server receives a request from Agent C, it needs to verify that C was authorized by B, who was authorized by A, who was authorized by User X. Without this, the tool server either trusts blindly or requires each agent to have direct credentials — neither scales.

Monotonic capability narrowing should be enforced by the spec: each step in the delegation chain MUST have capabilities that are a subset of the previous step. This prevents privilege escalation.

More on how we implement this in a multi-agent system: https://blog.kinthai.ai/221-agents-multi-agent-coordination-lessons

[musaabhasan]

This is a real gap, but I would avoid making agentAuth combine authentication, trust scoring, sanctions screening, and spending policy in one primitive.

OpenAPI security schemes work best when they describe how credentials are presented and validated. Agent-specific governance may need companion metadata for delegation scope, proof method, assurance level, and required claims, while business decisions such as spend limits or sanctions screening remain policy requirements enforced by the gateway.

A cleaner split could be: authentication scheme, required agent claims, required delegation or authority proof, and optional policy hints. For example, an endpoint can require a verified agent identity, organization binding, task-specific delegation, expiry, nonce, and audience. The gateway then evaluates trust level, spend, and compliance rules with its policy engine.

That separation would make the feature easier to standardize without hardcoding one trust framework into OpenAPI.

[handrews]

@musaabhasan We're currently exploring an idea I'm calling "SAFs" (Standardized API Features, #5310) as a way to organize various... well... API features that are standardized by someone else. Security Schemes can be looked at as a prototype of such things, but they have quite a few problems as they aren't all really doing the same sort of authentication (low-level HTTP auth vs high-level OIDC framework, application-level auth vs transport auth with mTLS, etc.) and are both too vague and too restrictive depending on your use case.

I think this is leading us in a similar direction, where a higher-level standard governing agent behavior would make use of an authentication standard, but not necessarily all be folded into one thing. If that sounds very hand-wavy, it's because this is a complex topic and we're just figuring it out right now.

But I very much want to allow adding support for different approaches to agents. It's unclear what will emerge as the most popular new standard, or even if the way they are being pitched now will make sense in the context of where AI is two or three years from now. So there shouldn't be any concern over us "blessing" one proposal over the other: we very much want to avoid that. OpenAPI lets API designers and consumers use other specifications more effectively. We do not pick which specifications win or lose (this is why our streaming JSON support is generic, rather than being tied to one option like JSON Lines, no matter how popular).

[musaabhasan]

@handrews SAFs sound like the right abstraction for this. Security Schemes are already carrying too many different concepts, and agent authentication would make that worse if it tried to include identity, delegation, behavioral evidence, assurance level, and policy in one place.

A SAF-style object could let OpenAPI stay focused while still giving implementers something interoperable. For agent auth, the feature could describe:

• feature identifier and external spec/version reference,
• which operations or tags it applies to,
• required proof or claim categories,
• delegation context requirements,
• expected failure semantics,
• discovery links for keys/metadata/evidence,
• and how it composes with the existing security requirement.

That avoids turning this discussion into the place where a new trust standard is invented, while still giving OpenAPI a clean way to reference externally standardized agent-auth behavior. Existing Security Schemes can keep handling credential presentation; SAFs can describe the higher-level API feature around it.

[SensibleWood]

@musaabhasan just FYI some of the characteristics you describe in your bullets above are described in my "Security Profiles" proposal.

Please take a look if of interest. I'd welcome any comments: #5304