What is auth.md?

Published May 22, 2026 · Last updated May 22, 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 OTP claim ceremony

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

Two Flows Explained

Agent Verified

A trusted agent provider (OpenAI, Anthropic, Cursor) signs an ID-JAG asserting the user's identity. The service verifies the signature and returns credentials synchronously.

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

User Claimed

OTP-based registration. Two entrypoints: anonymous start (credential immediately, claim later) or email required (no credential until OTP verified).

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: The OTP-based process where a human user takes ownership of an agent-created registration. The user receives a 6-digit code via email and reads it back to the agent.
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

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 agent verified flow is a small addition. If you want to support agents from any platform (including those that can't mint ID-JAGs), add the user claimed flow.

Which agent platforms support auth.md?

Any platform that can mint audience-bound ID-JAGs can use the agent verified flow. Cloudflare and Firecrawl are launch partners. OpenAI, Anthropic, and Cursor are expected to follow. The user claimed flow works 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.