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: Uses agent trust information in lieu of a traditional API key. Requires the x-agent-trust extension.
      x-agent-trust:
        algorithm: ES256
        trustLevels: [L0, L1, L2, L3, L4]
        issuerKeysUrl: /.well-known/agent-trust-keys

paths:
  /v1/charges:
    post:
      security:
        - AgentTrust: [L3]

That is the entire spec change. The x-agent-trust block describes the security scheme. Per the OAI registry entry, the scopes array on each operation's security requirement carries the minimum trust level required for that endpoint -- so [L3] here means the operation requires at least L3 trust.

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({
  issuerKeysUrl: 'https://your-api.example.com/.well-known/agent-trust-keys',
  minTrustLevel: 'L3',
  algorithm: 'ES256'
}));

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,
        issuer_keys_url='https://your-api.example.com/.well-known/agent-trust-keys',
        min_trust_level='L3'
    )
    if not result.valid:
        return {'error': result.error}, 401
    return {'ok': True, 'agent_id': result.agent_id}

Signing: how to actually do it

The signing flow is three steps: build a canonical string, sign it with ECDSA P-256, attach the signature as an Agent-Signature header. There is no novel cryptography here -- the same primitive is used in AWS Signature V4 and IETF HTTP Message Signatures (RFC 9421). Any language with a crypto stdlib can implement it in roughly 20 lines.

The integration menu, ordered from "5 minutes" to "production grade":

Where the private key lives

How signing happens

How verification happens (on the API receiving signed requests)

What you do NOT need

• You do not need our SDK. The published SDKs are convenience, not requirement -- you can implement the spec from the registry entry in any language with a crypto stdlib.
• You do not need a SaaS dependency. The protocol is local-verification by design. No vendor sits in the trust path.
• You do not need novel cryptography. ECDSA over a canonical request is the same primitive AWS has used in Signature V4 since 2008.
• You do not need to replace your existing auth. x-agent-trust sits alongside OAuth 2.1, DPoP, mTLS, and API keys -- it adds an agent identity layer on top, it does not remove anything.

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.