An agent reaching a protected API needs more than a sign-in link. It needs instructions for the registration process the service supports, including where a person must intervene and which metadata identifies the relevant endpoints.
WorkOS's auth.md convention puts those instructions in a Markdown guide. It is vendor-authored guidance, not a universal web standard. Its useful role is to explain the process while leaving endpoint configuration and access decisions to the mechanisms that own them (WorkOS, "The auth.md file").
WorkOS describes a guide, not the authority for endpoints
WorkOS describes auth.md as one Markdown file that an application publishes at its service root to tell agents how to register. The same documentation says Protected Resource Metadata remains the authoritative source for endpoint URLs and supported flows, while auth.md is the prose companion that points back to it (WorkOS, "The auth.md file").
That is a useful convention. It gives a service a place to explain the human-readable parts of agent registration. It does not turn the Markdown document into the thing that authorizes requests.
The reference flow separates instructions from credentials
The WorkOS reference implementation keeps the same separation. Its README labels AUTH.md as a sample guide that the agent service would host. The operational flow is elsewhere: registration and credential issuance are split across endpoints. POST /agent/identity returns an identity assertion, and the agent later exchanges that assertion at POST /oauth2/token for an access token (WorkOS, "workos/auth.md README").
That sequence is the important part. The guide tells an agent what to do. A later endpoint response may produce a credential. A later protected API call may prove that the credential was accepted. A guide should explain these transitions clearly so a client knows which step it has reached.
The sample AUTH.md makes the sequence explicit. It tells an agent to discover metadata, register, handle any claim step, exchange for an access token, call the API, and handle revocation in order. It also distinguishes the guide URL from the token endpoint where an assertion is exchanged for an access token (WorkOS, "sample AUTH.md").
What MachineRead checks
With the auth.md family enabled, MachineRead probes /auth.md and /.well-known/auth.md. It looks for a nontrivial document with basic Markdown or authentication-related text. The strict-readiness and report-row checks use slightly different text screens; neither validates the complete procedure described by WorkOS.
A finding means a candidate guide was observed at a sampled path. It does not mean registration or token exchange succeeded. Read the document before following it, especially where it requests credentials, directs a client to another host, or asks a person to approve access.
How to read an auth.md finding
Follow the instructions on paper before testing them. For each step, identify who acts, which endpoint they contact, what they submit, and what response allows the next step to proceed. The guide should make human approval steps explicit rather than leave the client to improvise.
For example, if the prose names a token endpoint that differs from the authoritative metadata, resolve the disagreement before sending credentials. WorkOS's convention gives metadata authority over endpoint configuration; copying endpoint URLs into several documents creates a maintenance obligation (WorkOS, "The auth.md file").
Test registration and access only with the service owner's authorization and appropriate test credentials. A useful guide should help you understand a refusal or revocation as well as a successful path. None of those operational results follows merely from finding the Markdown file.
Works Cited
WorkOS. "The auth.md file." WorkOS, https://workos.com/auth-md/docs/auth-md. Accessed 9 Sept. 2026.
WorkOS. "sample AUTH.md." GitHub, https://github.com/workos/auth.md/blob/main/AUTH.md. Accessed 9 Sept. 2026.
WorkOS. "workos/auth.md README." GitHub, https://github.com/workos/auth.md. Accessed 9 Sept. 2026.
See also
- Methodology reference - separates observed documents from runtime guarantees
- What OAuth discovery metadata actually publishes - a related metadata-versus-access boundary
- What an A2A agent card is for - another document that should not be promoted into runtime proof