Auth.md and OAuth Metadata for AI Agent Authentication

AI agents can read public pages without an account. The moment they need to retrieve a private invoice, create a support ticket, change a subscription, or call a protected API, discovery becomes an identity and permission problem.

The right response is not to publish a vague “agents welcome” page or ask people to hand an agent a password. Make the boundary explicit: what is public, what needs user consent, where the authorization server lives, and which protected resource the client is trying to use.

This guide turns the Auth.md and OAuth Metadata wiki entry into a practical rollout workflow. It sits beside API Catalog SEO, MCP Server Card, and the wider Agent SEO audit.

Separate The Two Layers

OAuth metadata and auth.md are related to agent access, but they are not interchangeable.

Layer	What it answers	Current status	Publish it when
OAuth authorization server metadata	Where are the issuer, authorization endpoint, token endpoint, keys, and supported scopes?	IETF standard: RFC 8414	You operate an OAuth authorization server
OAuth protected resource metadata	Which authorization servers, scopes, and policies apply to this resource?	IETF standard: RFC 9728	You expose an API or other protected resource
auth.md	How may an agent register for a service on a user’s behalf?	Emerging project protocol, not an IETF standard	You intentionally support its registration flows
Human-facing auth documentation	What can a person authorize, revoke, and escalate?	Product documentation	Always, when a protected workflow is public

The distinction matters. An experimental registration convention is not a substitute for OAuth configuration, consent, scopes, or access controls. Conversely, a standards-based metadata file does not explain a product’s agent-specific onboarding policy.

The auth.md project describes a hosted AUTH.md file as instructions for participating agents and includes service and agent-provider examples. Treat it as a compatibility choice, not as a universal signal that every crawler or AI assistant will understand.

Start With The Resource, Not The Agent

For most teams, the first question is not “How will an AI agent sign up?” It is “What resource are we prepared to let an authorized client access?”

Build a simple access inventory before publishing metadata:

Inventory field	Example	Why it matters
Resource	https://api.example.com/v1/invoices	Prevents a generic login page from standing in for a real service
User action	Read invoices, open a support ticket	Defines what consent must cover
Required scope	invoices.read	Keeps permissions narrow and reviewable
Authorization server	https://auth.example.com	Gives clients a trusted issuer to validate
Revocation path	Account security settings	Lets users withdraw delegated access
Owner and review date	Identity platform team, quarterly	Makes changes and deprecations accountable

Do not give an agent a broad account credential because it is convenient. Use least-privilege scopes, visible user consent, and a revocation path that a person can find without relying on the agent.

Publish The Standards-Based Discovery First

If you operate OAuth, publish and validate the standard metadata before adding an agent-oriented convention.

RFC 8414 defines authorization server metadata. A client can retrieve a JSON document from a well-known URL such as:

https://auth.example.com/.well-known/oauth-authorization-server

At a minimum, the document identifies the issuer and the authorization and token endpoints. It can also advertise key material, supported scopes, registration endpoints, and the methods accepted by the token endpoint.

RFC 9728 performs the complementary job for the protected resource. A resource can publish:

https://api.example.com/.well-known/oauth-protected-resource

The document can name the protected resource, associated authorization servers, supported scopes, user-facing documentation, and policy URLs. A 401 response can use the WWW-Authenticate header with resource_metadata to show a client where to find it.

Illustrative protected-resource metadata:

{
  "resource": "https://api.example.com/",
  "authorization_servers": ["https://auth.example.com"],
  "scopes_supported": ["tickets.read", "tickets.write"],
  "resource_name": "Example Support API",
  "resource_documentation": "https://docs.example.com/support-api",
  "resource_policy_uri": "https://example.com/api-policy"
}

This is discovery information, not an authorization decision. Your API must still validate tokens, enforce scopes, verify audience and issuer values, and apply its normal abuse controls.

Decide Whether auth.md Fits

Add auth.md only after you can answer these questions in writing:

• Do you have a real self-service workflow that an agent may initiate for a user?
• Which actions are allowed before user verification, and which require it?
• Can your product distinguish the agent, the user, and the service it is contacting?
• Do you provide a reviewable consent screen, account recovery, and revocation?
• Can you support these flows over time rather than expose a one-off experiment?

If any answer is no, keep the discovery layer to OAuth metadata and normal documentation. A content site, a brochure site, or a product that only accepts human-created accounts does not need auth.md merely to appear agent-ready.

When it does fit, make the AUTH.md document honest and narrow. Link it to terms, privacy policy, user support, security contact, and the OAuth metadata that governs the protected resource. Do not expose credentials, internal endpoints, or instructions that bypass consent.

A Five-Step Rollout

1. Classify the service. Mark each surface as public content, protected read access, or protected action. Keep public documentation available without authentication where possible.
2. Define the smallest scopes. Name permissions around the action, not the entire account. Separate read and write scopes.
3. Publish OAuth metadata. Serve RFC 8414 authorization-server metadata and RFC 9728 protected-resource metadata from the correct well-known URLs.
4. Document the human control plane. Publish support, policy, consent, and revocation paths where people and clients can find them.
5. Add auth.md only for supported flows. If your service supports it, publish a maintained AUTH.md and test the registration journey with a non-production account.

This order starts with interoperable OAuth configuration, then adds product-specific agent registration only where the product can own the outcome.

Validate The Live Flow

curl -i https://auth.example.com/.well-known/oauth-authorization-server
curl -i https://api.example.com/.well-known/oauth-protected-resource
curl -i https://api.example.com/v1/tickets

Check	Pass condition
HTTPS and issuer	Metadata resolves over HTTPS and the issuer matches the expected authorization server
JSON and content type	Documents return valid JSON with an appropriate response type
Resource-to-server match	The protected resource lists only authorization servers it actually trusts
Scope review	Scopes are narrow, documented, and mapped to real API enforcement
Unauthorized response	A protected request returns a useful 401 challenge without exposing secrets
User control	Consent, revocation, support, and security paths are visible and usable
Protocol claims	auth.md is described as an optional supported integration, not an SEO or access guarantee

Bot Simulator and Technical SEO can help ensure the surrounding public documentation is reachable and readable. They cannot certify that your authorization design is safe; test the real flow with identity, product, and security owners.

Common Mistakes

Avoid publishing OAuth metadata for a resource that does not enforce OAuth, listing broad permissions where action-specific scopes are possible, or treating an agent-registration document as permission for high-impact autonomous actions.

Do not hide consent or revocation behind an opaque account flow. Keep AUTH.md aligned with the live OAuth issuer, endpoints, and policies. Do not claim that metadata improves Google rankings, AI citations, or universal agent compatibility.

OAuth security guidance recommends publishing authorization-server metadata and using it for client configuration when available. That baseline still does not remove the need for redirect URI handling, token validation, phishing defenses, and permission review.

The Next Action For Fennec Users

1. Confirm the protected action is legitimate, user-authorized, and reversible.
2. Publish current documentation; connect it to API Catalog SEO or an MCP Server Card only if those surfaces are real.
3. Validate RFC 8414 and RFC 9728 metadata from the live domain.
4. Run the public discovery surface through Agent SEO Audit and Bot Simulator.
5. Consider auth.md only after the OAuth and user-control layers are reliable.

For content-only sites, keep the simpler foundations healthy: robots.txt, a current sitemap, helpful internal links, and useful public pages. Authentication metadata is not a substitute for those basics.

Sources

• RFC 8414: OAuth 2.0 Authorization Server Metadata
• RFC 9728: OAuth 2.0 Protected Resource Metadata
• RFC 9700: Best Current Practice for OAuth 2.0 Security
• RFC 8628: OAuth 2.0 Device Authorization Grant
• auth.md reference implementation and protocol project

Q&A

Does auth.md replace OAuth?

No. auth.md is an emerging agent-registration protocol. OAuth metadata and protected-resource metadata remain the standards-based way to expose authorization-server and protected-resource configuration.

Should a content-only website publish OAuth metadata?

Usually not. Publish OAuth metadata when you operate a real authorization server or protected resource. Content sites should focus first on crawlability, clear documentation, and ordinary technical SEO.

Does authentication metadata improve AI search rankings?

No. It can reduce ambiguity for compatible clients that need to access a real protected service, but it does not guarantee indexing, rankings, citations, or agent adoption.