auth.md：让 AI Agent 代替用户完成注册的开放协议
阅读时间: 大约 10 分钟
auth.md：让 AI Agent 代替用户完成注册的开放协议
当 AI Agent 能自主行动时，它遇到的第一个摩擦往往是注册：想调用某个 SaaS 的 API，却发现要先填表单、收验证邮件、在浏览器里点一通。WorkOS 提出的开放协议 auth.md 就是为消除这一步而生——服务商在自己域名下放一个 auth.md 文件，声明”我们支持 Agent 代为注册”，Agent 读懂后自动完成身份核验与凭证颁发。本文基于 WorkOS 官方文档与协议仓库 workos/auth.md，分析它怎么工作、建立在哪些标准之上。
一、它要解决什么
传统 OAuth 解决的是”已有用户，授权一个客户端访问”。但 Agent 场景多了一步：账号本身都还没建。auth.md 把这条链路标准化为一条固定流程：
discover → register → (claim if needed) → exchange for an access_token → call API → handle revocation
服务端在 https://service.example.com/auth.md 放一份 Markdown，里面用自然语言告诉 Agent：支持哪些注册流程、有哪些 scope、各端点怎么调。Agent 读完整份文件，按编号步骤从上往下执行。
二、两跳发现：auth.md 是散文，PRM 才是机器可读真相
协议的一个关键设计是职责分离。auth.md 本身是给 Agent 读的”说明书”，而真正权威的端点信息由 OAuth 既有的结构化元数据承担：
- 第一跳：Agent 调用受保护 API 收到
401 Unauthorized，响应头里带WWW-Authenticate: Bearer resource_metadata="…"，指向 Protected Resource Metadata（PRM）； - 第二跳：Agent 拉取
/.well-known/oauth-protected-resource，读到resource、authorization_servers、scopes_supported、bearer_methods_supported；再进一步访问/.well-known/oauth-authorization-server，读到标准 OAuth 字段（issuer、token_endpoint、revocation_endpoint、grant_types_supported）以及协议自定义的agent_auth块——里面有identity_endpoint、claim_endpoint、events_endpoint、支持的身份类型与断言类型。
这背后复用了一系列 RFC：RFC 8414（授权服务器元数据）、RFC 7009（撤销）、RFC 7523（JWT Bearer 授权）、RFC 8628（设备授权流程），以及 ID-JAG 身份断言。auth.md 没有另起炉灶，而是在现有 OAuth 上扩展。
三、三种注册方式
POST /agent/identity 根据 Agent 手上有什么走不同分支：
| 方式 | 适用场景 | 行为 |
|---|---|---|
identity_assertion | Agent 持有可换成本服务 audience 的 ID-JAG | 立即完成，返回 identity_assertion、过期时间与 scopes；若验证邮箱命中已有账号则返回 401 interaction_required（首绑 step-up） |
service_auth | 只知道用户邮箱 | 返回 claim_token 与 user_code/verification_uri，需走完 claim 仪式才铸出断言 |
anonymous | 两者都没有 | 直接发预断言 + claim_token，Agent 可先用 pre_claim_scopes 工作，所有权以后再认领 |
一个重要安全约束：每次注册都只返回服务端签名的 identity_assertion，绝不直接发凭证；Agent 再拿断言去 /oauth2/token 换一个短期、可撤销、带 scope 的 access_token。这与 FAQ 里”发什么给 Agent”的回答一致——复用你已有的 API 鉴权。
四、Claim 仪式：类设备授权，代码不经邮件
当需要用户介入时，协议采用 RFC 8628 设备授权式的仪式：服务端从不邮件发码——user_code 由 Agent 直接展示给用户，用户在服务端自己的页面登录后输入这个码（而不是回给 Agent）。Agent 用 claim_token 以 grant_type=urn:workos:agent-auth:grant-type:claim 轮询 /oauth2/token 直到完成。
这两种人机协作模式被官方称为：agent verified（Agent 的身份提供方为用户背书，无人工介入）与 user claimed（无需提供方，Agent 展示码、用户登录确认）。多数应用两种都支持，由 Agent 选合适的。
五、口径与局限
- WorkOS 是协议作者：尽管官方反复强调”开放、不绑定 WorkOS 基础设施、无需 WorkOS 账号”，但自定义 grant type 命名空间是
urn:workos:agent-auth:*，events_supported的 schema 也在schemas.workos.com下——标准仍有明显的厂商出身痕迹，能否进入 IETF 标准化流程尚待观察。 - “agent verified”是无人工信任链：它依赖 Agent 的身份提供方为用户背书，背书强度取决于该 IdP 的核验级别；对高权限操作，服务端仍靠
interaction_required/login_required等 401 把人拉回来。 - 发现依赖约定与头：
auth.md是散文，机器必须靠 PRM 才知道端点；若服务端既不在 401 里带WWW-Authenticate、也不部署.well-known，Agent 只能靠文档/SDK 指针找到文件——体验会打折。 - 早期阶段：官方自述正在”与早期采用者一起塑造协议”，落地列表虽已有 Cloudflare、Neon、Firecrawl、Resend、Parallel.ai、monday.com 等，但生态仍在早期，跨 Agent/跨服务的互操作案例还很少。
六、客观分析：意义与谁该关注
价值：它把”Agent 入驻一个新服务”从”人填表单”压缩成”读一个 Markdown + 几轮 OAuth 交换”，且凭证是短期可撤销的，契合 Agent 按需、最小权限调用的安全模型；全部建立在现有 OAuth 标准上，服务端复用已有鉴权设施。
局限：信任模型（尤其是无人工的 agent verified）仍需服务端仔细配置 step-up；协议由单一厂商起草，长期治理与命名空间中立性待验证；对完全没有 OAuth 基础设施的小服务，接入成本不低。
适合谁：提供 API、希望被 Agent 生态自动接入的 SaaS（“让你的应用 agent-ready”）；以及自己做 Agent 平台、需要代表用户入驻各种服务的身份提供方。