Auth.md

Overview

The auth.md protocol is an open standard that lets AI agents register for services on behalf of users, without signup forms. A Markdown file published at a service’s root (https://service.com/auth.md) works simultaneously as human-readable documentation and as a discoverable runtime artifact for agents.

Extends RFC 9728 (OAuth 2.0 Protected Resource Metadata) with an agent_auth block in the Authorization Server metadata.

When to Use

• Make your app agent-ready by publishing an auth.md
• Generate Protected Resource Metadata (RFC 9728)
• Validate an existing auth.md against the protocol spec
• Implement agent registration endpoints
• Understand how the auth.md protocol works
• Configure authentication flows for agents

Installation

npx skills add https://gitlab.com/fabriciotelles/skills -s auth-md

Supported Flows

Flow	Mechanism	When to use
Agent Verified	Provider signs an ID-JAG asserting user identity	JIT provisioning from OIDC/SAML; zero-friction
User Claimed	OTP-based (anonymous start or email required)	Platforms without ID-JAG; self-serve

Protocol Endpoints

Endpoint	Purpose
/.well-known/oauth-protected-resource	Discovery — resource metadata
/.well-known/oauth-authorization-server	Discovery — AS metadata with agent_auth block
POST /agent/auth	Registration — dispatches on type field
POST /agent/auth/claim	Claim initiation (anonymous start only)
POST /agent/auth/claim/complete	OTP verification
POST /agent/auth/revoke	Revocation

Operation Modes

Mode	Description
generate	Create auth.md + metadata JSON
validate	Check existing auth.md (basic or full with live fetch)
explain	Explain the protocol without generating artifacts

Generated Artifacts

1. auth.md — Markdown file with all protocol steps
2. oauth-protected-resource.json — JSON for /.well-known/oauth-protected-resource
3. oauth-authorization-server.json — JSON with complete agent_auth block

Origin

Protocol created by WorkOS. Spec: github.com/workos/auth.md

📄 Full documentation on GitLab