Uchi Uchibeke

· Security

I Added .well-known/oap/ to My Agent Spec. Here's Why Every AI Service Needs One.

The agent passport spec now defines a .well-known/oap/ discovery endpoint so any system can verify what an AI agent is authorized to do.

A pull request landed in the aporthq/aport-spec repository: feat: .well-known/oap/ service discovery (IANA D-008).

It is 6 lines of spec change. And it might be the most important thing we have shipped for AI agent security this year.

Here is why.

TL;DR

  • AI agents can't identify themselves to each other or to the systems they call. That's a serious security gap.
  • RFC 8615 defined .well-known/ URIs for exactly this purpose. OAuth, WebFinger, and ACME all use it.
  • We just merged .well-known/oap/ into the Open Agent Passport spec, giving AI agents a standard discovery endpoint.
  • Any service hosting an AI agent can now expose https://yourdomain.com/.well-known/oap/ and let other systems verify what that agent is authorized to do.
  • Implementation takes under 30 minutes. The spec is open.

The problem: AI agents have no address

Imagine you receive a wire transfer from a number you don't recognize. There is no IBAN, no sender name, no bank reference. You can see the money arrived. You cannot see who sent it, what authorized them to send it, or whether you should keep it or return it.

That is the current state of AI-to-AI interactions.

An AI agent calls your API. It authenticates with a key. But the key tells you nothing about what the agent is supposed to be doing, who authorized it to make this call, what its scope is, or whether it has been revoked. You get the equivalent of a wire transfer with no sender information.

This is not a hypothetical problem. Astrix Security has disclosed that enterprises are finding thousands of shadow AI agents operating in their environments. Bessemer Venture Partners published a report saying that "action-level guardrails before any monitoring tool is turned on" is the defining security challenge of 2026. The industry knows the problem. Most builders are still shipping agents without any identity layer.

What RFC 8615 solved for the web, and what it can solve for agents

The IETF standardized the .well-known/ URI path in RFC 8615. The idea was simple: any server that wants to publish metadata about itself puts that metadata at a predictable URL under .well-known/. No custom paths, no guessing, no documentation hunting.

OAuth 2.0 adopted it for authorization server metadata at .well-known/oauth-authorization-server. ACME (the protocol behind Let's Encrypt) uses .well-known/acme-challenge/. WebFinger uses .well-known/webfinger. Today, if you want to know what a server supports for identity or authorization, you know exactly where to look.

AI agents need the same thing.

When an agent calls your system, you should be able to answer three questions: who is this agent, what is it authorized to do, and how do I verify those claims? Not by asking the agent itself. Not by trusting the API key alone. By fetching a standardized endpoint that tells you.

That endpoint is .well-known/oap/.

What the spec now defines

The Open Agent Passport spec now defines a discovery document served at https://{agent-host}/.well-known/oap/. Here is what a minimal document looks like:

{
  "oap_version": "1.0",
  "agent_id": "agt_k7m2x9p4r",
  "issuer": "https://aport.io",
  "passport_endpoint": "https://aport.io/passport/agt_k7m2x9p4r",
  "authorization_endpoint": "https://aport.io/authorize",
  "revocation_endpoint": "https://aport.io/revoke",
  "scopes_supported": ["read:files", "write:calendar", "send:email"],
  "signing_keys_uri": "https://aport.io/.well-known/oap/jwks.json"
}

Any system that receives a request from an agent can fetch this document, verify the agent's claims against a signed passport, and check the revocation endpoint before allowing the action to proceed. That is pre-action authorization built on a verifiable identity layer.

The merge also includes the IANA registration draft (D-008), which is the formal path to registering .well-known/oap as a recognized URI suffix. That registration process matters: without it, the path is a convention. With it, it becomes infrastructure.

Why this is different from just adding a header

Some frameworks already include agent identity in HTTP headers. The approach makes sense as a first step. It breaks down in two ways.

First, the agent self-reports. You trust the header because the agent sent it, not because a third party verified it. A compromised agent or a prompt-injection attack can supply any header value.

Second, there is no schema. "X-Agent-ID: my-agent-v2" tells the receiving system nothing verifiable. You cannot check scope. You cannot verify revocation. You cannot look up the signing key. It is identification without identity.

The .well-known/oap/ document is served by the host that issued the passport. The signing key lives at a URI the agent didn't supply. The revocation endpoint is not under the agent's control. This is the same principle that makes SSL certificates trustworthy: the authority sits outside the entity being verified.

How to add this to your service in 30 minutes

If you run any service that hosts an AI agent, you can implement this today.

Step 1: Create the discovery document

Create a static JSON file at public/.well-known/oap/index.json (or equivalent for your stack):

{
  "oap_version": "1.0",
  "agent_id": "your-agent-id",
  "issuer": "https://your-domain.com",
  "scopes_supported": ["read:data", "write:messages"],
  "contact": "security@your-domain.com"
}

Step 2: Serve it at the right path

For Express/Node:

app.use('/.well-known/oap', express.static('public/.well-known/oap', {
  setHeaders: (res) => {
    res.setHeader('Content-Type', 'application/json');
    res.setHeader('Access-Control-Allow-Origin', '*');
  }
}));

Step 3: Register with APort for signed passports

The static document is a start. For signed, verifiable identity, register your agent at aport.io. The issuer field becomes an externally verifiable claim, the passport endpoint holds a signed attestation, and revocation is handled for you.

That is the full trust chain: static document for discoverability, signed passport for verifiability, revocation endpoint for control.

What the discovery document does not do

This is not a replacement for authentication. Your API keys, OAuth tokens, and existing auth layers still matter. The .well-known/oap/ discovery document sits on top of authentication, not instead of it.

This is not magic. A discovery document alone does not stop a bad actor from claiming any agent_id they want. The security comes from the signed passport and the issuer verification chain. The discovery document is the address. The passport is the ID.

The use case reaches past external-facing APIs. Internal agent-to-agent calls have the same identity problem. If your orchestration agent spins up five sub-agents, how does each one verify the others' scope before taking an action? .well-known/oap/ works for internal service meshes too.

Why identity is the foundation

My experience building identity infrastructure for payments at Chimoney has shown me that identity is always the foundational problem. Before you can do anything else at scale, you need a way to answer: who is this, are they who they say they are, and are they authorized for this specific action? Payments solved this with account numbers, SWIFT codes, and correspondent banking relationships. The web solved it with SSL and IANA registrations. AI agents are at the same inflection point right now.

The patterns exist. RFC 8615 is proven infrastructure. The IETF and IANA process that gave us .well-known/oauth-authorization-server can do the same for .well-known/oap. What needed to happen was for someone to write the spec, register the path, and ship the implementation.

That is what this merge does.

It is a small pull request. It will matter at a large scale.

Resources

What's your setup?

Does your current agent setup have any way for another system to discover what it's authorized to do, without asking the agent itself? Are you relying on API keys alone, adding custom headers, or has your team started building toward a discovery layer?