`auth.md`: The Markdown File That Teaches Agents How to Authenticate

A deep dive into WorkOS’s agent registration protocol, where discovery, step-up verification, and human claim ceremonies collapse into one file-shaped entry point.

9 min read • View on GitHub • More from workos

A lone agent stands beside a tall file cabinet marked AUTH.md. One drawer opens into a narrow path that leads to a locked service gate, with small signposts for discovery, verification, and human claim ceremony along the route. The scene explains the repo’s core idea: a Markdown file can act as the front door for agent registration. — `AUTH.md` is not just documentation. In this protocol, it is the discovery surface that tells an agent where to go next.

Key Takeaways

`auth.md` treats agent onboarding as a discovery problem, not a browser problem.
The protocol uses a Markdown file to bridge human instructions and machine-readable registration flow.
Its most important design choice is the step-up path, which hands control back to a human when trust is incomplete.
The repo composes existing standards instead of replacing them, which makes the proposal feel practical rather than speculative.

The strangest thing about `auth.md` is also the most useful. It takes a familiar documentation file and turns it into the place an agent starts when it wants to identify itself, register, and ask for access. That makes the repo feel less like a new auth system and more like a new front door for software that acts on behalf of people.

auth.md is an open protocol, authored by WorkOS, that enables AI agents to register for web services on behalf of users. It consists of a Markdown file published at a domain's root and a set of HTTP endpoints that agents use to discover, register, and authenticate — without requiring a browser, sign-up form, or OAuth consent screen.

WorkOS, Project Author · What is auth.md?

Why a Markdown File Became the Front Door

Browser-first auth assumes a person is clicking through a product UI. Agents do not want a maze of redirects and forms. They want a way to discover the right endpoints, understand the rules, and move forward with as little ambiguity as possible. `AUTH.md` is the repo’s answer: a file-shaped manifest that gives the agent a map before it ever touches the service.

A close-up of a folded map stamped AUTH.md bridging two shorelines. On one side are readable notes and endpoint labels. On the other side are machine symbols and locked service infrastructure. The image explains how the manifest translates human instructions into something an agent can follow. — The manifest is the bridge. Humans read it like documentation, while agents use it like a routing table.

The Protocol in One Sentence

This is the core shape of the protocol: discovery, branching trust paths, and a human checkpoint when the machine cannot prove the link on its own.

In plain English, the system has three parties: an agent, an agent provider, and a service. The agent discovers `AUTH.md`, reads the metadata, then picks a registration path. If trust is already established, the provider can mint an assertion. If not, the service can pause the flow and ask a human to step in. The interesting part is not the endpoint list. It is the way the protocol makes uncertainty explicit instead of pretending it does not exist.

How `AUTH.md` Turns Documentation into a Machine Interface

The repo’s novelty lives in the handoff between the file and the API surface. In `agent-services/src/routes/well-known.ts`, the service exposes well-known metadata, including an `agent_auth` block that points to the `skill` file. That turns a normal docs artifact into the thing an agent is expected to read first. It is a small move with a big consequence: the protocol gives machines a place to start that still makes sense to humans.

We're calling it Auth.md. Auth.md is a spec, not an IETF-ratified standard — please don't bring the pitchforks. It's a set of ideas that lets you expose your application to agents so they can register, sign up, and start using it. Not as spam. Not as a fake human. As an agent acting as a first-class user.

Michael Grinich, Founder of WorkOS · Introducing Auth.md

The Three Registration Paths

`agent-auth.ts` handles three routes into identity. One uses an ID-JAG assertion from a trusted provider. One starts from service-auth, which can verify the user through the service itself. One allows anonymous registration, then waits for claim later. That mix matters because it lets the system accommodate both confident identity and first contact that is too thin to trust yet.

Path	What it assumes	What happens next
ID-JAG assertion	A trusted provider can vouch for the agent	The service can register or link the identity immediately
Service auth	The service can verify the user directly	The flow continues through a verified service-side path
Anonymous registration	Nothing is proven up front	The service creates a pending identity that must be claimed later

The design is careful about what it does not assume. It does not require every agent to arrive with a known identity. It does not force every service to trust the same provider. Instead, it gives the system enough branching logic to accept known agents quickly and unknown ones safely.

Why the Claim Ceremony Matters

This is the repo’s most important product move. When the service cannot prove the link immediately, it returns `interaction_required` and sends the user into a claim ceremony. That is not a failure state. It is a deliberate pause. The protocol acknowledges that trust sometimes needs a human witness before the machine should continue.

Generating illustration...

The claim ceremony is the trust boundary made visible. Automation can proceed, but only after the human confirms the link.

Conventional auth	`auth.md` claim flow
Optimized for a human signing in	Optimized for an agent that may need a human checkpoint
Usually hides ambiguity behind redirects	Makes uncertainty explicit with `interaction_required`
Tends to treat the browser as the default interface	Treats a file and a step-up ceremony as the default interface

That is why the claim flow feels so strong. It does not try to eliminate ambiguity. It turns ambiguity into a controlled transition. The user sees advisories, the agent waits, and the service keeps the state machine honest instead of guessing.

What the Token Endpoint Is Really Doing

The token endpoint composes familiar standards instead of inventing a new universe. In the repository, `grant_type` dispatches between a standard JWT bearer exchange and a custom claim grant. While the claim is pending, the service can reuse `authorization_pending` semantics, which makes the waiting state legible to tooling that already understands OAuth-style polling.

switch (grant_type) {
  case 'jwt-bearer':
    return handleJwtBearerExchange(req, res);

  case 'urn:workos:agent-auth:grant-type:claim':
    if (!claimIsComplete) {
      return res.status(400).json({
        error: 'authorization_pending'
      });
    }
    return issueTokensForClaimedAgent(req, res);

  default:
    return res.status(400).json({ error: 'unsupported_grant_type' });
}

That choice matters because it keeps the protocol grounded. WorkOS is not discarding OAuth conventions. It is extending them just enough to cover agent registration and human-mediated claim without breaking the mental model already used by the ecosystem.

What Makes This Different from OAuth, MCP, and Traditional Auth

System	What it solves	Primary user	Where `auth.md` differs
OAuth / OIDC	Browser-based login and delegated access	Humans	`auth.md` starts before login, at discovery and registration for agents
MCP	Tool connectivity between models and tools	Agents	`auth.md` covers identity and onboarding, not tool transport
Auth0, Clerk, Keycloak	Identity management and login UX	Humans and product teams	`auth.md` offers an agent-native entry point instead of a human-first sign-in flow

The table makes the boundary clear. `auth.md` is not trying to replace OAuth, MCP, or identity vendors. It is carving out the missing layer between discovery and registration, where an agent needs to know how to introduce itself before any login box makes sense.

The Bigger Bet

If this works, agent onboarding stops being a bespoke integration problem. A service can publish a file, expose a small set of metadata, and let an agent figure out the rest. That is a meaningful shift: identity for non-human actors becomes a discoverable surface, not a private implementation detail buried inside product UI.

The bet is bigger than one protocol. It is an argument that the agentic web will need a standard way to say, “Here is how I recognize you.” `auth.md` answers with a file, a few endpoints, and a human fallback when the trust boundary is still fuzzy. That is a surprisingly practical place to start.