SDK
安全最佳实践
API Key 保护、HTTPS 强制、数据处理规范，构建安全可靠的翠鸟集成
API Key 安全
API Key 是访问翠鸟账号的凭证，泄露后果等同于账号密码泄露。以下是必须遵守的安全规范：
绝对禁止：将 API Key 硬编码在源代码中并提交至 Git 仓库（包括私有仓库）。一旦泄露，请立即在控制台撤销该 Key 并重新生成。
推荐的 Key 管理方式
- 环境变量：通过操作系统环境变量或
.env文件（加入.gitignore）传递 - 密钥管理服务：生产环境推荐使用 AWS Secrets Manager、阿里云 KMS、HashiCorp Vault 等专业服务
- CI/CD 平台密钥仓库：在 GitHub Actions Secrets、Jenkins Credentials 等处存储，不在流水线脚本中明文出现
# 正确做法：通过环境变量读取
export CUINIAO_API_KEY="ck_live_xxxxxxxxxxxx"
// Java
String apiKey = System.getenv("CUINIAO_API_KEY");
# Python
import os
api_key = os.environ["CUINIAO_API_KEY"]
// Node.js
const apiKey = process.env.CUINIAO_API_KEY;
最小权限原则
为每个集成场景创建独立的 API Key，并仅申请该场景所需的最小权限范围。
- 只读数据同步脚本：仅需
leads:read、analytics:read - CRM 同步服务：需要
leads:read、leads:write - 内容发布工具：需要
resources:write - Webhook 处理服务：不需要 API Key，使用 Webhook Signing Secret 验证即可
在控制台 — API Keys 页面可以为每个 Key 单独设置权限范围（Scopes），并添加 IP 白名单限制 Key 的使用来源。
HTTPS 与传输安全
翠鸟 API 仅通过 HTTPS（TLS 1.2+）提供服务，拒绝所有 HTTP 请求。SDK 默认强制使用 HTTPS，请勿禁用 TLS 证书验证。
严禁在任何环境（包括开发环境）中禁用 TLS 证书验证（如
ssl_verify=False 或 hostnameVerifier 返回 true）。这会使您的应用暴露于中间人攻击风险。如在开发环境遇到证书问题，正确做法是将自签名证书添加至 JVM 信任库，而非跳过验证：
# 将自签名证书导入 JVM 信任库
keytool -import -alias cuiniao-dev \
-file dev-cert.crt \
-keystore $JAVA_HOME/lib/security/cacerts \
-storepass changeit
线索数据处理规范
翠鸟 API 返回的线索数据包含访客个人信息，处理时需遵守以下规范：
- 线索数据不应存入未加密的本地日志文件或日志系统（如直接写入 Elasticsearch 的明文索引）
- 传递给第三方系统（CRM、邮件系统）前，确认对方具备相应的数据安全能力
- 不再使用的线索数据应在合规要求的留存期内定期清理
- 开发/测试环境使用测试 API Key（
ck_test_），避免将真实线索数据用于调试
安全集成检查清单
- API Key 通过环境变量或密钥管理服务存储，未出现在代码中
- 生产环境与测试环境使用不同的 API Key
- 每个集成场景使用独立 Key，并配置最小权限范围
- 为 API Key 配置 IP 白名单（如适用）
- Webhook 端点实现了签名验证逻辑
- 未在任何环境中禁用 TLS 证书验证
- 线索数据日志已做脱敏处理
- 已订阅翠鸟安全公告邮件列表