# 认证

每次调用只带一个请求头：Authorization: Bearer 加你的 Key。一个账户最多 50 把 Key，每把有自己的金额上限、到期时间和范围。

## 请求头

凭证放在 `Authorization: Bearer` 里，可以是 API Key，也可以是控制台用的登录凭证。放在地址里或别的请求头里都不收。

```bash
curl "https://api.dataxapi.com/v1/account" \
  -H "Authorization: Bearer $DATAXAPI_API_KEY"
```

Key 放在环境变量 `DATAXAPI_API_KEY` 里：SDK、命令行和 MCP 的配置都从这里读。

## Key

Key 的样子是 `dx_` 加 32 个字符。它只在新建时显示**一次**，之后读不出来：服务只留开头几个字符，用来认是哪一把。丢了就新建一把。一个账户最多 50 把，在控制台的 [Key 页](https://dataxapi.com/zh/console/keys/)新建和管理。

| 每把 Key 有 | 作用 |
| --- | --- |
| 名称 | 给自己认的名字。 |
| 金额上限 | 按日、按月或总额，单位是美元；日和月按 UTC 算。超出上限的调用在执行前就被拒。 |
| 到期时间 | 过了这个时间，这把 Key 的请求回 401。 |
| 范围 | 这把 Key 能调哪些接口的列表；不设就是全部。服务以后新增的接口不在已有的列表里。 |
| 停用、启用 | 关掉，之后还能再打开。 |
| 撤销 | 永久作废，不能恢复。 |

> Key 里不存钱。一个账户的所有 Key 花同一份余额，共用同一个限流额度。

## 查一把 Key 能做什么

`GET /v1/account` 回答的是发请求的这把 Key 的情况，不收费。

- `balance`: 账户现在能花的余额，美元。
- `key.budget`: `daily`、`monthly`、`total` 三项，各有 `limit`（上限）、`spent`（已花）、`remaining`（还剩）。
- `key.scopes`: 这把 Key 能调的接口；`null` 是不限。
- `key.expires_at`: 到期时间；`null` 是不到期。
- `rate`: 这个账户现在的限流额度，见[限流](https://dataxapi.com/zh/docs/rate-limits/)。

SDK 里是 `dx.account()`，命令行里是 `dataxapi balance`。

## 不用 Key 的部分

目录不用 Key：有哪些接口、每个接口收什么参数、返回什么、多少钱，都能直接读。

- `GET /v1/catalog`: 整份目录。
- `GET /v1/catalog/capabilities/{id}`: 一个接口的完整合同，以及它现在可不可用。
- `GET /v1/catalog/search`: 用一句话找接口，中英文都行：`query`、`platform`、`category`。
- `GET /v1/catalog/status`: 现在哪些可用：[状态页](https://dataxapi.com/zh/status/)的数据。

```bash
curl -G "https://api.dataxapi.com/v1/catalog/search" --data-urlencode "query=tiktok video search"
```

## 报错

| 代码 | 状态码 | 什么时候 | 怎么办 |
| --- | --- | --- | --- |
| [`unauthorized`](https://dataxapi.com/zh/docs/errors/#unauthorized) | 401 | 没有带凭证，或凭证无效、已停用、已过期 | 检查请求头，再到 Key 页看这把 Key 的状态。 |
| [`key_scope_denied`](https://dataxapi.com/zh/docs/errors/#key_scope_denied) | 403 | 这把 Key 不能调用这个接口 | 把这个接口加进这把 Key 的范围，或者换一把 Key。 |
| [`key_budget_exceeded`](https://dataxapi.com/zh/docs/errors/#key_budget_exceeded) | 402 | 超出这把 Key 的金额上限 | 调高上限，或者等到下一天、下一个月（`reason` 写明超的是哪一项）。 |

这几种都不扣费。

---

目录修订号 c48ce454ae6c4c65。 [网页版](https://dataxapi.com/zh/docs/authentication/)