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.

Rate Limiting

The /agent/identity endpoint is unauthenticated for anonymous registration. Implement two tiers:

1. Per-IP (checked first) — prevents a single source from consuming the tenant's budget. Default: 5/hour anonymous, 60/hour identity_assertion.
2. Per-tenant (checked second) — global cap across IPs. Default: 100/hour anonymous, 1000/hour identity_assertion.

Also rate-limit /oauth2/token polling — enforce interval from the claim block, reject with slow_down if too fast.

Recommended Audit Events

Security Considerations

• auth_time validation — auth_time is required in ID-JAGs. Service validates against idJagMaxAuthAgeSeconds. If too old, returns login_required (401) — agent must get user to re-authenticate at provider.
• claim_token handling — returned exactly once in the registration response. Agent holds in memory only for ceremony duration. Do not persist past Step 4.
• Token hashing — claim_token is a bearer secret. Store only SHA-256 hash server-side.
• Consent UX — surface resource_name and resource_logo_uri from PRM to the user before asserting identity. This is the user's only consent gate.
• Two revocation layers — credential layer (agent-callable, /oauth2/revoke, kills one access_token) vs registration layer (provider-driven SETs at events_endpoint, kills identity_assertion + all derived tokens).
• Replay protection — cache jti values with TTL of at least exp - iat + clock skew (typically 6 min).
• CIMD resolution — if client_id is a URL, fetch as Client ID Metadata Document and verify jwks_uri.
• Bulk revocation — provide operator-facing mechanism to revoke all outstanding identity_assertions for a tenant.

Error Codes Reference

Agent Readiness Scanner Check

The isitagentready.com scanner validates auth.md as the authMd check. Pass criteria:

1. /auth.md served from site root with HTTP 200
2. Content is Markdown with H1 heading containing "auth.md"
3. Optionally validates OAuth Protected Resource Metadata at /.well-known/oauth-protected-resource
4. Optionally validates Authorization Server metadata at /.well-known/oauth-authorization-server

To pass the check minimally:

markdownCopy code
# auth.md

This service accepts AI agent registrations.

## Authentication

Agents can register via POST /agent/identity with a valid ID-JAG.
See below for supported methods.

To pass with full marks (all metadata):

• Serve /auth.md with proper heading
• Publish /.well-known/oauth-protected-resource with resource, resource_name, resource_logo_uri, authorization_servers, scopes_supported, bearer_methods_supported: ["header"]
• Publish /.well-known/oauth-authorization-server with issuer, token_endpoint, revocation_endpoint, grant_types_supported, and agent_auth block containing skill, identity_endpoint, claim_endpoint, events_endpoint, and registration methods

Scan command:

bashCopy code
curl -s -X POST 'https://isitagentready.com/api/scan' \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://YOUR-DOMAIN/","enabledChecks":["authMd"]}' | jq '.checks.discovery.authMd'

Quality Checklist

Before delivering output, verify:

• Generated auth.md contains all required steps (1-6) + Errors + Revocation
• AS metadata includes issuer, token_endpoint, revocation_endpoint, grant_types_supported
• agent_auth block includes identity_endpoint, claim_endpoint, events_endpoint
• identity_types_supported matches the flows the user chose
• scopes_supported reflects actual API scopes found in codebase
• Base URLs are consistent between auth.md and metadata JSON
• Error codes table includes all standard codes for the supported flows
• Step 5 documents token exchange at /oauth2/token with jwt-bearer grant
• Revocation section documents both layers (credential + registration)
• No unreplaced placeholder values ({{...}}, <your-...>, [YOUR_...])
• Validation report covers all rules for the requested level
• Rate limiting documented (including /oauth2/token polling)
• Security considerations included (auth_time, claim_token, consent UX)
• If role=provider: ID-JAG structure with auth_time documented

References

• references/protocol-template.md — Complete auth.md template with all sections and placeholders
• references/validation-rules.md — Full validation ruleset with error messages and severities
• references/metadata-schema.md — JSON schema for PRM, AS metadata, ID-JAG, and identity_assertion
• references/example-auth-md.md — Working example of a complete auth.md file (Acme Notes)
• references/implementation-guide.md — Server-side implementation guide with token exchange, claim ceremony, revocation, and security

Updating Protocol Knowledge

This skill ships with a snapshot of the auth.md protocol specification (v2, June 2026). When possible, fetch the latest version from:

• Skill Home and Doc Hub: https://auth-md.com
• Spec: https://raw.githubusercontent.com/workos/auth.md/refs/heads/main/AUTH.md
• Docs overview: https://workos.com/auth-md/docs
• Apps guide: https://workos.com/auth-md/docs/apps
• Agent providers guide: https://workos.com/auth-md/docs/agent-providers
• File anatomy: https://workos.com/auth-md/docs/auth-md

If fetch fails, use the bundled references/ as the source of truth.