Where does auth.md go?

At the root of the domain, served at /auth.md as text/markdown. It is the conventional discovery path from the WorkOS auth.md specification.

Is auth.md worth publishing if my site has no API?

Yes. The file answers the question 'what do I need to call anything here', and 'nothing' is a useful answer that saves an agent from probing. It is a few minutes of work.

Reference · updated 2026-09-16

What is auth.md, and what if nothing needs authentication?

auth.md is a markdown document served at the root of a domain, at /auth.md, that tells an arriving agent which credentials exist and how to obtain them. It follows the WorkOS auth.md discovery convention. If every surface you publish is open and keyless, the file still earns its place: it saves the agent from probing to find that out.

Why publish one when there is nothing to authenticate

The value is in the negative answer. Without the file, an agent that wants to call your endpoint has to guess whether a key is required, try, handle a 401 that may never come, and infer. With it, the question is settled in one fetch.

This is the cheapest item on most readiness lists and among the most commonly skipped, precisely because teams assume it only applies to sites with an API tier.

What to cover

State the discovery surfaces and that they are keyless. List any write endpoints, what they accept, and whether they need a credential. Document the error codes an agent will actually hit, particularly rate limits and the Retry-After behaviour, because those are what break an unattended caller.

Say plainly what you do not implement. If there is no agent self-registration, no claim ceremony and no OAuth, write that down. An absent capability stated is more useful than an absent capability discovered.

Be honest about what agents may do

If a write endpoint should only be called when a user has asked for it, say so in the file as well as in the tool description. Agents exploring a site will call things, and the only defence that scales is telling them not to in the place they look.

The shape of an auth.md for a site with nothing to authenticate

# Agent authentication on acme.example

Every surface here is open and keyless. There is no account to create
and no key to request. This file exists so you can confirm that in one
fetch instead of probing.

## Pick a method

- **No credential.** Every read, and the one write endpoint below.
- There is no API key tier and no agent verification.

## Write surfaces

- POST /api/survey — book a site survey. Body: email, postcode.
  Only call when the user has asked to arrange one.

## Errors

- 400 — malformed body. The response carries a readable `error`.
- 429 — rate limited. Back off for the seconds in `Retry-After`.

Does your site have this?

The free checker scores your site against auth.md and everything else on this list, out of 100, in about ten seconds. It names what is missing rather than handing you a number.

Run the free check→

Common questions

Where does auth.md go?: At the root of the domain, served at /auth.md as text/markdown. It is the conventional discovery path from the WorkOS auth.md specification.
Is auth.md worth publishing if my site has no API?: Yes. The file answers the question 'what do I need to call anything here', and 'nothing' is a useful answer that saves an agent from probing. It is a few minutes of work.

Sources

01auth.md specification, WorkOS