auth.md and the OAuth Lineage Move for Agent Registration

On May 25, 2026, WorkOS published auth.md, an open protocol that lets agents register with any web service without a human ever opening an email client and copying a one-time code. The mechanism is small. A service drops a Markdown file at service.com/auth.md, exposes two well-known endpoints, and any compliant agent can discover how to register, get credentials, and revoke them.

This is the second WorkOS shipment in three weeks. Project Horizon, published May 6, was the productized governed runtime for code agents. auth.md is the parallel open-standards play. Read together, the strategy is legible: ship one productized stack to win the platform fight, ship one open protocol to win the standards fight, and let neither depend on the other.

The protocol itself is the right move at the infrastructure layer. It is also the kind of move that quietly hands the hard work back to the buyer. Every service that publishes an auth.md still has to decide which agent providers it trusts, what scopes new registrations get by default, and what happens when a credential turns out to be wrong. The protocol is plumbing. The policy is yours.

What auth.md Actually Specifies

The published specification, as the WorkOS team and the MarkTechPost write-up describe it:

A plain-text Markdown file at the well-known path service.com/auth.md. It is human-readable documentation and machine-parseable configuration at the same time. Engineers read it, agent runtimes parse it.
Two-hop discovery via OAuth metadata. The agent fetches /.well-known/oauth-protected-resource (Protected Resource Metadata, per RFC 9728) and then /.well-known/oauth-authorization-server, which carries an agent_auth block with register_uri, claim_uri, revocation_uri, and identity_types_supported. Any 401 response includes a WWW-Authenticate: Bearer resource_metadata="..." header so an agent that hits a closed door knows exactly where the lock is.
Two registration flows, mapped to two trust models. Agent Verified registrations use ID-JAG (Identity Assertion Authorization Grant). The agent’s identity provider, OpenAI, Anthropic, or Cursor for example, issues a signed assertion. The service verifies the JWT against the provider’s JWKS, validates aud, exp, iat, jti, and client_id, and issues credentials synchronously. No OTP. No human. User Claimed registrations use OTP, in two variants: Anonymous Start (the agent self-registers and the user binds the registration later via OTP, scopes upgrading in place) and Email Required (no credential issues until OTP completes).
A bounded credential model for the ID-JAG path. Access tokens issued from a verified ID-JAG must not include refresh tokens. The agent presents a fresh assertion to extend access. The blast radius of a stolen token shrinks to the assertion lifetime.
A recommended audit shape. registration.created, claim.requested, otp.generated, claim.confirmed, registration.expired, registration.revoked. ID-JAG flows include iss, sub, and agent_platform so the service and the agent provider can correlate logs after an incident.

None of these primitives are new. auth.md composes RFC 9728 with ID-JAG and writes the agent registration use case as a thin layer on top. That is the point. The protocol is not tied to WorkOS infrastructure. The auth.md spec lives on GitHub. Any service can implement it, and any agent runtime can speak it.

Two Flows, Two Trust Models

The most consequential design choice in auth.md is not the file format. It is the split between Agent Verified and User Claimed registrations, because those two paths encode two different answers to the same question: who is asserting that this agent should get access.

Agent Verified flows trust the agent provider. When Anthropic signs an ID-JAG and the service verifies the JWT, the service is saying, in effect, that Anthropic’s identity provider is a sufficient witness. The user does not show up in the loop. The credential issues synchronously because the service has decided in advance that this issuer is trustworthy for this scope. That is fast and clean. It also concentrates risk: every service that accepts ID-JAG from a given provider is now exposed to that provider’s identity hygiene.

User Claimed flows trust the user. The agent registers anonymously or with email, and the user has to complete an OTP ceremony before any meaningful scope opens. Slower. Higher friction. Lower blast radius. The user is in the loop by design, and the binding between agent and account happens through a channel the user owns.

A product team adopting auth.md has to decide which providers it accepts in the Agent Verified path, which it forces down the User Claimed path, and how scopes differ between the two. Those decisions are not in the spec. They cannot be. They are policy, and the policy belongs to the service.

What the Protocol Does Not Solve

auth.md gets the registration handshake right. It says nothing about the policy decisions that determine whether the handshake should have happened at all.

Which agent providers do you trust by default. ID-JAG verification is a cryptographic check. It tells you the assertion is genuine. It does not tell you the assertion is safe to honor. A new agent provider could be technically compliant and operationally dangerous on day one. The service has to maintain a trust list, a scope matrix per provider, and a process for promoting providers from Anonymous Start to Email Required to Agent Verified. None of that ships with auth.md.

What scopes new registrations receive. The spec describes how to issue credentials. It does not describe what those credentials should let an agent do on first contact. A service that grants read-write scopes to any verified assertion has built a fast path to a major incident. A service that grants read-only and forces scope upgrades through explicit consent has built a slower path with a smaller blast radius. Both are valid auth.md implementations. Only one survives an audit.

What happens when something goes wrong. Revocation is in the protocol. Anomaly detection is not. If an agent provider’s keys leak, every service that trusts that provider has to know within minutes, not hours. The recommended audit events give you the raw material. They do not give you the detection logic, the alert routing, or the response playbook.

We treated this exact pattern in the machine-payments protocol post: a clean specification at the infrastructure layer, no governance answer at the policy layer. The same shape appears here, and the same engineering response applies. The protocol is necessary. It is not sufficient. The governed registry that decides which agents to admit, with what scopes, under what conditions, is a product decision and an operational discipline. The integration tax we described in the agent-integration-tax post does not disappear because the discovery handshake got cheaper. It moves up the stack.

The Two-Track WorkOS Strategy

Look at the two May shipments together and the WorkOS bet becomes visible. Project Horizon is the productized runtime: a closed integration of sandboxes, event-driven orchestration, MCP-based context, and human approval at every merge. auth.md is the open protocol: a specification anyone can implement, with WorkOS infrastructure as one option among several.

Productized stacks win when buyers want a single vendor to call when something breaks. Open standards win when buyers want to avoid that exact dependency. WorkOS is shipping both. The Horizon customer gets a managed runtime. The auth.md adopter gets an open spec they can implement against any backend, including WorkOS’s. Neither move undermines the other, because they target different decisions in the same buyer.

Standards beat platforms at scale, when the standard is good enough to compose. RFC 9728 plus ID-JAG plus a thin Markdown spec is good enough to compose. The question for the next 12 months is which other vendors ship auth.md endpoints, which agent providers issue ID-JAG assertions, and how fast the policy layer matures around the protocol. Until that layer matures, every service that publishes an auth.md file is writing its own answers to the trust questions the spec leaves open.

Do This Now

If your service is going to be consumed by agents in 2026, read the auth.md specification this week. Then write three documents before you implement anything.

The first document is a trust list. Which agent providers are you willing to accept ID-JAG assertions from on day one? Which require User Claimed for the first 90 days? Which are excluded entirely? Write the names down and write the criteria for moving a provider between tiers.

The second document is a scope matrix. For each trust tier, what scopes does a new registration receive? What scopes require an explicit user consent step? What scopes are never granted via Anonymous Start? Map the answers to your actual API surface, not to a generic OAuth scope vocabulary.

The third document is an anomaly playbook. If registration.created events spike for a single agent_platform over a 10-minute window, what happens? Who pages whom? What is the auto-throttle threshold? What is the kill switch? auth.md gives you the events. The playbook is yours to write.

Implement auth.md when those three documents exist, not before. The protocol is a few hundred lines of code. The policies it depends on are the actual product.

This analysis synthesizes WorkOS Releases auth.md: An Open Agent Registration Protocol Built on OAuth Standards (MarkTechPost, May 2026), auth.md technical details (WorkOS, May 2026), the auth.md specification (WorkOS GitHub, May 2026), and RFC 9728: OAuth 2.0 Protected Resource Metadata (IETF, April 2025).

Victorino Group helps companies design the trust and scope policies that sit on top of open agent protocols. Let’s talk.