auth.md agent registration guide published

What we check

auth.md is a convention from WorkOS, not an IETF or W3C standard, with no published version. It is a Markdown file hosted at your domain, typically /auth.md, that "tells agents how to register on behalf of a user": how to discover your authorization server, which registration methods you support, and how to use the resulting credentials. We check that /auth.md exists, is a Markdown document rather than your storefront page, and opens with a heading that names auth.md.

Why it matters

Some agents need an account or API credentials with your shop to act for a customer, for example to track orders or manage returns. A published guide lets them follow your intended process instead of improvising or giving up. For a shop where agents never need to create accounts or credentials, this is optional.

How we check

We request /auth.md once, and never call the registration endpoints it describes, because registering can create accounts or issue credentials. PASS when it answers 200 with a non-HTML body whose first top-level heading (a line starting "# ") contains "auth.md", served as text/markdown or text/plain. WARN when there is no top-level heading, when the first heading does not name auth.md (as when a host answers every .md path with some other page), or when the media type is different. FAIL on 404 or 410, or when /auth.md returns your site's HTML page. We SKIP when the request is bot-blocked, disallowed by robots.txt, or answered with another non-200 status such as 429, 5xx or an unexplained 403.

How to fix it

1. Only act on this if agents may create accounts or API credentials on a customer's behalf.
2. Publish /auth.md as text/markdown, opening with "# auth.md", and describe discovery, the registration methods you support and how credentials are used.
3. If you publish /.well-known/oauth-authorization-server, link the file from its agent_auth block.
4. Check that your platform or CDN does not rewrite /auth.md to your storefront's HTML; a static file served as-is is enough.

What good looks like

GET /auth.md
Content-Type: text/markdown

# auth.md

You are an agent. This service supports agentic registration:
discover -> register -> exchange for an access_token -> call API.

## 1. Discover
Read /.well-known/oauth-protected-resource, then
/.well-known/oauth-authorization-server.

## 2. Pick a method
identity_assertion, service_auth or anonymous.

## 3. Register
...

Sources

• WorkOS auth.md
• auth.md reference repository