DEV Community

razashariff
razashariff

Posted on

The OpenAPI Initiative just merged our new extension called x-agent-trust into its official extensions registry for AI Agents

#openapi #ai #api #security

It is the first vendor extension in OpenAPI specifically designed for APIs that serve autonomous AI agents.

If you build APIs, this is worth 5 minutes of your time.

The problem

Right now, OpenAPI gives you three ways to describe how a caller authenticates:

  • API key in a header
  • OAuth 2.0 / OpenID Connect
  • Mutual TLS with client certificates

All three were designed for humans and their apps. None of them answer the question that matters when an AI agent calls your API:

Who is this agent, and should I trust it to do what it is asking?

An API key tells you nothing about the agent behind the request. OAuth proves a human delegated access to an application, not that the application is an autonomous agent with a specific trust level. Client certificates prove machine identity, not agent identity.

The standards layer has no primitive for "this agent has a trust score of 70, is authorized to spend up to GBP 1000 per transaction, runs the Claude model, and was delegated by a human user with a specific identity."

Until today.

What x-agent-trust does

x-agent-trust extends OpenAPI security schemes with metadata that describes how agents authenticate and how their trust should be evaluated. It is designed to sit alongside your existing security schemes, not replace them.

Here is what it looks like in a spec:

components:
  securitySchemes:
    AgentTrust:
      type: apiKey
      name: Agent-Signature
      in: header
      description: ECDSA-signed agent identity with trust metadata
      x-agent-trust:
        algorithm: ECDSA-P256-SHA256
        trust-levels:
          - L0-UNTRUSTED
          - L1-RESTRICTED
          - L2-STANDARD
          - L3-ELEVATED
          - L4-FULL
        minimum-trust-level: L2-STANDARD
        jwks-uri: https://example.com/.well-known/jwks.json
        verification: local
Enter fullscreen mode Exit fullscreen mode

That is it. Five lines.

Now any tool that reads your OpenAPI spec knows:

  • Agents authenticate via an Agent-Signature header
  • The signature uses ECDSA P-256 with SHA-256
  • There are five trust levels (L0 through L4)
  • This endpoint requires at least L2 (standard) trust
  • The public keys for verification are at a standard JWKS endpoint
  • Verification can happen locally without a callback to the issuer

Your existing authentication stays in place. x-agent-trust adds the agent-specific context on top.

Why this matters

Every API on the internet is about to start receiving traffic from autonomous AI agents. Not chatbots. Not copilots. Actual autonomous agents making decisions, calling tools, and executing transactions on behalf of humans or organizations.

If you run an API today that could be called by an agent, three things are true:

  1. You need to know if the caller is an agent, so you can apply different policies
  2. You need to know the agent's trust level, so you can decide whether to serve the request
  3. You need to prove to auditors what happened, because "an AI agent called my API" is going to become a compliance requirement in regulated industries

x-agent-trust gives you a standard way to describe all three in your API specification. No proprietary format. No vendor lock-in. Same registry that defines extensions used by AWS, Google, Microsoft.

What you can do with it today

Add it to your OpenAPI spec. Tools will progressively add support as agent traffic grows. Even without tool support, the extension serves as documentation for anyone integrating with your API.

For fintechs and payment processors, this is particularly relevant. If your API processes financial transactions, agents are already calling it. Describing your trust requirements with x-agent-trust gives compliance teams a machine-readable answer to "what trust level is required for this operation?"

For MCP server authors, this is the standard way to expose security requirements in a format that any OpenAPI-aware tool can understand.

The broader picture

x-agent-trust is part of a larger effort to build the standards layer for the agent economy. The related pieces:

  • OWASP MCP Security Cheat Sheet Section 7 covers message integrity, replay protection, and tool hash-pinning for agent calls
  • IETF draft-sharif-apki-agent-pki-00 defines the full certificate-based Agent Public Key Infrastructure
  • IETF draft-sharif-mcps-secure-mcp covers cryptographic signing for MCP messages
  • OpenAPI x-agent-trust (this extension) provides the API description layer

Four different standards bodies, one consistent story. Each layer builds on the others.

Get involved

The extension is live now at:

https://spec.openapis.org/registry/extension/

If you maintain a tool that reads OpenAPI specs (Swagger UI, Redoc, Postman, Stoplight, Kong, Apigee, Tyk), consider adding support for rendering x-agent-trust metadata.

If you build APIs that agents call, start including it in your specs. The syntax is stable and the registry entry is permanent.

If you have feedback or questions, find me on GitHub at razashariff or reach out via:

Agent traffic is coming. The standards are here. Time to use them.

Raza Sharif
CyberSecAI Ltd | cybersecai.co.uk

Top comments (0)