Two files called auth.md, and they disagree on the field names
2026-09-04
WorkOS shipped Agent Auth for AuthKit on 2 September, a way to give the agents you build into your own product short-lived scoped tokens instead of a long-lived API key. Next to it in the same product menu sits something else with a wider blast radius, and it is a month older: an open protocol called auth.md, shipped into AuthKit on 4 August, in which a service publishes a markdown file at its own root telling outside agents how to register on behalf of a user. This site has served a file at that same address since June. The two are not the same document, I read both on 4 September to find out how far apart they are.
What each document asks for
The scanner this site is measured by publishes its own recipe for the check it calls authMd, at https://isitagentready.com/.well-known/agent-skills/auth-md/SKILL.md, which answered 200 with 2 112 bytes. It asks for a markdown file at the service root with an H1 containing auth.md, protected resource metadata carrying resource, authorization_servers, scopes_supported and bearer_methods_supported, and an agent_auth block in the authorization server metadata. It names that block's fields: skill, register_uri, claim_uri, revocation_uri, identity_types_supported, identity_assertion.assertion_types_supported and anonymous.credential_types_supported.
The WorkOS file format at https://workos.com/auth-md/docs/auth-md asks for the same two-hop discovery walk and the same agent_auth block. It names the block's fields identity_endpoint, claim_endpoint and events_endpoint.
So the two documents agree on the path, the file name, the H1 and the discovery order, and they nearly agree on the protected resource metadata: the scanner asks for four fields in it and WorkOS for those four plus resource_name. They disagree on what to call the registration endpoint, the claim endpoint and the revocation surface inside the block both of them require.
Why that is worth knowing before you implement
A site built from the scanner recipe and a site built from the WorkOS specification both serve a file called auth.md at the root, both publish an agent_auth block, and both can be described as having implemented auth.md. An agent that fetches one and looks for the other's field names finds nothing where it expects an endpoint. Nothing in either document warns you, because each is internally complete and neither cites the other.
The gap is easy to walk into in one direction in particular. If you build against the specification and then test with the scanner, the check reports the file as missing rather than as differently named, and the natural reading of that result is that the file is not being served.
What this site does
This site follows the scanner's naming, because that is what was measurable when the file was written and because a rename would drop a check this site's own score rests on. The file is at https://turva.dev/auth.md, served as text/markdown, and the protected resource metadata carries all five fields the WorkOS discovery step names.
What this site does not implement is both of the WorkOS ceremonies. Agent verified needs an identity provider to vouch for a user, and user claimed needs a device-code confirmation. Neither exists here for the same reason: there are no user accounts, every resource is public and read only, and nothing on the domain answers 401, so there is no challenge for an agent to bootstrap from. The file now says that in its own words rather than describing a flow that is not there, and it names the protocol so a reader can see the difference for themselves.
The word claim is its own trap. On this site it means proving control of an identifier you already corresponded under. In the protocol it means a ceremony where the agent shows the user a code to confirm in a browser. Same word, two mechanisms, and the file now separates them.
What I am not claiming
I have no view on which naming should win, and this is not a prediction that either one becomes a standard. I did not measure how many sites serve an auth.md of either kind, so nothing here says which is more common. What I read is two published documents on one day, and what I can show is that they name the same three positions differently. Anyone implementing from one and verifying against the other will find that out the hard way, and it seemed worth writing down before more sites are built either way.
Frequently asked
Is auth.md a standard?
No. It is a convention published by two parties who do not agree on the field names inside it. The underlying pieces it composes are standards, OAuth protected resource metadata in RFC 9728 and authorization server metadata in RFC 8414, and those two are the parts an agent can rely on today.
Which field names should I use?
That depends on what will read your site. If a scanner grades you, use the names its recipe publishes and verify with the scanner. If a specific agent platform will consume the file, use the names its specification publishes. There is no third answer that satisfies both, and the honest thing is to say in the file which one you followed.
Does a site need an auth.md at all?
Only if an agent could ever need permission to do something there. A site that is entirely public and issues no credentials can publish one to say exactly that, which is what this site does, but there is nothing dishonest about not having the file when there is nothing to authenticate.