What is auth.md?

The problem it solves

OAuth 2.0 was written for a person sitting at a browser. The redirect, the Approve button, the callback URL, all of it assumes a human clicking. That model does not survive the agent era. When an agent goes to book a flight, file an expense, or open an account, there is no browser open and nobody there to click. Today most sites either block agents outright or force them through fragile browser automation that breaks the moment a page rerenders.

auth.md keeps OAuth’s semantics and adds two flows that fit how agents actually work. One skips the browser entirely by leaning on a signed assertion from the agent provider. The other pins identity verification to a short interactive step, similar to how a smart TV asks you to visit a URL and type a code.

Where the file lives

An agent looking to register hits /.well-known/auth.md at your domain. That file describes what the service is, what scopes it exposes, which agent providers it trusts, and where the registration and token endpoints live. Alongside it, RFC 9728 protected resource metadata lives at /.well-known/oauth-protected-resource and points at the OAuth authorization server. Between those two files an agent has everything it needs to attempt a registration.

Flow 1: Identity assertion (ID-JAG)

The agent provider (OpenAI, Anthropic, Cursor, whichever LLM host the user is signed into) signs a short-lived JWT that asserts the user authorized this specific agent to act on their behalf. The JWT format is called ID-JAG, short for Identity Assertion JWT Authorization Grant, and it’s an IETF draft.

Your service receives the ID-JAG, verifies its signature against a trust list of accepted providers, and exchanges it for an access token at /oauth2/token. No browser opens. No user prompt. If your product already provisions users just-in-time from OIDC or SAML, this flow slots in cleanly, since you’re already used to trusting a signed identity claim from an external IdP.

The trust list is the security-critical part. Only providers you explicitly accept can assert user identity to your service. Add Anthropic and you accept every Claude that registers. Add OpenAI and you accept every ChatGPT agent. That’s the whole risk model.

Flow 2: Browser claim ceremony

When the ID-JAG flow doesn’t fit, either because you don’t trust any of the agent providers who could sign one, or because your product needs the user to complete some human step (accept terms, choose a workspace, pass MFA), auth.md falls back to a claim ceremony modeled on RFC 8628, the device authorization grant.

The agent gets a code, hands the user a URL and that code, and waits. The user visits the URL in a browser, does whatever verification your service requires, and the agent then completes the token exchange. Two variants exist: an anonymous entry point where the agent asserts identity first and the user claims that identity later, and a service_auth entry point where verification must happen before a token is issued at all.

The building blocks

auth.md is not a brand-new spec invented from scratch. It composes existing standards, which is a big part of why WorkOS was able to ship it with real launch partners this fast.

auth.md vs standard OAuth

The most common question about auth.md is what it changes about OAuth. The short answer: nothing at the wire level. You still exchange tokens at /oauth2/token. Scopes still mean what they mean. Access tokens still look like access tokens.

What a service needs to implement

If you want your SaaS product to be usable by AI agents through auth.md, you need:

1. An auth.md file at /.well-known/auth.md describing your service, scopes, and registration endpoints.
2. RFC 9728 protected resource metadata at /.well-known/oauth-protected-resource, pointing at the authorization server that protects your API.
3. A trust list of agent providers whose ID-JAG assertions you accept, and the code to verify their signatures.
4. A token endpoint that accepts either an ID-JAG grant or a device-code-style exchange and issues access tokens.
5. A claim UI if you support the browser flow, where users complete verification after entering the code the agent gave them.

WorkOS ships this as a hosted product for teams that don’t want to build the trust-list plumbing themselves. Cloudflare integrated it into their Zero Trust identity stack. Firecrawl uses it to let agents register directly for scraping accounts.

Why this matters now

The interesting bet inside auth.md is that agent providers become de-facto identity providers. If your service accepts an Anthropic-signed ID-JAG, you’re treating “this user is signed into Claude” as a valid identity assertion, the same way you might trust “this user signed in with Google.” That’s a real change in who sits in the identity graph.

Whether it becomes the standard or gets absorbed into something IETF publishes is an open question. The composition of RFC 9728 plus ID-JAG plus a discovery file is sensible, and the launch partners are the ones who actually route agent traffic. For a SaaS builder deciding today whether to invest, the safer bet is that agent-native auth in some form is coming, and the file-at-a-well-known-URL pattern is going to survive whichever name wins.

Related specs

• MCP Model Context Protocol, how agents connect to tools once they’re authenticated.
• SKILL.md packaging domain expertise so agents know how to use a service.
• AGENTS.md baseline project instructions for AI coding agents.
• llms.txt making your documentation discoverable to AI models.