/auth-md

name: auth-md
description: >
  Generate, validate, and explain `auth.md` files — the open protocol for AI agent registration.
  Use when making apps agent-ready, generating Protected Resource Metadata (RFC 9728),
  validating auth.md files, or implementing agent registration endpoints. Triggers on
  "auth.md", "agent registration", "agent auth", "make my app agent-ready", "ID-JAG",
  "identity_assertion", "service_auth", "protected resource metadata", "agentic registration".
metadata:
  author: https://ft.ia.br
  version: "2.1"
  date: 2026-09-20
  repository: https://github.com/fabricioctelles/skills
  license: Apache 2.0
  category: library-and-api-reference
  upstream_commit: "b53c9edfbfeea679b617727ebca9ba436bade794"

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:

| Flow | Mechanism | When to use | |------|-----------|-------------| | **identity_assertion** | Provider signs an ID-JAG (with `auth_time`) asserting user identity. Service verifies JWKS, returns `identity_assertion`. Agent exchanges at `/oauth2/token`. | Service does JIT provisioning from OIDC/SAML; wants zero-friction registration. | | **service_auth** | Email hint + browser-based ceremony. Agent receives `user_code` + `verification_uri`; user signs in and types code. Agent polls `/oauth2/token`. | Agents on platforms that can't mint ID-JAGs; self-serve without trust list. | | **anonymous** | No identity upfront. Immediate `identity_assertion` with pre-claim scopes. Optional deferred claim for scope upgrade. | Agent needs basic access immediately; human ownership binding deferred. |

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/identity` | Registration — dispatches on `type` field | | `POST /agent/identity/claim` | Claim initiation (anonymous deferred, or re-initiate expired user_code) | | `POST /oauth2/token` | Token exchange (JWT-bearer grant) + claim polling (claim grant) | | `POST /oauth2/revoke` | Credential-layer revocation (RFC 7009) | | `events_endpoint` | Registration-layer revocation (receives SETs, RFC 8935) |

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

| 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: `identity_assertion`, `service_auth`, `anonymous`, `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 (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`** — JS