WorkOS Releases auth.md: An Open Agent Registration Protocol Built on OAuth Standards

For years, authentication on the web has followed one design assumption: a human sits behind a browser. Click a button. Fill out a form.

Verify an email. Copy an API key and paste it somewhere else. But what happens when the user is delegating work to an agent?

Agents are already writing code, opening pull requests, triaging tickets, querying systems, and updating records. Yet, most products still have no real way for an agent to register. The current workaround – giving an agent a raw API key or session token – produces credentials that are unscoped, hard to audit per session, and impossible to revoke selectively.

To address this issue, WorkOS is proposing a structured alternative: auth.md, an open protocol for agent registration. auth.md is a small Markdown file an application publishes at a well-known location – typically https://service.com/auth.md. The file tells agents how to register with that service: which flows are supported, which scopes exist, and how credentials are issued, audited, and revoked.

Because it is plain-text Markdown, the same file works as documentation for human developers and as a runtime artifact agents can read programmatically. An agent fetches the file, reads the structured sections, picks the right flow, and registers – without a human filling out a form. Discovery works in two hops.

The machine-readable source of truth lives at /.well-known/oauth-protected-resource (Protected Resource Metadata, or PRM). It promotes the resource and points at the Authorization Server. The Authorization Server metadata at /.well-known/oauth-authorization-server carries the agent_auth block – the structured object that tells agents which flows are supported, and what the register_uri, claim_uri, revocation_uri, and identity_types_supported values are.

On any 401 from the API, the service should return a WWW-Authenticate: Bearer resource_metadata="..." header so agents can bootstrap discovery without reading documentation first. auth.md defines two primary flows. An application can support either or both.

The Agent verified flow and the User claimed flow provide different methods for agents to register and obtain credentials. The result is a delegation record per (iss, sub, aud) that the provider can revoke at any time by POSTing a logout token to the service's revocation_uri. For observability and incident response, the docs recommend recording a standard set of audit events: registration.created, claim.requested, otp.generated, claim.confirmed, registration.expired, and registration.revoked.