Build with x-agent-trust

Integration guide for the official OpenAPI extension for AI agent authentication. Approved and merged into the OpenAPI Extensions Registry on 11 April 2026.

Overview

x-agent-trust is a vendor extension that describes how AI agents authenticate to your API. It sits inside your existing OpenAPI securitySchemes block and carries the algorithm, trust level vocabulary, and JWKS endpoint your API uses to verify agents.

You do not need to rewrite your API. You add five lines to your OpenAPI spec and one middleware line in your server. Agents authenticate with a signed Agent-Signature header. Your server verifies locally against a JWKS endpoint. No gateway. No SaaS dependency.

Step 1: Add the extension to your OpenAPI spec

openapi: "3.1.0"
info:
  title: My API
  version: "1.0.0"

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://your-api.example.com/.well-known/agent-trust-keys
        verification: local

paths:
  /v1/charges:
    post:
      security:
        - AgentTrust: []
      x-agent-trust-required: L3-ELEVATED

That is the entire spec change. The x-agent-trust block describes what your API requires. The x-agent-trust-required field on individual operations lets you raise the bar for sensitive endpoints.

Step 2: Publish a JWKS endpoint

Publish your issuer's public keys at /.well-known/agent-trust-keys using standard JWKS format (RFC 7517). Relying parties fetch this once and verify signatures locally.

{
  "keys": [
    {
      "kty": "EC",
      "crv": "P-256",
      "kid": "agent-trust-2026-04",
      "use": "sig",
      "alg": "ES256",
      "x": "f83OJ3D2xF1Bg8vub9tLe1gHMzV76e8Tus9uPHvRVEU",
      "y": "x_FEzRu9m36HLN_tue659LNpXW6pCyStikYjKIWI5a0"
    }
  ]
}

Step 3: Agents sign requests

An agent generates an ECDSA P-256 key pair, obtains a trust-level assertion from its issuer, and signs each outgoing request with an Agent-Signature header. The signature covers the canonical request: HTTP method, path, timestamp, nonce, and a SHA-256 hash of the body.

POST /v1/charges HTTP/1.1
Host: your-api.example.com
Authorization: Bearer <oauth-token>
Agent-Signature: keyid="payment-bot@acme.com",
                 alg="ES256",
                 ts="1775894679",
                 nonce="3fc4b1",
                 trust="L3",
                 sig="MEUCIQD..."
Content-Type: application/json

{"amount": 500, "currency": "GBP"}

Step 4: Server verifies locally

Your API server fetches the JWKS endpoint once (cached), parses the Agent-Signature header, rebuilds the canonical request string, and verifies the signature against the published public key. If the trust level meets the endpoint's requirement, the request proceeds.

Node.js / Express

npm install mcp-secure
# or
npm install @cybersecai/agent-trust-middleware

const express = require('express');
const { verifyAgentTrust } = require('mcp-secure');

const app = express();
app.use(express.json());

app.use('/v1/charges', verifyAgentTrust({
  jwksUri: 'https://your-api.example.com/.well-known/agent-trust-keys',
  minTrustLevel: 'L3-ELEVATED',
  algorithm: 'ECDSA-P256-SHA256'
}));

app.post('/v1/charges', (req, res) => {
  // req.agent now contains verified identity + trust level
  console.log('Agent:', req.agent.id, 'Trust:', req.agent.trustLevel);
  res.json({ ok: true });
});

Go

go get github.com/razashariff/mcps-go@v1.0.0

import mcps "github.com/razashariff/mcps-go"

// Load signing keys (stable across reboots)
kp, _ := mcps.LoadKeyPair("agent-trust.key", "agent-trust.pub")

// Verify incoming Agent-Signature header
err := mcps.VerifyMessage(signedMessage, kp.PublicKey)
if err != nil {
    http.Error(w, "Invalid agent signature", 401)
    return
}

// Check trust level against required
err = mcps.VerifyPassport(passport, mcps.TrustElevated)
if err != nil {
    http.Error(w, "Insufficient trust level", 403)
    return
}

Python

pip install mcps-secure

from mcps_secure import verify_agent_signature

@app.route('/v1/charges', methods=['POST'])
def create_charge():
    result = verify_agent_signature(
        request.headers,
        jwks_uri='https://your-api.example.com/.well-known/agent-trust-keys',
        min_trust_level='L3-ELEVATED'
    )
    if not result.valid:
        return {'error': result.error}, 401
    return {'ok': True, 'agent_id': result.agent_id}

What you get

• Zero gateway dependency. Verification happens in your API server, not in a SaaS proxy.
• Tamper-evident requests. Every request body is hashed and signed. Any modification in transit breaks the signature.
• Replay protection. Every signature includes a nonce and timestamp. Duplicate requests fail verification.
• Trust levels. L0 through L4 give you five tiers of trust. You decide which endpoints require which tier.
• Composable. Works alongside OAuth 2.1, DPoP, mTLS, and API keys. You do not replace your existing auth.
• Standards-backed. Registered OpenAPI extension. OWASP MCP Security Cheat Sheet Section 7. IETF drafts on Datatracker.

Issuing trust levels: bring your own authority

Trust-level assertions come from an issuer you control, or from a third-party trust authority you federate with. The issuer signs the agent's passport with a key published at its JWKS endpoint. Your API trusts the issuer, the issuer vouches for the agent, and the chain is cryptographically verifiable at every hop.

For managed agent identity issuance, see AgentSign. For full certificate-based agent PKI (APKI), see IETF draft-sharif-apki-agent-pki.

The bigger picture

x-agent-trust is the API-description layer of a larger standards stack for agent security:

• OpenAPI describes what your API requires (this extension).
• MCPS signs messages end-to-end beyond what TLS can guarantee through intermediaries.
• APKI issues and revokes certificate-based agent identities with embedded trust scores.
• OWASP MCP Security Cheat Sheet Section 7 documents message integrity and replay protection patterns.

Each layer is independently useful. Together they give you end-to-end tamper-evident trust from agent to API.