auth.md: a native registration path for agents

What it is

auth.md is an open protocol (launched by WorkOS in May 2026) that gives AI agents their own registration path into a service. Instead of imitating a human — clicking through forms, solving CAPTCHAs, confirming emails — an agent reads a single markdown file at /auth.md and learns: which registration flows are supported, which scopes exist, and which endpoints to call.

The file is readable by both humans and agents. The protocol invents no new cryptography — it composes existing standards: OAuth Protected Resource Metadata (RFC 9728) and identity assertions. The application stays in control: you decide which flows to accept and what access to grant.

Why it matters for AI agents

For twenty years onboarding was built for a human behind a browser. Agents break that assumption: they need a predictable machine path, not a “brittle browser-automation hack.” auth.md answers an agent’s three questions: how do I register, which scopes can I request, how do I prove the user approved this.

Two primary flows:

• Agent Verified — the agent’s provider (a platform you trust) attests the user’s identity; the service verifies it and returns credentials. No email round-trips.
• User Claimed — the agent registers first, then the user confirms it with a one-time code (OTP). Works even where the agent platform can’t yet attest identity — a fit for MCP servers, custom agents, and scripts on top of LLM APIs.

Minimal working example

GET /auth.md HTTP/1.1

# Agent registration

This service supports agent registration via the auth.md protocol.

## Supported flows
- **Agent Verified** — your agent provider attests the user's identity.
- **User Claimed** — register first, the user confirms with an OTP code.

## Scopes
- `read:profile` — read the user's public profile
- `write:orders` — create orders on the user's behalf

## How to register
POST https://api.example.com/agents/register

OAuth metadata: /.well-known/oauth-protected-resource

Serve the file with Content-Type: text/markdown (or text/plain) at the site root, alongside an existing /.well-known/oauth-protected-resource.

Right vs wrong

Right	Wrong
/auth.md at the domain root	File buried in a subdirectory
Real markdown with flows/scopes	SPA serves index.html on every path
Links to /.well-known/oauth-protected-resource	Registration described, but no OAuth metadata
Concrete scopes and endpoints	”Contact us” instead of a machine path

Common mistakes

• SPA fallback. A client-routed site returns 200 OK and an HTML page at /auth.md. To an agent that isn’t an auth.md — serve real markdown.
• The file exists but is empty of meaning — without flows, scopes, and endpoints there’s nothing for an agent to act on.
• No OAuth linkage. auth.md builds on RFC 9728 — without /.well-known/oauth-protected-resource the authorization chain breaks.
• Human-only registration. If the only path is a web form with a CAPTCHA, the agent is still locked out.

How to verify

Our scan fetches /auth.md and checks that it looks like a real auth.md rather than an HTML placeholder. Manually:

curl -s https://example.com/auth.md | head -40

Expect markdown describing the registration flows, scopes, and endpoints. The auth_md check is informational: its absence does not lower your score (the protocol is young), but early adoption is an edge while competitors still imitate clicks.