# 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.

```markdown
# 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.

[← All glossary terms](/en/glossary)