auth-md

name: auth-md description: > Generate, validate, and explain `auth.md` files — the open protocol that lets AI agents register for services on behalf of users. Use this skill whenever the user wants to make their app agent-ready by publishing an `auth.md`, generate Protected Resource Metadata (RFC 9728), validate an existing `auth.md` against the protocol specification, implement agent registration endpoints, understand how the auth.md protocol works, or configure authentication flows for agents. Trigger on mentions of "auth.md", "agent registration", "agent auth", "make my app agent-ready", "ID-JAG", "agent verified flow", "user claimed flow", "protected resource metadata", "OTP claim", "agentic registration", "CIMD", "Client ID Metadata Document", "oauth-id-jag", "logout token", "agent revocation", "agent credential", "agent discovery", "/.well-known/oauth-protected-resource", "/.well-known/oauth-authorization-server", "/agent/auth", or any variation of AI agent authentication/registration in APIs. metadata: author: https://ft.ia.br version: "1.0" date: 2026-03-05 repository: https://gitlab.com/fabriciotelles/skills license: Apache 2.0

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, and defines two primary flows:

Flow	Mechanism	When to use
Agent Verified	Provider (OpenAI, Anthropic, Cursor) signs an ID-JAG asserting user identity. Service verifies signature via JWKS and issues credentials synchronously.	Service already does JIT provisioning from OIDC/SAML; wants zero-friction registration.
User Claimed	OTP-based. Two entrypoints: anonymous start (credential immediately, claim later) or email required (no credential until OTP verified).	Agents on platforms that can't mint ID-JAGs; self-serve without trust list.

Protocol Endpoints

Endpoint	Purpose
`/.well-known/oauth-protected-resource`	Discovery — resource metadata (RFC 9728)
`/.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 (receives logout tokens from providers)

Credential Types

access_token — short-lived, no refresh token, re-register with fresh ID-JAG on expiry
api_key — typically no expiry, subject to revocation

Operation Modes

Parameter	Default	Description
`mode`	`generate`	`generate` = create auth.md + metadata; `validate` = check existing auth.md; `explain` = explain the protocol
`validation_level`	`basic`	`basic` = structure + fields + consistency (offline); `full` = basic + live endpoint fetch
`flows`	`all`	Which flows to include: `agent_verified`, `user_claimed_anonymous`, `user_claimed_email`, `all`
`role`	`app`	Perspective: `app` = service accepting registrations; `provider` = platform minting ID-JAGs

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 (agent verified, user claimed anonymous, user claimed email, or combination)
Credential type preference (api_key, access_token, or both)
Pre-claim scopes vs post-claim scopes (if anonymous start)
Trusted agent providers and trust list policy (if agent verified)
Whether the service already does JIT provisioning or requires manual onboarding
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 user claimed)
Step 5 — Use the credential
Errors (complete table)
Revocation

b) oauth-protected-resource.json — JSON for /.well-known/oauth-protected-resource

c) oauth-authorization-server.json — JSON for /.well-known/oauth-authorization-server with the complete agent_auth block

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)
Recommended rate limiting configuration
Recommended audit events
Security considerations (token hashing, OTP entropy, replay protection)

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
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 logout+jwt)
How to present consent to the user before asserting identity

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–5, Errors, Revocation)
Service name and base URL declared
At least one flow documented
Valid JSON in fenced code blocks for request/response shapes
Error table with standard error codes
Consistency: flows in prose match identity_types_supported in metadata JSON
Well-formed URLs in code blocks
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 and is consistent with auth.md
Fetch /.well-known/oauth-authorization-server and verify consistency
Check that register_uri, claim_uri, revocation_uri 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:

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

User Matching and JIT Provisioning

Both flows need to decide which service user a registration represents. Recommended resolution order:

Delegation record match — if credentials were previously issued for this (iss, sub), route to the same user
Verified email match — if a user exists with the same verified email, link
Verified phone match — same pattern
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 and no channel for user-facing communications.

Rate Limiting

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

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

Use a sliding-window counter with a shared store. Fail open on store errors.

Recommended Audit Events

Event	When	Data
`registration.created`	Successful POST /agent/auth	registration_id, registration_type, iss, sub
`claim.requested`	/agent/auth/claim called	registration_id, email
`otp.generated`	OTP minted for claim view	registration_id
`claim.confirmed`	/agent/auth/claim/complete succeeds	registration_id, claimed_by_user_id
`registration.expired`	Unclaimed registration past TTL	registration_id
`registration.revoked`	Logout token processed	registration_id, iss, sub

Security Considerations

Token hashing — claim_token, claim_view_token, and OTP are bearer secrets with no proof of possession. Store only SHA-256 hashes. Plaintext leaves the server exactly once.
OTP entropy + TTL — use CSPRNG. Default TTL ≤10 min with tight retry limits.
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 OAuth Client ID Metadata Document and verify jwks_uri matches the one used to verify the signature.
Key reuse across claim boundary — for anonymous, the in-place permission swap means anyone who captured the key pre-claim retains access post-claim. Offer forced-rotation as an opt-in.
Bulk revocation — provide an operator-facing mechanism to revoke all outstanding agent credentials for a tenant in one shot.

Agent Readiness Scanner Check

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

/auth.md served from site root with HTTP 200
Content is Markdown with H1 heading containing "auth.md" (e.g., # auth.md or # Example auth.md)
Optionally validates OAuth Protected Resource Metadata at /.well-known/oauth-protected-resource
Optionally validates Authorization Server metadata at /.well-known/oauth-authorization-server

Scanner does NOT:

Probe POST /agent/auth (passive scan only)
Require OAuth metadata to pass (self-contained auth.md is sufficient)

To pass the check minimally:

# auth.md

This service accepts AI agent registrations.

## Authentication

Agents can register via POST /agent/auth with a valid ID-JAG.
See below for supported methods and credential types.

To pass with full marks (all metadata):

Serve /auth.md with proper heading
Publish /.well-known/oauth-protected-resource with resource, authorization_servers, scopes_supported, bearer_methods_supported: ["header"]
Publish /.well-known/oauth-authorization-server with issuer, agent_auth block containing skill, register_uri, and registration methods

Scan command:

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'

Flow Metadata Fields (per scanner SKILL.md)

For each flow the scanner may look for:

Flow	Required in AS metadata
ID-JAG	`identity_types_supported: ["identity_assertion"]`, `identity_assertion.assertion_types_supported` with `urn:ietf:params:oauth:token-type:id-jag`, credential types. Optional: `revocation_uri`, `events_supported`
Verified email	`identity_assertion.assertion_types_supported` with `verified_email`, credential types, `claim_uri`
Anonymous	`identity_types_supported: ["anonymous"]`, `anonymous.credential_types_supported`, `claim_uri`

Quality Checklist

Before delivering output, verify:

Generated auth.md contains all required steps + Errors + Revocation
JSON metadata includes valid agent_auth block with all required fields
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
No unreplaced placeholder values ({{...}}, <your-...>, [YOUR_...])
Validation report covers all rules for the requested level
Rate limiting documented or mentioned in next steps
Security considerations included in next steps
If role=provider: ID-JAG structure and JWKS 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 Protected Resource Metadata, AS metadata, and ID-JAG
references/example-auth-md.md — Working example of a complete auth.md file (Acme Notes)
references/implementation-guide.md — Server-side implementation guide with security, rate limiting, and audit events

Updating Protocol Knowledge

This skill ships with a snapshot of the auth.md protocol specification (v1, May 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.