跳转到主要内容
您的 OneSignal 账户包括公开 ID 和私有 API 密钥。
  • 使用 ID（如应用 ID）来配置 SDK 和引用应用。
  • 使用 API 密钥来验证安全的 REST API 请求。
本指南介绍每个密钥的作用、在哪里找到它以及如何安全地管理它。

​
应用 ID

应用 ID 是一个公开的 UUID (v4)，用于标识您的 OneSignal 应用。 您可以将其用于：
  • 初始化 SDK（移动 SDK 设置、Web SDK 设置）
  • 发起 API 请求，例如创建消息和创建用户
在仪表板的 Settings > Keys & IDs 下或通过 View apps API 找到您的应用 ID。
OneSignal 仪表板密钥和 ID 页面，显示应用 ID 的位置。

您的应用 ID 可以安全地用于客户端 SDK 初始化。它不是密钥。

​
组织 ID

**组织 ID（Org ID）**是一个 UUID (v4)，用于将计费计划下的所有应用分组。 您需要在以下组织级 API 中使用它： 在 Organizations > Your Organization > Keys & IDs 下或通过 View an app API 找到它。
OneSignal 仪表板在密钥和 ID 下显示组织 ID。

​
API 密钥概述

OneSignal 支持两种类型的 API 密钥：
密钥类型作用范围用途
应用 API 密钥单个应用发送消息、创建用户、应用级操作
组织 API 密钥整个组织创建应用、管理 API 密钥、组织级配置
您可以创建最多 16 个 API 密钥并配置 IP 允许列表。
两者都是私有密钥，必须安全存储。

​
应用 API 密钥

使用应用 API 密钥进行与特定应用相关的大多数 REST API 请求。 身份验证格式： 在 Authorization 标头中使用 key 身份验证方案包含密钥： 
Authorization: key YOUR_REST_API_KEY
您可以在 App Settings > Keys & IDs 中或通过 Create API key API 创建应用 API 密钥。
像密码一样对待应用 API 密钥。
  • 切勿在移动端或 Web 客户端代码中暴露它们。
  • 切勿将它们提交到公共代码仓库（如 GitHub）。
  • 将它们存储在安全的后端或密钥管理器中。

​
组织 API 密钥

使用组织 API 密钥进行以下操作： 在 OneSignal 仪表板中导航到 Organizations > Your Organization > Keys & IDs 进行创建。
与应用 API 密钥一样，您可以配置最多 16 个组织密钥并包含 IP 允许列表配置。

​
创建 API 密钥

您可以从仪表板创建应用和组织 API 密钥。
  • 应用 API 密钥也可以通过 Create API key API 创建。
  • 组织 API 密钥只能通过仪表板创建。
创建密钥：
  1. 转到 Keys & IDs（应用或组织级别）。
  2. 点击 Add Key。
OneSignal 仪表板中创建新 API 密钥的弹窗。
  1. 输入一个描述性名称（例如：CRM Sync Service）。 4.（可选）配置 IP 允许列表。
  2. 点击 Create。
  3. 立即复制并安全存储密钥。
API 密钥仅显示一次。如果丢失密钥，您必须轮换它。

​
IP 允许列表（可选但推荐）

您可以将 API 密钥的使用限制为特定的 IP 地址。
  • 输入以空格分隔的 CIDR 块
    • 示例：192.0.2.0/24 192.0.2.123/32
  • 来自非允许 IP 的请求将被拒绝。
使用 IP 允许列表的场景：
  • 具有静态 IP 的后端服务
  • 高安全性的生产环境
API 密钥创建弹窗中的 IP 允许列表配置字段。

​
密钥管理

创建密钥后，您可以通过密钥列表界面管理它：
OneSignal 仪表板中的 API 密钥列表，显示密钥名称和 ID。
密钥 ID 是供参考的标签，不是 API 密钥本身。

​
编辑 API 密钥

您可以：
  • 更新密钥名称
  • 修改 IP 允许列表设置
编辑不会更改密钥值。无需更改集成配置。
  • 应用 API 密钥可以通过仪表板或 Update API key API 更新。
  • 组织 API 密钥只能通过仪表板更新。

​
轮换 API 密钥

轮换密钥：
  • 生成新的密钥
  • 保留相同的名称和配置
  • 立即使旧密钥失效
何时轮换：
  • 密钥被泄露
  • 有访问权限的团队成员离职
  • 定期安全轮换
轮换密钥后，请更新所有使用该密钥的服务。使用旧密钥的请求将会失败。
  • 应用 API 密钥可以通过仪表板或 Rotate API key API 轮换。
  • 组织 API 密钥只能通过仪表板轮换。

​
删除 API 密钥

删除密钥：
  • 永久移除密钥
  • 立即阻止使用该密钥的 API 访问
当密钥不再需要时使用删除操作。
  • 应用 API 密钥可以通过仪表板或 Delete API key API 删除。
  • 组织 API 密钥只能通过仪表板删除。

​
从传统 API 密钥迁移

我们于 2024 年 11 月 14 日推出了丰富的 API 密钥管理功能。 迁移步骤
  1. 创建一个新的应用或组织 API 密钥。
  2. 在您的代码中替换传统密钥。
  3. 将 API 基础 URL 更新为：
https://api.onesignal.com
而不是： 
https://onesignal.com/api/v1/
  1. 在 Keys & IDs 中禁用或删除传统密钥。
在生产环境中禁用传统密钥之前，请先在测试环境中测试 API 请求。

​
禁用您的应用

阻止 API 访问：
  • 删除或轮换 API 密钥以立即阻止 REST API 使用。
禁用消息发送：
  • 转到 Settings > Manage App > Disable App。
有关详细信息，请参阅禁用的应用和组织。
禁用应用不会停止计费。禁用应用的月活跃用户（MAU）仍然计入计费。要停止计费，请删除应用或将其移动到免费组织。如需帮助，请联系 support@onesignal.com。

​
安全最佳实践

  • 将 API 密钥存储在安全的后端（切勿放在客户端）。
  • 使用环境变量或密钥管理器。
  • 尽可能启用 IP 允许列表。
  • 定期轮换密钥。
  • 为测试环境和生产环境使用不同的密钥。