---
name: auth-md
description: Publish auth.md instructions that help agents authenticate safely.
---

# auth.md

Use this skill when a CanAgentUse report flags `auth-md`. The goal is to implement the exact public signal the scanner evaluates, not to perform a broad redesign. Treat the report evidence as the failing test case and make the smallest production-quality change that turns that evidence into a pass.

## What This Check Evaluates

This check validates whether a site publishes Auth.md-style agent registration guidance. Auth.md is an emerging open protocol authored by WorkOS and documented at `auth-md.com`. It lets agents discover how to register, claim a user, obtain credentials, use bearer access tokens, and recover from expired credentials without scraping human login flows.

## Pass Criteria

- `/auth.md` returns HTTP 200.
- The response content type is Markdown or plain text.
- The document contains actionable registration guidance.
- The document explains or links to protected-resource metadata discovery.
- The document explains or links to authori

## Failure And Warning Signals

**Failures usually mean:**

- the site explicitly claims Auth.md, agent registration, agent-verified, user-claimed, or MCP agent access support but `/auth.md` is missing
- `/auth.md` is unreachable, served as incompatible content, or is not meaningful Markdown/plain text
- `/auth.md` lacks actionable agent registration guidance
- required protected-resource metadata is missing, invalid JSON, or has an invalid `resource`
- required authori

**Warnings usually mean:**

- generic login, account, dashboard, developer, OAuth, API-key, or credential evidence is present but no explicit Auth.md signal is found
- `/auth.md` is present but omits recommended lifecycle details such as expiry, errors, revocation, or claim ceremony behavior
- `/auth.md` is readable but uses a generic content type
- protected-resource metadata or authori

## Implementation Workflow

1. Start from the failed CanAgentUse evidence: URL, status code, content type, parsed fields, and failed criterion ID.
2. Locate the route, static asset, metadata generator, schema component, server config, or API endpoint that owns that public signal.
3. Implement the missing or malformed signal with real production values. Keep it same-origin unless the check explicitly supports external URLs.
4. Validate locally with direct HTTP requests, JSON/XML parsing, schema validation, or header inspection before relying on a full rescan.
5. Re-run the scan and compare the new evidence with the original failed criterion.

## Fix The Reported Criterion

- **Auth surface exists but Auth.md is missing** (warning): Publish `/auth.md` when the site has login, signup, account, API credential, or agent-registration surfaces that agents need to understand.
- **/auth.md is missing or not usable as agent registration guidance** (fail): Serve `/auth.md` as Markdown or plain text with Auth.md v1 guidance: registration, credential types, protected-resource metadata, authorization-server metadata, claim ceremony, revocation, and error handling.
- **Auth.md protected-resource metadata is missing or incomplete** (fail): Publish `/.well-known/oauth-protected-resource` with a valid `resource` URL and `authorization_servers` array so agents can discover the authorization server.
- **Authorization-server metadata lacks Auth.md v1 fields** (fail): Add Auth.md v1 fields to authorization-server metadata, including `agent_registration_endpoint`, `credential_types_supported`, and `agent_revocation_endpoint` where supported.

## Implementation Pattern

- Publish machine-readable metadata at the well-known or documented discovery path.
- Include clear names, descriptions, versions, endpoint URLs, auth requirements, and capability boundaries.
- Make every advertised URL resolvable and every advertised action actually supported.
- Document dangerous, paid, authenticated, or state-changing actions explicitly.

## Validate Before Rescanning

Validate through the CanAgentUse MCP server when the agent can use MCP tools:

1. Connect to the hosted Streamable HTTP MCP endpoint:

   ```text
   https://canagentuse.com/api/mcp
   ```

   This endpoint uses MCP Streamable HTTP. Configure it in the agent's MCP client as an HTTP/streamable HTTP server.

2. For stdio-based MCP clients, install and run the npm package:

   ```bash
   npx -y @canagentuse/mcp
   ```

3. Use the MCP tools to verify the specific fix.

   - Run `scan_website` with the public production or preview URL.
   - Use `list_checks` to confirm the check id and public docs URL.
   - Use `get_fix_guidance` with `auth-md` if the scan still reports a failure or warning.
   - Use `get_skill` with `auth-md` to reload this skill after updates.
   - Compare the new scan evidence for `auth-md` with the original failed criterion.

Validate through HTTP by creating and reading a hosted scan when MCP is unavailable:

```bash
SCAN_ID=$(curl -sS -X POST https://canagentuse.com/api/scans \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://YOUR-SITE.com"}' | jq -r '.scanId // .id')

curl -sS "https://canagentuse.com/api/scans/$SCAN_ID/result" | jq .
```

After deployment, re-run the same check and verify the report evidence now satisfies the pass criteria.

## Common Mistakes To Avoid

- Do not ship sample domains, placeholder names, fake dates, fake prices, fake reviews, or unsupported capabilities.
- Do not fix a scanner warning by hiding the signal; make the public evidence accurate and parseable.
- Do not change unrelated SEO, auth, security, or commerce behavior just to satisfy this one check.

## Public Check Documentation

- https://canagentuse.com/suites/2026.06.10/checks/auth-md/1.0.0