Skip to content

TRX-009Buy

auth.md agent registration guide published

Checks whether your shop publishes an auth.md file telling agents how to register or sign in on a customer's behalf.

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 (a host answering every .md path with another 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. Make sure 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