Auth Md

auth-md

Generate, validate, and explain the auth.md protocol — the open standard that lets AI agents register for services on behalf of users, without signup forms.

---

Protocol Context

auth.md is a Markdown file published at a service's root (typically https://service.com/auth.md) that instructs agents on how to register. It works simultaneously as human-readable documentation and as a discoverable runtime artifact for agents.

The protocol extends RFC 9728 (OAuth 2.0 Protected Resource Metadata) with an agent_auth block in the Authorization Server metadata. Registration returns an identity_assertion (service-signed JWT) that the agent exchanges at /oauth2/token for an access_token. Three registration methods are supported:

Protocol Endpoints

Token Lifecycle

Registration never returns an access_token directly. The flow is:

1. Registration → identity_assertion (service-signed JWT, reusable until expiry)
2. Exchange → POST /oauth2/token with grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer → access_token
3. Refresh → re-exchange same identity_assertion when access_token expires
4. Expired assertion → restart at registration (Step 3)

Claim Ceremony (v2 — Browser-Based)

The claim ceremony uses RFC 8628-style device authorization:

1. Registration returns user_code + verification_uri in a claim block
2. Agent surfaces both to the user
3. User opens verification_uri, signs in to the service, types the 6-digit code
4. Agent polls POST /oauth2/token with grant_type=urn:workos:agent-auth:grant-type:claim + claim_token
5. On success: receives access_token + fresh identity_assertion

---

Operation Modes

---

Workflow: Generate

1. Scan the codebase

Look for:

• Existing API routes and authentication patterns
• Defined scopes/permissions
• Framework (Express, Django, Rails, FastAPI, NestJS, etc.)
• Base URL and auth server URL configuration
• Existing authentication middleware
• User models and provisioning mechanisms

2. Ask the user only what cannot be inferred

• Which flows to support (identity_assertion, service_auth, anonymous, or combination)
• Pre-claim scopes vs post-claim scopes (if anonymous)
• Trusted agent providers and trust list policy (if identity_assertion)
• Whether the service already does JIT provisioning or requires manual onboarding
• idJagMaxAuthAgeSeconds value (default: 3600)
• Desired rate limiting policy

3. Generate artifacts

Produce three artifacts:

a) auth.md — Markdown file following the protocol template (see references/protocol-template.md). Must contain:

• Title and intro addressed to the agent
• Step 1 — Discover (two hops: PRM → AS metadata)
• Step 2 — Pick a method (decision tree)
• Step 3 — Register (one subsection per supported method)
• Step 4 — Claim ceremony (if service_auth or anonymous with claim)
• Step 5 — Exchange the assertion (POST /oauth2/token with jwt-bearer grant)
• Step 6 — Use the access_token
• Errors (complete table with all applicable codes)
• Revocation (two layers)

b) oauth-protected-resource.json — JSON for /.well-known/oauth-protected-resource with resource_name and resource_logo_uri

c) oauth-authorization-server.json — JSON for /.well-known/oauth-authorization-server with:

• issuer, token_endpoint, revocation_endpoint, grant_types_supported
• Complete agent_auth block with identity_endpoint, claim_endpoint, events_endpoint

4. Generate implementation guidance

"Next Steps" section with:

• How to serve auth.md at the domain root
• How to serve metadata at the well-known paths
• How to add WWW-Authenticate header to 401 responses
• Endpoint implementation guidance (without generating framework-specific code unless requested)
• Token exchange implementation at /oauth2/token
• Claim page hosting (verification_uri → login → code input → confirm)
• Recommended rate limiting configuration
• Recommended audit events
• Security considerations (token hashing, auth_time validation, replay protection, claim_token handling)

5. Generate Agent Provider guide (if role=provider)

When the user is an agent provider (not an app), generate:

• How to mint audience-specific ID-JAGs with auth_time
• Token structure (header + payload with required and optional claims)
• How to publish JWKS
• Optionally: how to publish a CIMD (Client ID Metadata Document)
• How to implement revocation (POST SET to events_endpoint)
• How to present consent to the user before asserting identity (using resource_name + resource_logo_uri)

---

Workflow: Validate

1. Load the auth.md

From a local file path or URL.

2. Run validation at the requested level

Basic (offline):

• All required headings present (Step 1–6, Errors, Revocation)
• At least one flow documented
• Valid JSON in fenced code blocks for request/response shapes
• AS metadata contains identity_endpoint, token_endpoint, grant_types_supported
• Error table with standard error codes
• Consistency: flows in prose match identity_types_supported in metadata JSON
• No unreplaced placeholders

Full (live):

• All basic checks, plus:
• Fetch /.well-known/oauth-protected-resource from the declared base URL
• Verify agent_auth block exists in AS metadata
• Fetch /.well-known/oauth-authorization-server and verify consistency
• Check that identity_endpoint, token_endpoint, revocation_endpoint respond (accept 400/401/422, reject 404/405)
• Verify API returns 401 with WWW-Authenticate containing resource_metadata

3. Report results

Checklist with ✅/❌ per rule, grouped by category:

• Structure — headings and order
• Fields — required fields in JSONs
• Consistency — cross-references between prose and metadata
• Format — valid JSON, valid HTTP, no placeholders
• Endpoints (full only) — reachability and correct responses

Include severity: 🔴 Error (agents will fail), 🟡 Warning (degraded experience), 🟢 Info (suggestion).

See references/validation-rules.md for the complete ruleset.

---

Workflow: Explain

When the user wants to understand the protocol without generating or validating:

1. Identify what the user wants to know (overview, specific flow, specific endpoint, security, etc.)
2. Explain using the protocol context above and the references
3. Use text-based sequence diagrams when helpful
4. Point to official documentation when relevant

---

User Matching and JIT Provisioning

The identity_assertion flow needs to decide which service user a registration represents. Recommended resolution order:

1. Delegation record match — if (iss, sub) has a delegation on file, route to same user
2. Verified email match — if a user exists with same verified email BUT no (iss, sub) delegation → interaction_required (401) with claim block for user to confirm linking
3. Verified phone match — same pattern
4. No match → JIT — create a new user per provisioning policy, or refuse

Reject ID-JAGs with neither a verified email nor a verified phone — there's no basis for matching.

---