# API 访问令牌
API 访问令牌是分配给您账户中一个或多个项目的唯一标识符。它用于通过 API 对您的账户进行身份验证，以管理您的项目，包括账户修改、发送消息、编辑项目等。
## API 访问令牌类型
Pushwoosh 提供两种不同类型的 API 访问令牌：**服务器 (Server)** 和 **设备 (Device)**。
每种令牌类型仅在其特定的 API 范围内有效。如果使用不正确的令牌，将会发生身份验证错误。
#### 服务器 API 令牌
服务器 API 令牌用于除设备 API 之外的所有 API 方法。它应包含在请求正文的 `auth` 字段中。
#### 设备 API 令牌
设备 API 令牌专用于设备 API 方法。它应使用 `Authorization` 标头包含在 HTTP 请求标头中。
以下是正确标头格式的示例：
```
Authorization: Token
```
将 `` 替换为您的实际设备 API 令牌值。
## 创建和管理 API 访问令牌
您可以在 Pushwoosh 控制面板的 **API Access** 部分查看、创建和管理您的 API 访问令牌。要访问它，请转到 **Settings → API Access**。
您的角色需要同时拥有 **API access** 和 [**Personal data**](/zh/product/account-management-and-security/multi-login-accounts/#available-permissions) 权限，因为令牌可以读取全部受众。
默认情况下，每个账户都包含一个名为 **Pushwoosh Demo App** 的令牌，该令牌被设置为服务器令牌。
### 创建新的 API 访问令牌
要创建新的 API 访问令牌：
1. 转到控制面板中的 **API Access** 部分。
2. 点击 **Generate New Token**。
3. 在出现的窗口中，选择令牌类型：
* [**服务器 (Server)**](#server-api-token) 用于大多数 API 方法（不包括设备 API 方法）。
* [**设备 (Device)**](#device-api-token) 仅用于设备 API 方法。
4. 为令牌输入一个名称。
5. 点击 **Generate** 创建令牌。
> **重要提示：** 请确保为令牌授予对您 Pushwoosh 控制面板中正确应用的访问权限。[了解更多](#edit-token)
新令牌将出现在 API 访问列表中。您可以从那里复制其值以在 API 请求中使用，或根据需要管理其访问权限。
### 管理令牌
要管理现有 API 令牌，请点击 **API Access** 部分中令牌条目旁边的**三点菜单 (⋮)**。
提供以下选项：
#### 授予对所有项目的访问权限
授予令牌对您账户中所有项目的访问权限。这允许它在所有项目中完全使用 API。
#### 撤销对所有项目的访问权限
移除令牌对您账户中所有项目的访问权限。在再次授予访问权限之前，该令牌将无法再使用 API。
#### 编辑令牌
打开 **Edit API Token Permissions** 屏幕，您可以在其中：
* 更改令牌名称
* 复制令牌值
* 通过在列表中选择或取消选择项目来选择令牌可以访问哪些项目
* 打开或关闭令牌的权限：账户修改、应用修改、标签修改、消息发送和删除
* 设置令牌可以使用的[允许的 IP 地址](#restrict-a-token-to-specific-ip-addresses)（仅限服务器令牌）
**Permissions** 选项卡还显示令牌的上次使用时间以及在过去 7 天和 30 天内其调用被拒绝的次数。
完成更改后，点击 **Save** 以应用它们。
#### 检查令牌的使用日志
在“编辑 API 令牌权限”屏幕上打开 **Usage journal** 选项卡，以查看过去 90 天内使用该令牌进行的每次 API 调用。选择一个结果（任何结果、已接受、已完成、已拒绝：IP 地址、已拒绝：无权限）和一个日期范围，然后点击 **Apply** 筛选列表。点击 **Export CSV** 将筛选后的日志下载为 CSV 文件。
#### 删除令牌
从您的账户中永久删除该令牌。
## 授权 API 请求
要授权 API 请求，请根据您调用的 API 方法类型使用正确类型的 API 访问令牌：
#### 对于服务器 API 方法
将令牌包含在请求正文的 "auth" 字段中：
示例：
```json
{
"request": {
"application": "XXXXX-XXXXX",
"auth": "yxoPUlwqm…………pIyEX4H", // 在此处粘贴您的服务器令牌
"notifications": [{
"send_date": "now",
"content": "Hello world"
}]
}
}
```
#### 对于设备 API 方法
使用**设备令牌**。使用以下格式将其包含在 HTTP 请求标头中：
```
Authorization: Token
```
将 `` 替换为您的实际令牌值。
## 将令牌限制到特定的 IP 地址
服务器令牌可以限制为允许的源 IP 地址列表。设置列表后，Pushwoosh 仅接受来自匹配地址的、使用该令牌发出的 API 请求。设备令牌没有此选项。
为服务器令牌打开 [**编辑令牌**](#edit-token)，并在 **Allowed IP addresses** 中输入地址：
* 最多添加 50 个条目，IPv4 或 IPv6，每个条目可以是单个地址 (`203.0.113.7`) 或 CIDR 范围 (`203.0.113.0/24`)。
* 单个地址存储为全长范围，例如 `203.0.113.7` 变为 `203.0.113.7/32`。
* 范围被规范化为其网络地址，例如 `203.0.113.7/24` 变为 `203.0.113.0/24`。
* `0.0.0.0/0` 和 `::/0` 会被拒绝，因为它们会匹配所有地址，无法提供任何限制。
* 将列表留空，以使令牌可以从任何地址使用。这是现有和新令牌的默认设置。
点击 **Save** 应用列表。如果列表包含超过 50 个条目或任何条目不是有效的地址或 CIDR 范围，则保存将被拒绝。
### 当请求来自不允许的地址时会发生什么
Pushwoosh 会在每次使用令牌进行的 API 调用中检查允许的 IP 地址，无论是 v1 REST 调用（如此 API 参考文档中所述，例如 [Messages API](/zh/developer/api-reference/messages-api/)）、[Messaging API v2](/zh/developer/api-reference/messaging-api-v2/) 调用，还是 [Customer Journey API](/zh/developer/api-reference/customer-journey-api/) 调用。来自令牌允许列表之外地址的请求将被拒绝。
响应格式因您进行的调用而异：
* 发送、取消和删除消息，例如 [`createMessage`](/zh/developer/api-reference/messages-api/#createmessage)、特定于渠道的 `create*Message` 方法、[`cancelMessage`](/zh/developer/api-reference/messages-api/#cancelmessage) 和 [`deleteMessage`](/zh/developer/api-reference/messages-api/#deletemessage)，会返回 HTTP 200，响应正文中包含 `"status_code": 403`，与其他授权失败情况相同。
* 其他 v1 REST 调用，例如 Applications、Tags、Geozones、Segmentation (Filters)、Campaigns、Presets、Test devices 和 Statistics API，会返回一个真实的 HTTP 403，并带有一个 JSON 错误正文。
* **Messaging API v2** 和 **Customer Journey API** 会返回 HTTP 403，并带有一个 `PermissionDenied` 错误。