auth.md

What is auth.md?

auth.md is an open protocol (launched by WorkOS in May 2026) for registering AI agents with web services. An application publishes a markdown file at /auth.md that tells an agent how to register: which flows are supported, which scopes exist, and which endpoints to call. The file is readable by both humans and agents.

# Agent registration

## Supported flows
- Agent Verified — provider attests the user's identity
- User Claimed — register first, user confirms via OTP

## Scopes
- read:profile
- write:orders

## How to register
POST https://api.example.com/agents/register
OAuth metadata: /.well-known/oauth-protected-resource

Why do you need auth.md?

For decades, registration was built for humans: forms, CAPTCHAs, email confirmations, OAuth consent screens. Agents break that assumption — they need their own machine-readable path, not an imitation of browser clicks.

auth.md provides one by composing existing standards (OAuth Protected Resource Metadata, RFC 9728, and identity assertions) rather than introducing a new “walled garden.” The protocol is open: any app can publish an auth.md and any agent can read it, with no WorkOS account required. The application stays in control: it decides which flows to accept and what access to grant.

How do you implement auth.md?

Publish a markdown file at the domain root with Content-Type: text/markdown (or text/plain). Contents (the protocol has no strict JSON schema — these are markdown conventions):

Section	Purpose
Flows	Agent Verified and/or User Claimed
Scopes	which permissions an agent may request
Registration	endpoint and method (register_uri)
OAuth	link to /.well-known/oauth-protected-resource

Optionally, an agent_auth block in /.well-known/oauth-authorization-server with register_uri, identity and credential types, and claim/revocation URLs.

How do we check auth.md?

The scanner performs a GET request to /auth.md and verifies it looks like a real auth.md rather than an HTML placeholder:

• HTTP status 200 and a non-empty body;
• it is not an SPA fallback (HTML instead of markdown);
• protocol markers are present (flows, scopes, registration, OAuth).

The auth_md check is informational: its absence does not lower your score (the protocol is young), but its presence is a bonus for early adoption. The scanner does not perform the registration flow itself.