Protocol Discovery · Emerging · Medium impact
/auth.md agent authentication guide
A guide telling an agent which authentication flow to use.
- Emerging
- Medium impact
- Draft standard
| 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:
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.
# 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.
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 | — |