怎么创建和管理 API 密钥？

简短回答

所有者和管理员打开 配置 › 设置 › API 密钥，点「创建」，给密钥起名、选权限和有效期，然后创建。密钥以 wck_ 开头，完整值只显示一次，请马上存进密钥管理工具。在服务端用 Authorization: Bearer 请求头发送。

只有服务端事件和日志导入需要密钥。网站脚本不用：它带的是公开的站点 Key，暴露出去也没关系。

创建密钥

1. 进入 配置 › 设置，打开「API 密钥」页签。创建和吊销密钥需要所有者或管理员角色。
2. 点「创建」，名字写清用在哪里，比如 order-service 或 nginx-importer。
3. 选择权限（见下文），只选这个集成需要的。
4. 选择有效期：永不过期、30 天、90 天或一年。
5. 点「创建」，从弹窗里复制密钥。关掉弹窗后只显示前缀。

每个密钥绑定在创建它的项目上。用它发送的事件会进入这个项目，所以请求里不用带项目 ID。

选择权限

列表里还有「读取报表」「管理定义」「签发嵌入」，供特定集成使用，只有指南要求时才勾选。缺少所需权限的请求返回 403。

一个服务、一种用途一个密钥。订单服务只需要「服务端 Track」，日志上传只需要「导入日志」。一个密钥泄露时，只需吊销一个集成，而不是全部。

使用密钥

放在下面任一请求头里：

Authorization: Bearer wck_xxxxxxxxxxxxxxxx

X-Api-Key: wck_xxxxxxxxxxxxxxxx

用服务端 SDK 时，从环境变量（比如 TAPCUB_API_KEY）读出来传给 apiKey。见从服务端发送事件和用 HTTP API 发送事件。

不要把密钥放进地址参数、前端代码、移动应用安装包或代码仓库。拿到密钥的人都能往你的项目里写数据。

轮换和吊销

密钥列表显示每个密钥的名称、前缀、权限、有效期和最近使用时间。

• 定期轮换： 用相同权限新建一个密钥并部署，确认「最近使用」已经转到新密钥，再吊销旧的。
• 立即吊销 可能泄露的密钥。用已吊销或已过期密钥的请求返回 401。
• 清理 几个月没用过的密钥。

找客服排查时，只提供前缀，不要发完整密钥。

常见问题

密钥丢了，还能再看吗？ 不能，完整值只显示一次。新建一个，再把旧的吊销。

哪些报错说明是密钥问题？ 401 NO_API_KEY（请求头里没有密钥）、401 BAD_API_KEY（密钥错误、已吊销或已过期）和 403（密钥缺少权限）。

一个密钥能写多个项目吗？ 不能，每个项目各建一个。

相关

• 从服务端发送事件
• 导入服务器日志
• 团队和角色