Auth.md and OAuth Metadata
Auth.md and OAuth metadata help AI agents understand authentication, authorization servers, protected resources, scopes, and consent boundaries.
Auth.md and OAuth Metadata
“Auth.md” is an informal label for a human-readable authentication guide. It is not an IETF standard, registered well-known URI, or replacement for OAuth discovery. OAuth metadata is the standardized layer that lets clients locate authorization servers and understand protected resources.
For agent-ready websites, the important principle is simple: do not make agents guess your auth model.
Separate documentation from protocol metadata
| Layer | Audience | Suitable content |
|---|---|---|
| Product documentation | Humans and agent developers | Sign-in flow, consent expectations, examples, support and security contacts |
| Authorization server metadata | OAuth clients | Issuer, authorization endpoint, token endpoint, supported grants and signing methods |
| Protected resource metadata | OAuth clients | Resource identifier, authorization servers, supported scopes and bearer-token methods |
Do not copy secrets, client credentials, private endpoints, or access tokens into any public Markdown or metadata document.
What to Document
- Whether public resources require no auth
- Which workflows require user consent
- OAuth authorization server metadata
- Protected resource metadata
- Supported scopes
- Token audience and issuer expectations
- Human support or security contact
SEO and Product Guidance
Authentication metadata matters when agents move beyond reading pages and start acting for users. A product website may let an agent retrieve invoices, compare plans, open a support ticket, or start checkout. Those workflows need explicit consent and clear boundaries.
Keep public content public. Keep private workflows behind user-approved authorization. Authentication establishes who or what is acting; authorization determines what that actor may do. A useful guide should not collapse the two.
Implementation sequence
- Publish RFC 8414 authorization-server metadata under the issuer’s documented well-known location.
- Publish RFC 9728 protected-resource metadata for APIs that need clients to discover their authorization servers and scopes.
- Validate issuer, audience, redirect URI, PKCE, scope, token lifetime, and revocation behavior in the actual client flow.
- Add readable documentation only after the machine-readable endpoints are correct.
- Version examples and record a security contact and review date.
An agent-readable index can link to these endpoints, but should not invent a parallel authentication protocol.
Failure modes
- An authorization-server issuer does not exactly match the issuer returned in metadata.
- A protected resource accepts a token intended for another audience.
- Documentation lists broader scopes than the consent screen or API enforces.
- A public discovery file exposes internal hostnames or operational secrets.
- A workflow lets an agent perform a consequential action without fresh user confirmation.
Test negative cases as deliberately as the happy path: expired tokens, wrong audience, missing scope, revoked consent, and replayed requests should fail predictably.