认证与 API Key
如何获取、轮换并在请求中携带密钥。
所有 /api/v1 接口都要求在请求头中携带工作区范围的 Bearer Token。密钥可在
SyncPostly 仪表盘的 设置 → 开发者 → API keys 管理。
头部格式
Authorization: Bearer YOUR_SECRET_TOKEN- 不需要也不接受 cookie，接口是完全无状态的。
- 密钥绑定到工作区所有者，泄露后请立即删除并重建。
- 上传流程中两步请求都要带同一个 Authorization 头：先获取
POST /media/create-upload-url，再执行PUT /media/upload/{id}。
创建与轮换
- 打开 设置 → 开发者 → API keys。
- 点击 Create key，密钥只显示一次，请立即保存。
- 成员离职或密钥暴露时，删除旧密钥并重发。
- 轮换后同步更新 CI/CD 与后台任务的环境变量。
频率限制
- 读取：鼓励分页调用，仍受工作区级限流保护。
- 写入：受套餐限制。出现 429 时会返回
Retry-After，按秒数退避后再重试。
环境建议
- 将密钥存储在服务端环境变量（如
SYNCPOSTLY_API_KEY），通过 HTTP 客户端注入。 - 不要把密钥放进浏览器或移动端代码。