# 身份认证

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

## 签发 Token

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

## 使用 Token

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

```bash
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 滚到所有部署。

程序化：

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

响应体返回新 Token。

## 撤销

```bash
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 及时撤销。


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.helodata.com/helodata-zh/api-can-kao/authentication.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.