Skip to main content
Clawdot Gateway 通过 MCP 暴露能力，认证分两层：
  • Agent 身份 — 连接层请求头 Authorization: Bearer clw_...，标识调用方 Agent。每个 MCP 请求都要带。
  • 用户授权 — 业务工具的 consent_grant_id 参数（cg_ 前缀），标识”某个外卖用户已授权该 Agent”。它是工具参数，不是请求头。

​
认证链

不同工具需要不同级别的认证：
绑定类工具（request_user_bind / verify_user_bind）是拿授权的入口，本身不传 consent_grant_id。授权成功后，其余所有业务工具调用都要带上 consent_grant_id 参数。

​
API Key

格式为 clw_ 前缀加随机字符，例如 clw_a1b2c3d4...。通过连接层请求头 Authorization: Bearer clw_... 传递，每个 MCP 请求都需要它。在控制台 https://console.hicaspian.com/agents 创建 Agent 时生成。
API Key 在服务端只存哈希、不保留明文，每次请求按哈希比对。被禁用的 Key 立即失效。
代表”某个外卖用户已授权某个 Agent 使用某项能力”。授权成功后铸造出 consent_grant_id，之后每个业务工具调用都把它作为参数传入。

​
绑定流程

走绑定流程获取 consent_grant_id，支持 SMS 验证码与 H5 两种模式：
  1. request_user_bind 发起绑定（SMS 发验证码；H5 返回授权链接，仅需 Agent 身份，不传 consent_grant_id）
  2. verify_user_bind 确认绑定，成功铸造 consent_grant_id
详见 发起绑定 与 确认绑定。
verify_user_bind 成功返回：
  • consent_grant_id — 用户授权记录 ID（cg_ 前缀）
  • scopes — 授权能力范围，例如 ["taobao_flash.delivery"]
  • expires_at — 过期时间（ISO 8601）
过期，或被 revoke_user_bind 撤销后，该 consent_grant_id 即时失效；需重新走绑定流程获取新的。用户的地址等数据保留，重新授权后自动可用。

​
错误响应

认证 / 授权失败返回统一格式：
完整错误码见 错误处理。