auth-md 1.0.0

Auth.md Agent Registration Check v1.0.0

Status

• Version: 1.0.0
• Check identifier: auth-md
• Input contract: [email protected]
• Output contract: [email protected]
• Scope: site

Abstract

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.

This check is isolated. It fetches /auth.md, /.well-known/oauth-protected-resource, and /.well-known/oauth-authorization-server itself and does not depend on another check's runtime output.

Motivation

Agent readiness is different from ordinary human login readiness. A site can have a perfectly usable login page, dashboard, OAuth button, or API key screen while still being opaque to an agent. Auth.md gives automated clients a stable registration contract and points them at OAuth Protected Resource Metadata and authorization-server metadata.

Normative Model

The check follows Auth.md Protocol Specification v1 as an emerging industry profile, not an IANA/IETF-registered standard.

The expected model is:

• /auth.md is Markdown or plain text and describes agent registration.
• Protected Resource Metadata is available at /.well-known/oauth-protected-resource per RFC 9728.
• Authorization Server Metadata is available at /.well-known/oauth-authorization-server or an issuer listed by the protected-resource metadata.
• Authorization Server Metadata advertises Auth.md v1 fields:
• agent_registration_endpoint
• agent_revocation_endpoint when supported
• credential_types_supported
• claim_ceremony_supported
• Supported Auth.md v1 credential types include agent_verified and user_claimed.
• Agents use issued access tokens as bearer credentials.

Legacy nested agent_auth metadata is treated as compatibility evidence, not the primary v1 shape.

Applicability

The check has two applicability tiers.

Tier 1 is explicit Auth.md applicability. It applies when:

• /auth.md returns HTTP 2xx.
• HTML, headers, API catalog, OpenAPI, MCP metadata, llms.txt, robots.txt, or documentation links to /auth.md.
• Authorization Server Metadata contains Auth.md v1 fields or legacy agent_auth.
• A 401 challenge or documentation points agents toward Auth.md.
• The site claims agent registration, agent verified flows, user claimed flows, MCP agent access, or machine clients acting on behalf of users.

Tier 2 is agent-readiness warning applicability. It applies when:

• the page shows login, signup, account, dashboard, credential, OAuth, API key, or developer-portal evidence; and
• no explicit Auth.md support is found.

Tier 2 absence is a warning, not a hard failure.

The check is not applicable when no meaningful auth/account/API access surface or Auth.md claim is detected.

Pass Criteria

The check passes when:

• /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 authorization-server metadata.
• The document mentions supported credential types or flows.
• The document covers claim/verified flow behavior and credential usage, expiry, errors, or revocation.
• Protected Resource Metadata is fetchable and has a valid resource plus authorization_servers.
• Authorization Server Metadata has valid Auth.md v1 fields, including agent_registration_endpoint and recognized credential types.

Warning Criteria

Warnings include:

• 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 authorization-server metadata is partially present but incomplete
• legacy agent_auth metadata is present without the preferred Auth.md v1 field names
• CORS or cache metadata is missing where browser-based or repeated agent access would benefit

Failure Criteria

Failures include:

• 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 authorization-server metadata is missing, invalid JSON, or lacks agent_registration_endpoint
• credential types are missing or not recognized
• metadata URLs are non-HTTPS, malformed, credential-bearing, localhost, private, or internal
• public Auth.md text or metadata exposes secrets, tokens, cookies, or credential values

Evidence Model

The check emits:

• applicability tier and signals,
• auth/login/account/API evidence from the scanned page,
• /auth.md status, content type, CORS header, length, and validation summary,
• protected-resource metadata status, content type, resource, authorization servers, scopes, and bearer methods,
• authorization-server metadata status, content type, agent_registration_endpoint, agent_revocation_endpoint, credential types, scopes, claim ceremony support, and legacy agent_auth summary if present,
• sanitized excerpts only, never credentials or tokens.

Validation And Scoring Steps

1. Detect applicability.
2. Fetch and validate /auth.md.
3. Fetch and validate OAuth Protected Resource Metadata.
4. Fetch and validate Auth.md authorization-server metadata.

If login/account/API access exists but /auth.md is absent, the check returns warning. If Auth.md is explicitly advertised but broken or inconsistent, the check returns fail.

Standard Behavior

Auth.md composes existing standards and drafts:

• RFC 9728 for OAuth Protected Resource Metadata.
• RFC 8414 for OAuth Authorization Server Metadata.
• ID-JAG draft for identity assertion authorization grants.
• Bearer token usage and OAuth-compatible scopes.

Non-Standard And Real-World Behavior

Auth.md is an emerging protocol with visible industry backing from WorkOS and ecosystem signals from services and agent providers named by auth-md.com. It is not currently registered as:

• an IANA well-known URI,
• an IANA OAuth metadata parameter,
• an IANA link relation,
• a W3C/browser standard,
• or an IETF RFC.

The check therefore treats missing Auth.md on generic sites as a warning only when auth/account/API surfaces are visible, and not applicable otherwise.

Non-Goals And Limitations

• The check does not perform live agent registration.
• The check does not create accounts or credentials.
• The check does not verify real OTP delivery.
• The check does not validate ID-JAG signatures or trusted issuer lists.
• The check does not replace OAuth/OIDC discovery or OAuth Protected Resource Metadata checks.
• The check does not assume every human-login site must hard-fail without Auth.md.

References

• auth-md.com/
• auth-md.com/specification
• auth-md.com/what-is-auth-md
• workos.com/auth-md
• github.com/workos/auth.md
• www.rfc-editor.org/rfc/rfc9728
• www.rfc-editor.org/rfc/rfc8414
• datatracker.ietf.org/doc/html/draft-ietf-oauth-identity-assertion-authz-grant

auth-md v1.0.0 Changelog

• Aligns validation with Auth.md Protocol Specification v1.
• Validates /auth.md, OAuth Protected Resource Metadata, and Auth.md authorization-server metadata from within the check.
• Warns when login, signup, account, API key, or credential surfaces are visible but /auth.md is absent.
• Treats legacy nested agent_auth metadata as compatibility evidence instead of the primary v1 shape.