API REFERENCE
认证与授权
了解翠鸟 API 的认证机制，包括 API Key 管理、OAuth 流程与访问令牌生命周期
API Key 认证
翠鸟 API 使用 Bearer Token 方式进行认证。所有请求需在 HTTP Header 中携带有效的 API Key：
Authorization: Bearer ck_live_xxxxxxxxxxxxxxxxxxxx
API Key 分为两种环境：
- 生产密钥（
ck_live_前缀）— 用于生产环境，操作真实数据 - 测试密钥（
ck_test_前缀）— 用于开发调试，数据不计入统计，不触发 Webhook
API Key 是敏感凭证，请勿将其硬编码在前端代码或提交至公开代码仓库。建议通过环境变量或密钥管理服务（如 AWS Secrets Manager）进行存储。
OAuth 2.0 授权流程
如需代表其他用户调用 API（例如构建翠鸟集成应用），应使用 OAuth 2.0 授权码流程，而非直接使用对方的 API Key。
1
引导用户前往授权页面
将用户重定向至 https://app.cuiniao.com/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT&scope=leads:read+resources:write&response_type=code
2
用户授权确认
用户登录翠鸟账号并确认授权范围，系统将携带授权码（code）重定向回您的 redirect_uri。
3
换取 Access Token
在服务端用授权码换取 Access Token，此步骤需携带 Client Secret，必须在服务端完成。
4
使用 Token 调用 API
将 Access Token 作为 Bearer Token 放入请求头，即可以该用户身份调用 API。
# 步骤3：用授权码换取 Access Token
curl -X POST https://api.cuiniao.com/oauth/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=authorization_code" \
-d "code=AUTH_CODE_FROM_REDIRECT" \
-d "client_id=YOUR_CLIENT_ID" \
-d "client_secret=YOUR_CLIENT_SECRET" \
-d "redirect_uri=YOUR_REDIRECT_URI"
// Token 响应
{
"access_token": "at_xxxxxxxxxxxxxxxxxxxxxxxx",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "rt_yyyyyyyyyyyyyyyyyyyyyy",
"scope": "leads:read resources:write"
}
Token 有效期与刷新
Access Token 的有效期为 1小时（expires_in: 3600）。过期后使用 Refresh Token 获取新的 Access Token，无需用户重新授权。
# 使用 Refresh Token 刷新 Access Token
curl -X POST https://api.cuiniao.com/oauth/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=refresh_token" \
-d "refresh_token=rt_yyyyyyyyyyyyyyyyyyyyyy" \
-d "client_id=YOUR_CLIENT_ID" \
-d "client_secret=YOUR_CLIENT_SECRET"
Refresh Token 有效期为 90天，每次刷新后原 Refresh Token 失效，同时颁发新的 Refresh Token。如果 Refresh Token 也过期，用户需重新完成授权流程。
建议在 Access Token 到期前 5 分钟主动刷新，避免因 Token 恰好在请求过程中过期导致请求失败。
权限范围（Scopes）
OAuth 授权时可按需申请最小权限范围，减少安全风险。
resources:read— 读取内容资源列表与详情resources:write— 创建、更新、发布内容资源leads:read— 读取线索数据leads:write— 创建和更新线索analytics:read— 读取分析数据webhooks:write— 管理 Webhook 端点users:read— 读取团队成员信息