API 访问令牌

API 访问令牌是分配给您账户中一个或多个项目的唯一标识符。它用于通过 API 对您的账户进行身份验证，以管理您的项目，包括账户修改、发送消息、编辑项目等。

API 访问令牌类型

Pushwoosh 提供两种不同类型的 API 访问令牌：服务器 (Server) 和 设备 (Device)。

每种令牌类型仅在其特定的 API 范围内有效。如果使用不正确的令牌，将会发生身份验证错误。

服务器 API 令牌

服务器 API 令牌用于除设备 API 之外的所有 API 方法。它应包含在请求正文的 auth 字段中。

设备 API 令牌

设备 API 令牌专用于设备 API 方法。它应使用 Authorization 标头包含在 HTTP 请求标头中。以下是正确标头格式的示例：

Authorization: Token <device_api_token>

将 <device_api_token> 替换为您的实际设备 API 令牌值。

创建和管理 API 访问令牌

您可以在 Pushwoosh 控制面板的 API Access 部分查看、创建和管理您的 API 访问令牌。要访问它，请转到 Settings → API Access。 Pushwoosh Demo App token

默认情况下，每个账户都包含一个名为 Pushwoosh Demo App 的令牌，该令牌被设置为服务器令牌。

创建新的 API 访问令牌

要创建新的 API 访问令牌：

转到控制面板中的 API Access 部分。
点击 Generate New Token。
在出现的窗口中，选择令牌类型：
- 服务器 (Server) 用于大多数 API 方法（不包括设备 API 方法）。
- 设备 (Device) 仅用于设备 API 方法。
为令牌输入一个名称。
点击 Generate 创建令牌。

Generate a New Token

重要提示： 请确保为令牌授予对您 Pushwoosh 控制面板中正确应用的访问权限。了解更多

新令牌将出现在 API 访问列表中。您可以从那里复制其值以在 API 请求中使用，或根据需要管理其访问权限。

管理令牌

要管理现有 API 令牌，请点击 API Access 部分中令牌条目旁边的三点菜单 (⋮)。

Manage a token

提供以下选项：

授予对所有项目的访问权限

授予令牌对您账户中所有项目的访问权限。这允许它在所有项目中完全使用 API。

撤销对所有项目的访问权限

移除令牌对您账户中所有项目的访问权限。在再次授予访问权限之前，该令牌将无法再使用 API。

编辑令牌

打开 Edit API Token Permissions 屏幕，您可以在其中：

更改令牌名称
复制令牌值
通过在列表中选择或取消选择项目来选择令牌可以访问哪些项目
打开或关闭令牌的权限：账户修改、应用修改、标签修改、消息发送和删除
设置令牌可以使用的允许的 IP 地址（仅限服务器令牌）

Permissions 选项卡还显示令牌的上次使用时间以及在过去 7 天和 30 天内其调用被拒绝的次数。

编辑令牌屏幕，包含权限和使用日志选项卡、使用摘要和允许的 IP 地址字段

完成更改后，点击 Save 以应用它们。

检查令牌的使用日志

在“编辑 API 令牌权限”屏幕上打开 Usage journal 选项卡，以查看过去 90 天内使用该令牌进行的每次 API 调用。选择一个结果（任何结果、已接受、已完成、已拒绝：IP 地址、已拒绝：无权限）和一个日期范围，然后点击 Apply 筛选列表。点击 Export CSV 将筛选后的日志下载为 CSV 文件。

使用日志选项卡，包含结果和日期过滤器以及 CSV 导出按钮

删除令牌

从您的账户中永久删除该令牌。

授权 API 请求

要授权 API 请求，请根据您调用的 API 方法类型使用正确类型的 API 访问令牌：

对于服务器 API 方法

将令牌包含在请求正文的 “auth” 字段中：

示例：

{
  "request": {
    "application": "XXXXX-XXXXX",
    "auth": "yxoPUlwqm…………pIyEX4H", // 在此处粘贴您的服务器令牌
    "notifications": [{
      "send_date": "now",
      "content": "Hello world"
    }]
  }
}

对于设备 API 方法

使用设备令牌。使用以下格式将其包含在 HTTP 请求标头中：

Authorization: Token <device_api_token>

将 <device_api_token> 替换为您的实际令牌值。

将令牌限制到特定的 IP 地址

服务器令牌可以限制为允许的源 IP 地址列表。设置列表后，Pushwoosh 仅接受来自匹配地址的、使用该令牌发出的 API 请求。设备令牌没有此选项。

为服务器令牌打开 编辑令牌，并在 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）、Messaging API v2 调用，还是 Customer Journey API 调用。来自令牌允许列表之外地址的请求将被拒绝。

响应格式因您进行的调用而异：

发送、取消和删除消息，例如 createMessage、特定于渠道的 create*Message 方法、cancelMessage 和 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 错误。