# /auth.md agent authentication guide

> /auth.md agent authentication guide: A guide telling an agent which authentication flow to use. The fix: publish an auth.md guide.

- Source: /checks/auth-md
- Site: AgenticWebScore
- Language: English

---
A guide telling an agent which authentication flow to use.

| Property | Value |
| --- | --- |
| Check id | `auth-md` |
| Dimension | Protocol Discovery (25%) |
| Tier | Emerging — pool 5 pts |
| Weight inside tier | 2 |
| Impact | Medium |
| Maturity | Draft — A published specification that is not yet ratified. |
| Conditional | No |
| Publishing skill | `auth-md` |
| Standards | — |

## What the scanner requests

- `/auth.md`
- `/.well-known/auth.md`

## What is measured

The scanner GETs /auth.md and /.well-known/auth.md and reads the body. It passes when one returns 200 with markdown that names the registration methods the service accepts (anonymous, service_auth, identity_assertion), the endpoints an agent posts to (identity_endpoint, claim_endpoint) and the pointer to the service's OAuth protected-resource metadata. It partially passes when the file exists but describes only a human login page, with no method names or machine-readable endpoints.

## Reproduce it yourself

You do not have to take our word for any of this. Run the same measurement against your own domain:

```bash
DOMAIN=https://your-domain.example
for p in /auth.md /.well-known/auth.md; do printf '%s matches=' "$p"; curl -sS "$DOMAIN$p" | grep -cE 'identity_endpoint|claim_endpoint|identity_assertion|service_auth'; done
```

## The fix

This is the artifact to ship. It is the complete change, not a description of one.

```markdown
# auth.md - how agents authenticate with Example
You are an agent acting for a user. This service supports agentic registration:
discover -> register -> claim if needed -> exchange -> call.

## 1. Discover
Fetch the protected resource metadata for the API host:

    GET https://api.your-domain.example/.well-known/oauth-protected-resource

`resource` is the audience to request; `authorization_servers[0]` is the
authorization server whose metadata carries the `agent_auth` block.

## 2. Pick a method
- `identity_assertion` - you hold an ID-JAG bound to this service's `resource`.
- `service_auth` - you only have the user's verified email; a claim ceremony is required.
- `anonymous` - no user identity yet; claim later if the user wants ownership.

## 3. Register and exchange
POST to `agent_auth.identity_endpoint` with your chosen `type`, then exchange the
returned assertion at the authorization server's `token_endpoint` for an
access_token and send it as `Authorization: Bearer <token>`.

## 4. Revocation
Subscribe to `agent_auth.events_endpoint` and stop using a revoked identity.
```

> auth.md is a young convention (WorkOS-authored, spec dated June 2026): the file is the agent-readable skill, while the machine-readable contract lives in the agent_auth block of your /.well-known/oauth-authorization-server metadata, so publish both.

## Related checks

| Check | Tier | Impact | Same skill |
| --- | --- | --- | --- |
| `mcp-card` — MCP server card | Essential | High | — |
| `openapi` — OpenAPI definition | Essential | High | — |
| `oauth-discovery` — OAuth discovery documents | Essential | High | — |
| `api-catalog` — API catalog | Recommended | Medium | — |
| `agent-skills` — Agent Skills declaration | Recommended | Medium | — |
| `a2a-card` — A2A agent card | Recommended | Medium | — |
| `a2a-signed` — Cryptographically signed agent card | Emerging | Medium | — |
| `webmcp` — WebMCP browser tool declaration | Emerging | Medium | — |