身份认证

helodata REST API 使用 Bearer Token 认证。每个 Token 归属你的账号，可限定到特定资源或操作。

签发 Token

1. 控制台 → API → 新建 Token。
2. 起名并选择 scopes（见下文）。
3. 复制 Token——仅显示一次。我们只存哈希；丢失无法恢复，只能轮换。

使用 Token

放在 Authorization 头，格式 Bearer <token>：

curl -H "Authorization: Bearer hel_live_01HXabc..." \
     https://api.helodata.com/v1/users/me

Scope

Scope	权限
read	所有资源只读
subusers:write	创建/更新/删除子账号
whitelists:write	管理 IP 白名单
orders:write	下单与修改订单
traffic:read	读流量与用量
reports:write	创建定时报表
*	账号完全权限（谨慎使用）

按最小权限给每个调用方分配 scope。常见做法：一份只读 Token 给分析仪表盘，一份 orders:write 给分发服务。

Token 格式

hel_live_01HXabc...                # 生产
hel_test_01HXabc...                # 沙箱（即将上线）

前缀后 64 字符，密码学随机。

轮换

轮换 Token：

1. 控制台 → API → {token} → 轮换。
2. 生成新 Token，旧 Token 继续有效 24 小时，之后返回 401。
3. 在 24 小时宽限期内把新 Token 滚到所有部署。

程序化：

curl -X POST -H "Authorization: Bearer EXISTING_KEY" \
     "https://api.helodata.com/v1/tokens/{token_id}/rotate"

响应体返回新 Token。

撤销

curl -X DELETE -H "Authorization: Bearer EXISTING_KEY" \
     "https://api.helodata.com/v1/tokens/{token_id}"

撤销后立即失效。

Token IP 白名单（可选）

在 控制台 → API → {token} → 源 IP 中限定特定来源 IP。适合仅从已知生产环境调用的 Token。

错误码

状态码	code	含义
401	missing_token	缺少 Authorization 头
401	invalid_token	Token 不存在或格式错
401	revoked_token	Token 已被撤销
401	expired_token	Token 24 小时轮换宽限期已过
403	insufficient_scope	Token 缺少端点所需 scope
403	source_ip_not_allowed	调用方 IP 不在 Token 白名单中

安全最佳实践

• 永不提交 Token 到 git，用密钥管理工具。
• 每个调用方独立 Token，便于精细授权和泄露后撤销。
• 至少每季度轮换一次。
• 监控 控制台 → API 中 Token 的最近使用时间，闲置 Token 及时撤销。