+1 capabilitybadge capabilities from 1 to 2
Publish an auth.md for agents
No /auth.md published.
Read prompt
My website goodforbots.com scored 100/100 on Good for Bots (Excellent). Good for Bots measures one thing: whether a language model can read a site and cite it.
The capability it is missing is "Publishes an auth.md for agents". It carries no points at all: a capability is recorded as a badge on the report and never touches the score. What the scanner saw: No /auth.md published.
I need you to: publish an auth.md telling agents how to authenticate with this service. Here is what that means.
An agent that wants to call this project's API on a user's behalf has no way to find
out how, unless a person tells it first or the site says so itself at a predictable
address. That is what `auth.md` is for: one markdown file, at the site root, that
takes an agent from "I want to call this API" to a working credential without a human
in the loop.
`auth.md` is a convention published by WorkOS in May 2026, not a standard: it has no
version and no conformance criteria, so there is no such thing as a file that formally
conforms. What it points at is specified (RFC 9728 for protected-resource metadata
and RFC 8414 for authorization-server metadata), and that is the part worth getting
right.
Serve a markdown document at `https://goodforbots.com/auth.md`. It must:
- address an agent directly, in the second person, and say what credential this
service issues;
- link the protected-resource metadata at
`https://goodforbots.com/.well-known/oauth-protected-resource`, which names the authorization
server;
- link the authorization-server metadata at
`https://goodforbots.com/.well-known/oauth-authorization-server`, which carries the endpoints and
the supported registration methods;
- say how an agent picks up a credential it already has, in priority order, and where
to send the user when it has none;
- say how the agent knows a credential has been revoked, which is almost always a 401
on one that previously worked.
A minimal file that does the job:
```
# auth.md
You are an agent that wants to call the Example API on a user's behalf.
Discovery is two hops. Fetch the protected-resource metadata at
https://goodforbots.com/.well-known/oauth-protected-resource, which names the authorization
server in `authorization_servers`. Then fetch
https://goodforbots.com/.well-known/oauth-authorization-server for the endpoints and the
registration methods this service supports. If anything below disagrees with the
protected-resource document, that document wins.
Present the issued credential as a bearer token:
Authorization: Bearer <credential>
Read it from the environment or a secret store at the moment of the call. Never ask
the user to paste a credential into a chat transcript, and never print it in logs,
commits, pull requests or error reports.
A 401 on a credential that previously worked means it was revoked. Drop it and start
again at discovery rather than retrying.
```
If this service does not issue credentials to agents yet, say exactly that, and point
at what does work today: an MCP server, a CLI that handles auth itself, or a
dashboard where the user mints a key by hand. A file that honestly says "not yet, use
this instead" is worth publishing; it stops an agent guessing, which is the failure
the whole convention exists to prevent.
Two things to get right, because they are the common failure modes. First, make sure
the path is served by a real route: many frameworks answer every unknown path with the
application shell, which returns 200 and HTML, and an agent gets no signal that the
feature is absent. Second, do not let an unrelated page occupy the address: a site
that mirrors its documentation to markdown and happens to have a page about
authentication will serve it at `/auth.md`, and an agent following the convention
lands on a product description instead of instructions.
Two places where this scan deliberately reads the convention loosely, so you are not
surprised by what it accepts. The WorkOS documentation describes an H1 reading
`# auth.md` and nine named sections; this check requires neither, because the largest
real implementations use their own headings and none carries the full set, and
failing them would say something untrue about those sites. In exchange, the badge is
awarded for linking the two metadata documents rather than for resembling the
template, because those have specifications behind them and the template does not.
If this project has no API that an agent could call, skip this entirely. There is
nothing to declare, and an `auth.md` describing a service that issues no credentials
is worse than none at all. Nothing is lost by not having one.
The whole report, as markdown, is at https://goodforbots.com/r/goodforbots.com.md?scan=cmuo0n1du000101nrbtiif2ar. Read it first: this prompt covers one finding, and the report has everything the scan saw.
When you are done, summarise what you changed and how to check it against a running instance. Do not try to run the Good for Bots scan yourself: it only sees what is already deployed, it is rate-limited, and re-running it is the site owner's call once the change ships.
