跳转到主要内容
您的 OneSignal 账户包括 App ID 和 Organization ID 等公开 ID，以及 App API key 和 Organization API key 等私有 API 密钥。 在 OneSignal 仪表板的 Settings > Keys & IDs（应用级别）或 Organizations > Your Organization > Keys & IDs（组织级别）下找到这些信息。

​
应用 ID

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

​
组织 ID

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

​
API 密钥

有两种 API 密钥。它们都用于对 REST API 请求进行身份验证，并且都必须妥善保密。请选择与您要执行的操作相匹配的一种：
密钥用途
应用 API 密钥单个特定应用：发送消息、创建用户、读取统计信息。
组织 API 密钥整个组织：创建应用和管理其他 API 密钥。
每个应用最多可创建 16 个应用 API 密钥，每个组织最多可创建 16 个组织 API 密钥。

​
应用 API 密钥

将应用 API 密钥用于针对单个应用的任何 REST API 请求：发送消息；创建或更新用户；或读取消息历史记录。 仪表板从不显示现有 API 密钥的值。密钥 ID 列中的字符串只是内部标识符，不是密钥。要再次获得可用的密钥，请按照下面的步骤创建新的 API 密钥，或轮换现有密钥。轮换会生成新值，同时保留相同的密钥 ID、名称和 IP 允许列表，旧值会立即停止工作。
OneSignal 仪表板中的 API 密钥表，显示密钥 ID 列（不是 API 密钥值）
创建应用 API 密钥 按照以下步骤在仪表板中创建应用 API 密钥，或使用 Create API key API。
1

导航到应用的 Settings > Keys & IDs

在 OneSignal 仪表板中，选择您的应用并转到 Settings > Keys & IDs。
2

点击 Add Key

输入一个描述性名称（例如 Backend service）。可选择添加 IP 允许列表，使密钥只能从批准的服务器使用。
3

点击 Create，然后立即复制密钥值

密钥值以 os_v2_app_ 开头，仅显示一次。请立即将其存储在密钥管理器或后端环境变量中。
创建后显示的生成的 API 密钥
将应用 API 密钥视为密码：
  • 切勿在移动端或 Web 客户端代码中暴露它们。
  • 切勿将它们提交到公共代码仓库（如 GitHub）。
  • 将它们存储在安全的后端或密钥管理器中。

​
组织 API 密钥

将组织 API 密钥用于跨越组织中所有应用的操作。常见的端点： 创建组织 API 密钥： 组织 API 密钥仅可在仪表板中创建。没有用于创建的 API 端点。
1

导航到组织的 Keys & IDs

在 OneSignal 仪表板中，转到 Organizations > Your Organization > Keys & IDs。
2

点击 Add Key 并命名

输入一个描述性名称（例如 App provisioning）。可选择添加 IP 允许列表。
3

点击 Create，然后立即复制密钥值

密钥值以 os_v2_app_ 开头，仅显示一次。请立即将其安全存储。
密钥和 ID 仪表板中的组织 API 密钥部分
组织 API 密钥拥有对组织中每个应用的访问权限。请格外小心对待它们，仅与真正需要组织范围访问权限的服务共享。

​
IP 允许列表

IP 允许列表是可选的，但强烈推荐。它将 API 密钥的使用限制为特定的 IP 地址，从而使泄露的密钥无法从其他地方使用。
  • 输入以空格分隔的 CIDR 块（示例：192.0.2.0/24 192.0.2.123/32）。
  • 来自非允许 IP 的请求将被拒绝。
使用 IP 允许列表的场景：
  • 具有静态 IP 的后端服务。
  • 高安全性的生产环境。
API 密钥创建弹窗中的 IP 允许列表配置字段

​
管理 API 密钥

创建密钥后，您可以在 Settings > Keys & IDs 的密钥列表中编辑、轮换或删除它。应用 API 密钥还支持通过 REST API 执行这些操作。组织 API 密钥仅限仪表板操作。

​
编辑密钥

更新名称或 IP 允许列表，但不更改密钥值。无需更改集成配置。 使用仪表板，或 Update API key API（仅限应用 API 密钥）。

​
轮换密钥

轮换会生成新的密钥，同时保留相同的密钥 ID、名称和 IP 允许列表。旧密钥会立即停止工作。 在以下情况轮换密钥：
  • 密钥被泄露。
  • 有访问权限的团队成员离职。
  • 定期安全轮换到期。
  • 您丢失了原始密钥值，需要可用的密钥。
轮换密钥后，请更新所有使用旧值的服务。使用旧密钥的请求将立即失败。
使用仪表板，或 Rotate API key API（仅限应用 API 密钥）。

​
删除密钥

删除会永久移除密钥，并立即阻止使用该密钥的 API 访问。当密钥不再需要时使用删除操作。 使用仪表板，或 Delete API key API（仅限应用 API 密钥）。

​
从传统 API 密钥迁移

OneSignal 于 2024 年 11 月推出了带有命名、轮换和 IP 允许列表的 App 和 Organization API 密钥。传统的用户身份验证密钥（User Auth key）和原始 REST API 密钥仍然可用，但管理 UI 已被移除，并且无法创建新的传统密钥。
1

创建新密钥

根据您要替换的传统密钥，创建一个新的应用 API 密钥或组织 API 密钥。
2

更新您的代码

在每个针对 OneSignal 进行身份验证的服务中，使用新值替换传统密钥。
3

更新 API 基础 URL

将 API 基础 URL 从 https://onesignal.com/api/v1/ 更改为 https://api.onesignal.com。
4

验证后停用传统密钥

在测试环境中测试 API 请求，然后在 Settings > Keys & IDs 中禁用或删除传统密钥。
在生产环境中禁用传统密钥之前，请先在测试环境中验证 API 请求。

​
阻止 API 访问

要立即吊销密钥，请在 Settings > Keys & IDs 中轮换或删除。使用旧值的请求会立即失败。 要停止消息发送或完全暂停应用，请参阅禁用的应用和组织。

​
安全最佳实践

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

​
常见问题

​
如何找到我的 API 密钥？

API 密钥值以 os_v2_app_ 开头，仅在您创建或轮换密钥后显示一次。仪表板中的密钥 ID 列是内部标识符，不是 API 密钥，如果用于身份验证会返回 401 Unauthorized。如果您未保存密钥值，请轮换密钥以生成新值。完整流程请参阅应用 API 密钥或组织 API 密钥。

​
我可以找回传统应用 API 密钥吗？

不可以。OneSignal 不再显示传统应用 API 密钥。如果您在代码库中找不到该值，请生成新的应用 API 密钥并更新您的集成。

​
应用 ID、应用 API 密钥和组织 API 密钥有什么区别？

  • 应用 ID：应用的公开标识符。用于 SDK 设置和 API 请求中指定应用。
  • 应用 API 密钥：用于为单个应用发送消息和管理用户的密钥。
  • 组织 API 密钥：用于管理整个账户中的应用和组织级别设置的密钥。

​
如果我的 API 密钥泄露了怎么办？

立即轮换密钥。轮换会使旧值失效并发布新值，同时保留相同的密钥 ID、名称和 IP 允许列表。然后更新使用该密钥的每个服务。查看您的审计日志以发现意外的 API 活动。

​
相关页面

REST API 概述

对请求进行身份验证并了解 OneSignal REST API。

速率限制

每个密钥的速率限制以及高容量集成的最佳实践。

审计日志

按密钥、用户和时间查看 API 和仪表板活动。

禁用的应用和组织

暂停或关闭应用并了解计费影响。