每个 Telm API 请求都用一个以 tk_live_ 开头的 API 密钥 进行身份验证——绝不用你的仪表盘登录。在你的账户中创建一个密钥，在 Authorization 头中把它作为 Bearer 令牌发送，它就会在你是管理员的群组上代表你的账户行事。如果一个密钥泄露，在仪表盘中撤销它并签发一个新的。
1API 密钥如何工作
Telm REST API 不使用你的浏览器会话。相反，每个请求都携带一个 API 密钥——一个以前缀 tk_live_ 开头、后跟随机字符的长机密字符串。该密钥标识你的账户并授权此次调用。
你从你的账户生成密钥，并可同时持有多个（例如，每个脚本或服务一个）。完整机密只在创建时显示一次；此后仪表盘会用密钥的短前缀（tk_live_ 加最初几个字符）列出它，以便你识别，而完整值在此之后绝不保留。
- 一个密钥形如 tk_live_ 后跟一长串随机字符串。
- 密钥在你的 仪表盘 中创建和管理。
- 完整机密只显示一次——立即复制它并存放在安全的地方。
- 像对待密码一样对待密钥：任何持有它的人都能以你的身份调用 API。
2在每个请求中发送密钥
在 Authorization 头 中使用 Bearer 方案传递密钥。头的值是单词 Bearer、一个空格，然后是你的密钥——例如，Authorization: Bearer tk_live_your_key_here。
对于无法方便地设置 Authorization 头的客户端，API 也接受在 X-API-Key 头中传入密钥。如果两者都存在，Authorization 头胜出。在生产环境中，通过 HTTPS 以外任何方式发出的请求都不被接受。
- 首选：发送 Authorization: Bearer tk_live_...
- 备选：改为在 X-API-Key 头中发送密钥。
- 每次调用的基础 URL 是 api.telm.com/api/public/v1。
- 在 开发者页面 上查看完整的端点列表和模式。
3一个密钥能访问什么
一个密钥严格代表你的账户行事。它只能读取或更改你账户是管理员的群组——针对任何其他群组的请求会返回 404，因此 API 绝不会透露一个你无法管理的群组甚至存在。
访问权限还取决于目标群组的套餐。垃圾检查端点在每日配额内对所有套餐开放，而完整 API（规则、设置、白名单、日志、分析、批量检查和 webhook）在所涉群组上需要 Pro 或更高套餐。
- 一个密钥只能触及你是管理员的群组。
- 针对你不管理的群组的请求返回 404，而非 403。
- 每日配额在你所有的密钥之间共享，按账户计数。
4撤销与轮换密钥
如果一个密钥被暴露——提交到仓库、粘贴进聊天，或以任何其他方式泄露——就从你的仪表盘 立即撤销它。撤销会立即生效：被撤销的密钥会在数秒内停止工作，而非在某段延迟之后。
由于每日配额按账户共享，撤销一个密钥不会重置你的用量计数器。定期轮换密钥是良好的卫生习惯：创建新密钥，把它部署到你的服务，确认它有效，然后撤销旧的，这样就没有停机。
- 从你的 仪表盘 撤销一个密钥；它几乎立即停止工作。
- 先创建替代密钥，将其推出，然后撤销旧密钥，以实现零停机轮换。
- 撤销一个密钥不会重置你的每日配额——那会在 UTC 午夜重置。
5身份验证错误
缺失、格式错误或被撤销的密钥会返回 401，带一个机器可读的错误码和一条人类可读的消息。如果你的请求突然开始以 401 失败，检查该密钥是否未被撤销，以及 Authorization 头是否严格拼写为 Bearer 加一个空格加密钥。
一个针对你不管理的群组的有效密钥会返回 404。一个套餐低于 Pro 的有效密钥调用仅限 Pro 的端点会返回 403，带一个 plan_required 码和一个升级提示。
- 401——密钥缺失、格式错误或被撤销。
- 404——目标群组不存在，或你不是其管理员。
- 403 plan_required——该端点在那个群组上需要 Pro 或更高。