auth.md

auth.md is an open protocol and reference implementation that lets AI agents authenticate to services on behalf of the users they act for. It is published by WorkOS on GitHub at github.com/workos/auth.md under an MIT license. The mechanism centers on a Markdown file named AUTH.md that a service hosts at its domain, telling agents how to register and obtain credentials.

What It Is

The repository describes a protocol for what it calls agentic registration. It defines three roles: an agent acting on behalf of a user, an agent provider that mints identity assertions (called ID-JAGs), and a service that accepts those assertions and issues credentials in return. When an agent is not tied to a user identity, or the agent provider does not support ID-JAGs, the service falls back to an OTP-based claim flow to authenticate the agent instead.

The AUTH.md File

At the center of the protocol is a Markdown manifest the service hosts, typically at a path like service.com/auth.md. The README describes this file as a skill manifest that agents read, laying out a procedural recipe for the agent to follow: discover, register, claim, use, and handle revocation. Service metadata is published at a well-known discovery endpoint that points agents to the AUTH.md skill, the registration URI, the claim URI, and the revocation URI.

Registration Flows

The README documents three registration flows that share a single /agent/auth endpoint, each matched to what the agent already has available. The identity assertion flow has the agent obtain an audience-specific ID-JAG from its provider, which the service verifies against the provider's published JSON Web Key Set before issuing credentials. The verified-email flow sends a claim email and uses a six-digit one-time code that the user reads back to the agent. The anonymous flow issues a scoped API key up front and lets a user later take ownership through the same OTP claim step, at which point the service swaps the key's pre-claim permissions for post-claim ones.

What the Repository Includes

The repository ships sample implementations for both sides of the exchange. The README points implementers to agent-services for a sample resource server and authorization server, and to agent-providers for a sample identity provider that mints ID-JAGs and publishes its JWKS. A shared workspace package holds common ports and types. The project is written entirely in TypeScript and runs locally with pnpm, exposing a sample service and provider that walk through the three flows interactively.

Current Status

The repository is public and MIT-licensed, with no tagged releases published at the time of writing. The codebase is presented as a reference implementation rather than a packaged product, intended to demonstrate the protocol and give implementers a starting point for both the service and provider sides.