什么是 Auth.md？AI Agent 的 OAuth 发现协议

最后更新：2026 年 6 月 17 日。

一个 AI agent 调用 API，拿到 401 Unauthorized，接下来该怎么办？人类会打开文档、注册账号、批准 scope，再把 API key 粘回工具里。Auth.md 想把这段人工绕路变成一个 agent 能自己读取的根目录 Markdown 文件，再配合 OAuth discovery metadata 完成注册和授权。

Auth.md 重要，是因为 agent authentication 的失败方式和人类登录不同。Agent 需要有 scope 的凭证、清楚的 consent 路径、可撤销的 delegation，以及足够机器可读的说明，避免靠猜。WorkOS 在 2026 年 5 月 21 日发布 Auth.md，把它定位成基于 Markdown、OAuth Protected Resource Metadata 和标准 token exchange 的开放 agent registration protocol。

目录

• 什么是 Auth.md？
• 为什么需要 Auth.md？
• Auth.md 如何工作？
• Auth.md、llms.txt 和 OAuth Metadata 的区别
• 一个 Auth.md 文件应该包含什么？
• 如何用 URL to Any 检查 Auth.md
• Auth.md 实施检查清单
• FAQ
• 总结

什么是 Auth.md？

Auth.md 是一个放在服务根目录的 Markdown 文件，通常是 https://service.example.com/auth.md，用于告诉 AI agent 如何发现 OAuth resource、代表用户注册、请求 scopes、完成 claim flow、把 assertion 换成 access token，并处理凭证撤销。

核心思路很直接：Auth.md 给 agent 一份可读的操作说明，OAuth metadata 给 agent 一份权威的机器数据。WorkOS 的 Auth.md 文档说明，这个文件描述服务支持哪些 registration flows、开放哪些 scopes、注册后如何操作；而 /.well-known/oauth-protected-resource 里的 Protected Resource Metadata 仍然是运行时的权威来源。

Auth.md 不是普通文档页。普通文档页是给开发者看的，开发者可以补全上下文、点击导航、做判断。Auth.md 是给 agent 执行流程用的，它需要短、顺序清楚、歧义少。它用 headings 做导航，用 fenced http 和 json code blocks 表达请求形状，用明确文字说明错误恢复方式。

Auth.md 也不是 API key 教程。API key 往往权限宽、生命周期长、很难按一次 delegation 审计。Auth.md 围绕 scoped OAuth credentials 和显式 registration flows 设计，因此服务可以知道哪个 agent 行动、代表哪个用户、授予了哪些 scopes，以及以后怎么撤销。

为什么需要 Auth.md？

Auth.md 出现，是因为 sign-up form 和传统 OAuth consent screen 默认由人类启动集成。AI agent 把顺序反过来了：agent 在任务过程中发现一个服务，需要先注册，只在服务要求时再向用户请求 consent。

WorkOS 用一个常见 API 场景解释这个问题：agent 调用 API，收到 401。没有 Auth.md 时，agent 要么放弃，要么要求用户手动创建账号并粘贴凭证，要么依赖一个只有该服务自己知道的自定义 endpoint。Auth.md 试图让第一次未授权请求变成可继续执行的流程。

Auth.md 把三个已有概念接在一起：

组成部分	在 Auth.md 中的作用	Agent 为什么需要
根目录 Markdown 文件	在 /auth.md 提供人类和 agent 都能读的说明	让 agent 不需要预训练每个服务，也能理解注册流程
OAuth Protected Resource Metadata	在 /.well-known/oauth-protected-resource 提供 JSON metadata	告诉 agent resource、authorization servers、scopes 和 bearer methods
OAuth token exchange 与 revocation	使用 /oauth2/token、/oauth2/revoke 等标准 endpoint	让服务获得 scoped access token 和熟悉的撤销模型

OAuth Protected Resource Metadata 标准 RFC 9728 发布于 2025 年 4 月，定义了客户端和授权服务器如何获取 protected resource 交互信息的 metadata 格式。Auth.md 是建立在这个 discovery layer 之上，而不是替代它。

Auth.md 如何工作？

Auth.md 的工作方式是一条有顺序的 discovery 和 registration flow。Agent 找到服务 metadata，读取 Auth.md 的步骤说明，选择服务支持的注册方式，拿到 identity assertion，再到 OAuth token endpoint 换取 access token，最后在凭证过期或撤销时恢复。

我们检查 WorkOS 的参考 AUTH.md 时，可以看到模板围绕 6 个操作步骤组织：discover、pick a method、register、必要时完成 claim ceremony、exchange assertion、use access token。这个结构对 agent 友好，因为每一步都对应一个明确决策。

落到实际流程，Auth.md 通常这样走：

1. Agent 访问 protected API。 它可能收到带有 Protected Resource Metadata URL 的 WWW-Authenticate header。
2. Agent 获取 Protected Resource Metadata。 Metadata 告诉 Auth.md-aware agent protected resource URL、显示名称、支持的 scopes、bearer methods 和 authorization server 位置。
3. Agent 获取 Authorization Server metadata。 这份 metadata 包含 issuer、token_endpoint、revocation_endpoint 等标准 OAuth 字段，以及 Auth.md 相关的 agent_auth block。
4. Agent 读取 Auth.md。 Auth.md 解释支持哪些 registration types，以及如何调用 registration 和 claim endpoints。
5. Agent 执行注册。 根据服务能力，它可以使用 agent-verified identity assertion、基于 email 的 user-claimed flow，或 anonymous pre-claim flow。
6. Agent 换取 token。 注册后，agent 把服务签名的 identity assertion 交给 OAuth token endpoint，获得 scoped access token。

WorkOS 描述了两类主要 Auth.md registration flows。Agent verified flow 依赖可信 agent provider，例如 OpenAI、Anthropic、Cursor，用 ID-JAG 断言用户身份。User claimed flow 让用户在服务自己拥有的页面上确认 code，所以即使 agent provider 不能 mint ID-JAG，服务也可以支持 Auth.md。

User claimed flow 对早期采用尤其关键。Agent 可以只拿到 email，甚至没有身份信息，然后让用户完成一个 6 位 code 的 claim ceremony。WorkOS 说明，这个 ceremony 借鉴 OAuth device authorization 的形状，但使用 Auth.md 专用 grant，避免和服务已有的 device-code 实现冲突。

Auth.md、llms.txt 和 OAuth Metadata 的区别

Auth.md、llms.txt、OAuth metadata 都是 discovery 相关文件，但回答的问题不同。Auth.md 回答“agent 如何认证和注册？”llms.txt 回答“LLM 应该读哪些内容？”OAuth metadata 回答“这个 protected resource 的权威 endpoint 和 capability 是什么？”

文件或 endpoint	主要读者	常见位置	主要任务
Auth.md	AI agent 和开发者	/auth.md	解释 agent registration、scopes、claim flow、token 使用和 revocation
llms.txt	LLM crawler 和 retrieval agent	/llms.txt	指向重要站点内容和 LLM 友好的阅读路径
OAuth Protected Resource Metadata	OAuth client、agent、authorization server	/.well-known/oauth-protected-resource	声明 resource identity、scopes、authorization servers 和 bearer methods
OAuth Authorization Server Metadata	OAuth client 和 agent	/.well-known/oauth-authorization-server	声明 issuer、token endpoint、revocation endpoint、grants，以及 Auth.md 的 agent_auth extension

这个区别影响实现方式。Auth.md 应该短而可执行，不应该塞进完整 API reference。如果 Auth.md 和 Protected Resource Metadata 冲突，agent 应该以 metadata 为准，因为 metadata 是运行时契约。

最实用的理解是：Auth.md 是 agent-facing guide，OAuth metadata 是 source of truth。人类可以读 Auth.md 理解流程；agent 可以解析 Auth.md 决定下一步；服务则依赖 OAuth metadata 和 endpoints 执行真正的安全边界。

一个 Auth.md 文件应该包含什么？

好的 Auth.md 文件只包含 agent 注册、行动、刷新和恢复所需的信息。WorkOS 建议文件保守、信息密度高，并按 agent 的执行顺序组织。

Auth.md section	应该回答什么	检查项示例
Title and intro	这是什么服务？真实 host 是哪些？	Resource server、authorization server、support contact
Discover	Protected Resource Metadata 在哪里？哪些字段重要？	resource、authorization_servers、scopes_supported
Pick a method	支持哪些 Auth.md registration flows？	identity_assertion、service_auth、anonymous
Register	哪个 endpoint 接收 registration body？	/agent/identity、request shape、response shape
Claim ceremony	需要用户确认时如何完成？	user_code、verification_uri、polling interval
Exchange assertion	Agent 如何拿到 access token？	/oauth2/token、JWT bearer grant、scopes
Use credential	Agent 如何调用 API，遇到 401 怎么恢复？	Bearer header、expiry behavior
Errors and revocation	失败时 agent 应该做什么？	invalid_grant、authorization_pending、/oauth2/revoke、event delivery

请求形状重要时，Auth.md 应该使用 code blocks。Fenced http block 方便 agent 识别 endpoint 和 method。Fenced json block 方便提取必填字段。错误码表能避免 agent 反复发出无效请求。

Auth.md 不应该包含产品营销文案、泛教程，或每一个 API endpoint。文件越长，agent 越难稳定解析。让 Auth.md 聚焦 registration 和 operation，更深的 API 行为交给普通文档，并在需要时从 Auth.md 链过去。

如何用 URL to Any 检查 Auth.md

你可以把根目录 Markdown 文件转换成 Markdown、Text 或 JSON，检查 agent-critical 信息是否能在提取后保留下来。这里的目标不是“抓取” Auth.md，而是在依赖它之前，确认 agent 或 LLM 能干净读取这个文件。

先准备一个真实 Auth.md URL，例如 https://service.example.com/auth.md，或者在起草阶段使用 GitHub raw template。然后用 3 个视图检查：

URL to Any 视图	检查 Auth.md 的什么	最适合
URL to Markdown	Headings、tables、code fences、links、ordered steps	验证 LLM 将读取到的 Auth.md 结构
URL to Text	纯文本说明和错误恢复	检查没有格式时是否仍然可理解
URL to JSON	提取的 links、sections、structured fields	自动检查 endpoints、scopes 和缺失 sections

把 Auth.md URL 粘到 URL to Any，先选择 Markdown。转换通常约 2 秒完成，你会得到一份干净副本，可以粘进 prompt、和源文件 diff，或交给 review agent。然后跑 Text 看 fallback reading path，再跑 JSON 检查 links 和结构化信息。

一个轻量 Auth.md 检查流程如下：

1. 确认根路径可访问。 Auth.md URL 应该返回 200 和可读 Markdown，而不是 HTML 营销页或 redirect loop。
2. 检查顶层流程。 Markdown 输出应保留主要步骤：discovery、method choice、registration、claim、token exchange、credential use、errors、revocation。
3. 验证 endpoint 引用。 Auth.md 应指向 Protected Resource Metadata、authorization server metadata、registration endpoint、claim endpoint、token endpoint 和 revocation endpoint。
4. 对比 scopes。 Auth.md 中的 scope inventory 应与 metadata 里的 scopes_supported 一致，或清楚解释为什么只是子集。
5. 复核错误恢复。 Text 输出仍应解释 interaction_required、login_required、authorization_pending、invalid_grant 等 Auth.md 常见失败该如何处理。
6. 自动化明显检查。 JSON 输出可以用来标记缺失 links、缺失 endpoint 字符串、重复 sections，或缺少 revocation path。

即使你的服务还没准备好发布 Auth.md，这个检查步骤也有价值。它能抓住 agent 最容易出错的问题：说明含糊、链接断裂、scope 缺失，以及在浏览器里看着没问题但转成纯文本后坍塌的 section。

Auth.md 实施检查清单

发布 Auth.md 前，要同时检查 Markdown 文件和 OAuth runtime。一个看起来有效的 Auth.md 文件，如果和 metadata 或 endpoints 不一致，仍然不够。

检查项	通过条件
根目录 Markdown 文件	https://service.example.com/auth.md 返回干净 Markdown，并写明真实 resource 和 auth hosts
Protected Resource Metadata	/.well-known/oauth-protected-resource 返回 resource、authorization_servers、scopes_supported 和 bearer method data
Authorization Server metadata	/.well-known/oauth-authorization-server 返回 OAuth endpoints 和 agent_auth block
Registration endpoint	/agent/identity 只接受服务实际支持的 registration types
User consent	Agent verified 和 email-based flows 在 identity assertion 前展示 resource name、scopes 和用户 consent
Claim ceremony	User claimed flows 把 code 绑定到目标登录用户，并让过期尝试失效
Token exchange	Token endpoint 支持 JWT-bearer assertion exchange；如果启用 user claimed flow，也支持 Auth.md claim grant
Revocation	Access-token revocation 和 registration-level revocation 都有说明
Audit trail	Registrations、claims、token exchanges、revocations 和 failures 都记录足够排查的上下文

这篇博客本身适合使用 Article 和 FAQPage schema。如果把检查流程作为编号操作步骤呈现，也可以补充 HowTo schema。

FAQ

Auth.md 一句话是什么？

Auth.md 是一个根目录 Markdown 文件，用来说明 AI agent 如何发现 OAuth metadata、向服务注册、请求 scopes、获得 access token，并代表用户处理凭证撤销。

Auth.md 是正式 OAuth 标准吗？

Auth.md 不是 OAuth RFC。它是 WorkOS 提出的开放协议，建立在现有 OAuth 标准之上，尤其是 OAuth Protected Resource Metadata、Authorization Server Metadata、JWT bearer token exchange、类似 device authorization 的 claim ceremony，以及 token revocation。

Auth.md 和 OAuth Protected Resource Metadata 有什么区别？

Auth.md 是 agent 用来理解 registration workflow 的文字说明。OAuth Protected Resource Metadata 是机器可读的 JSON source of truth，负责 resource identity、authorization servers、scopes 和 bearer methods。如果两者冲突，应以 metadata 为准。

Auth.md 和 llms.txt 有什么区别？

Auth.md 用于 authentication 和 agent registration。llms.txt 用于内容发现和 LLM-friendly reading path。一个服务可以同时发布两者：Auth.md 回答“我如何拿到 scoped credentials？”llms.txt 回答“我应该读哪些 docs？”

所有 agent 都需要 agent verified Auth.md flow 吗？

不需要。Agent verified Auth.md flow 只有在 agent provider 能 mint 可信 ID-JAG，且服务信任该 provider 时才成立。基于普通 LLM API 或不受信任 runtime 的 agent 通常需要 user claimed flow，让用户在服务自己拥有的页面确认 code。

URL to Any 能验证 Auth.md 实现吗？

URL to Any 可以帮助检查 Auth.md 文件在 Markdown、Text 和 JSON 形态下是否可读、结构是否清楚。它不能替代 OAuth endpoints、signature verification、token expiry、revocation 或 claim binding 的运行时安全测试。

Auth.md 应该包含每个 API endpoint 吗？

不应该。Auth.md 应包含 discovery、registration、token exchange、credential use、errors 和 revocation 所需的 endpoints。完整 API reference 应放在普通文档里，在 agent 需要更深操作上下文时从 Auth.md 链过去。

总结

Auth.md 是一个小文件，任务很窄：帮助 AI agent 发现如何向服务注册和认证，而不是让人类把文档翻译成凭证。它的价值在于把可读 Markdown、OAuth metadata 和 scoped token flow 组合起来，而不是重新发明一套 authentication stack。

如果你正在评估 Auth.md，先从文件本身开始。保持它短、顺序清楚、可测试。把它转成 Markdown、Text 和 JSON，检查 agent 是否仍能找到 endpoints、scopes、registration flows、claim behavior 和 revocation path。

想在发布前检查一个 Auth.md 文件？免费试用 URL to Any ->，把根目录 URL 转成 Markdown、Text 或 JSON，几秒内完成检查。