鉴权与 API key

本页说明 WebAgent 的 API key 形态、每次请求如何携带、以及创建、撤销、轮换的流程。

每次请求带 bearer token：

Authorization: Bearer wa_xxxxxxxxxxxxxxxxxxxxxxxx

Key 形态

• 前缀 wa_，"web agent" 缩写（仿 Stripe sk_*）
• 长度 前缀后 28+ 字符。当作不透明 token
• 范围 单 project；多个 project 各创建一个 key
• 可见性 创建时只显示一次；丢了只能撤销重建
• 撤销 软删除 + 1 小时 grace，不让在跑的 task 中途 401

Key 放哪

• 本地开发 环境变量、.env.local（已在 .gitignore 里）
• 生产 用你的 secret manager（Vault / AWS Secrets Manager / GCP Secret Manager / ……）
• 永远不要提交进 git。Console 的 Get Code 对话框默认用占位符

多 project

一个用户可以有多个 project。API path 把 project 直接编进去：

GET /v1/projects/{project_id}/do_anything/sessions

没有 X-Project-Id header。path 把租户写明——一条 curl 打错 project ID 就是不同的 URL，不会静默跨租户。

轮换

可以同时持有两个有效 key：

1. 在 Settings → API Keys 创建新 key
2. 用新 key 部署
3. 撤销旧 key。旧 key 还能用 1 小时；部署完成后自动 401

错误

状态码	code	含义
401	unauthorized	缺失 / 错误 / 过期 / 撤销超 grace
403	forbidden	key 有效但无权访问该 project
429	rate_limit_exceeded	per-key 并发或频率上限

接下来

• 计费与额度 —— 每个 task 多少钱
• Sessions 与 Tasks —— 一次请求实际创建什么