agentic-auth

Agentic Auth — auth.md Support for Every New App

Why This Skill Exists

AI agents are becoming users of software. Most apps only authenticate humans — but agents need to register, get scoped credentials, and act on behalf of users too. auth.md is an open protocol by WorkOS (MIT licensed) that standardizes how agents register with applications. It's like robots.txt but for agent authentication.

By using this skill, every product Mj builds is agent-ready from day one. This is a standing protocol: always ask about auth.md when a new app is being created, just like asking about a README or LICENSE.

When This Skill Triggers

This skill activates when Mj is building something new that could accept agent users:

• •New web apps, APIs, SaaS products, services, tools, or platforms
• •Scaffolding or deploying a new project that serves an API
• •Any product that has endpoints agents might want to call

It does NOT trigger for:

• •Blog posts, documents, presentations, or other content
• •Scripts or tools meant for personal/local use only
• •Modifications to existing apps (unless adding auth.md specifically)

What to Do When Triggered

Step 1: Ask the Question

Before scaffolding, always ask:

"Should this app support agentic authentication? auth.md is an open protocol that lets AI agents (like Claude, GPT, Cursor) register and use your service on behalf of users. It's adopted by Cloudflare, Firecrawl, Resend, and others. Adding it makes your app agent-ready from day one."

If the user says no, note it and continue with the build. Don't push.

If the user says yes (or says something like "sure", "yeah", "of course"), proceed to Step 2.

Step 2: Gather Project Details

Ask for (or infer from context) these details to fill in the auth.md template:

1. Service name — What's the app called?
2. Domain — Where will it be hosted? (e.g., myapp.graice.ai)
3. Description — One-line description of what the service does
4. Scopes — What permissions should agents have? (e.g., read data, write data, manage users). If unsure, default to api.read and api.write.
5. Which flows to support — Both agent verified (ID-JAG) and user claimed (OTP) are recommended. For simpler apps, user claimed alone is fine since it doesn't require agent provider integration.
6. Credential type — api_key (simpler, non-expiring) or access_token (more secure, expires). For most of Mj's products, api_key is the right default.

If the user hasn't thought about these yet, suggest sensible defaults based on the project. Most of Mj's apps will want:

• •Both flows supported
• •api_key credential type
• •api.read and api.write scopes as a starting point

Step 3: Generate the auth.md File

Read the template at templates/auth.md.template within this skill's directory.

Fill in all {{PLACEHOLDER}} values with the project-specific details gathered in Step 2. Place the generated auth.md file at the project root — it should be served at https://yourdomain.com/auth.md in production.

Step 4: Add Integration Guidance

After generating the auth.md file, provide a brief integration checklist for the project:

Endpoints to implement:

• •POST /agent/auth — Registration endpoint (dispatches on type field)
• •POST /agent/auth/claim — Start OTP claim (user claimed flow)
• •POST /agent/auth/claim/complete — Finish OTP claim
• •POST /agent/auth/revoke — Accept provider logout tokens (agent verified flow only)

Discovery documents to serve:

• •/.well-known/oauth-protected-resource — Protected Resource Metadata
• •/.well-known/oauth-authorization-server — Authorization Server metadata with agent_auth block

401 responses should include:

WWW-Authenticate: Bearer resource_metadata="https://api.yourdomain.com/.well-known/oauth-protected-resource"

Security reminders:

• •Store only SHA-256 hashes of claim tokens and OTPs
• •Use CSPRNG for OTP generation, 10-minute TTL max
• •Rate limit: 5/hr anonymous, 60/hr identity_assertion per IP
• •Cache jti values for replay protection on ID-JAG flows
• •Never hardcode secrets — use .env files (per Mj's standing rules)

Step 5: Reference Material

If the user wants to dive deeper into the protocol, point them to:

• •Full spec reference: Read references/auth-md-spec.md in this skill's directory
• •Official docs: https://workos.com/auth-md/docs
• •GitHub repo: https://github.com/workos/auth.md
• •Example auth.md: https://github.com/workos/auth.md/blob/main/AUTH.md
• •Source video: https://youtu.be/Dqp_b8GHLXU (Michael Grinich, MCP Night keynote)

Protocol Quick Reference

For a comprehensive reference on the auth.md protocol — including the three roles (agent, agent provider, service), both flows (agent verified and user claimed), discovery documents, credential types, error codes, and security considerations — read references/auth-md-spec.md in this skill's directory. That file contains everything needed to implement auth.md correctly.