What is auth.md?

Published May 22, 2026 · Last updated July 27, 2026

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.

The Problem

For 20 years, sign-up flows were built for humans: buttons, forms, email verification, OAuth consent screens, CAPTCHAs, and admin dashboards. These all assume a human is sitting in front of a browser clicking around.

AI agents break that assumption. When an agent hits your API and gets a 401, its options are limited: give up, ask the user to manually create an account, or attempt brittle browser automation. None of these scale.

The Solution

auth.md provides a standardized way for agents to answer three questions:

How do I register? — Discovery via RFC 9728 Protected Resource Metadata
What scopes can I request? — Declared in the Authorization Server metadata
How do I prove the user approved this? — Via ID-JAG (Identity Assertion JWT) or browser-based claim ceremony (RFC 8628-style)

The protocol composes with existing OAuth metadata, JWT verification, scoped credentials, and revocation. It extends standards rather than replacing them.

Why Agent Auth Control Matters

AI agents are powerful — and that power needs guardrails. Without proper authentication protocols, agents operate in a gray zone: either blocked entirely (bad for users) or granted broad access (bad for security).

auth.md gives services fine-grained control over what agents can do:

Scoped credentials — agents get only the permissions they need, nothing more
Revocation at two layers — kill a single token or an entire registration
Trust lists — choose which agent providers can assert user identity
Audit trail — every registration is traceable to a user and provider

The alternative is worse. Without a standard, agents resort to credential-stuffing, browser automation, or asking users to copy-paste API keys. All of these are less secure and harder to control than a proper registration protocol.

Two Flows Explained

Identity Assertion

A trusted agent provider (OpenAI, Anthropic, Cursor) signs an ID-JAG asserting the user's identity. The service verifies the signature and returns an identity assertion, exchanged at /oauth2/token for an access token.

Best for: Services that already do JIT provisioning from OIDC/SAML. Zero-friction, no human in the loop.

Service Auth & Anonymous

Browser-based claim ceremony (RFC 8628-style). Two entrypoints: anonymous (identity assertion immediately, claim later) or service_auth (user completes verification in browser before token is issued).

Best for: Agents on platforms that can't mint ID-JAGs; self-serve without a trust list.

auth.md discovery flow: Agent calls API, gets 401, fetches metadata, registers, uses credential — The auth.md discovery and registration flow

Key Concepts

ID-JAG (Identity Assertion JWT Authorization Grant): A short-lived JWT signed by an agent provider asserting that a specific user authorized the agent to act on their behalf. Audience-bound to the target service. Defined in the IETF ID-JAG draft.
Protected Resource Metadata (RFC 9728): A JSON document at /.well-known/oauth-protected-resource that tells agents which authorization servers protect a resource and what scopes are available.
Claim Ceremony: An RFC 8628-style browser-based process where a human user takes ownership of an agent-created registration. The agent receives a user_code and verification_uri, displays them to the user, and the user completes verification directly in their browser. The agent then polls /oauth2/token for the access token.
Trust List: A service-maintained registry of agent providers whose ID-JAG assertions are accepted. Security-critical configuration — only providers you trust can assert user identity to your service.

Who supports auth.md?

Apps (publish auth.md)

Services that have published an auth.md file for agents to discover:

Resend — Email API
here.now — Instant web hosting for agents
Ora.ai — Agent readiness platform

Agent Providers (mint ID-JAGs)

Platforms whose agents can assert user identity via ID-JAG:

Cloudflare — Launch partner
Firecrawl — Launch partner
OpenAI — ChatGPT, GPT agents
Anthropic — Claude
Cursor — AI code editor

Who should implement auth.md?

App developers who want AI agents to be able to sign up for and use their service without human intervention
Agent providers who want their agents to seamlessly access any service that publishes an auth.md
MCP server builders who need a standard way to issue credentials to connecting agents

How to get started

Read the Specification Install the Skill Compare to llms.txt

Frequently Asked Questions

Is auth.md only for WorkOS customers?

No. auth.md is an open protocol released under the MIT license. Any app can publish one, any agent can read one, and any provider can implement verified identity assertions. WorkOS authored the spec but it is not tied to WorkOS infrastructure.

What's the difference between auth.md and OAuth?

auth.md extends OAuth for agent-initiated registration. OAuth assumes a browser-based consent dance with a human in the loop. auth.md provides a machine-readable discovery layer and registration endpoints that agents can use without a browser. It uses existing OAuth standards (RFC 9728, JWT) under the hood.

Do I need to support both flows?

No. Pick what fits your security model. If you already do JIT provisioning from identity providers, the identity assertion flow is a small addition. If you want to support agents from any platform (including those that can't mint ID-JAGs), add the service auth or anonymous flow.

Which agent platforms support auth.md?

Any platform that can mint audience-bound ID-JAGs can use the identity assertion flow. Cloudflare and Firecrawl are launch partners. OpenAI, Anthropic, and Cursor are expected to follow. The service auth and anonymous flows work with any agent — no platform support required.

How is auth.md different from MCP Auth?

MCP Auth secures the connection between an MCP client and an MCP server. auth.md solves a different problem: how an agent registers for a web service it has never used before. They are complementary — an MCP server could use auth.md to register with upstream services on behalf of users.