> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 密钥和 ID

> 查找和管理您的 OneSignal App ID、Organization ID 和 API 密钥。了解如何创建、轮换、保护和安全迁移密钥。

您的 OneSignal 账户包括 App ID 和 Organization ID 等**公开 ID**，以及 App API key 和 Organization API key 等**私有 API 密钥**。

* [应用 ID](#app-id) 和[组织 ID](#organization-id) 是公开标识符，可以安全地在客户端代码和 SDK 初始化中使用。
* [应用 API 密钥](#app-api-key)和[组织 API 密钥](#organization-api-key)是私有机密。请安全存储，切勿在客户端代码中暴露。

在 OneSignal 仪表板的 **Settings > Keys & IDs**（应用级别）或 **Organizations > Your Organization > Keys & IDs**（组织级别）下找到这些信息。

***

## 应用 ID

**应用 ID** 是一个公开的 UUID (v4)，用于标识您的 OneSignal 应用。

您可以将其用于：

* 初始化 SDK（移动 SDK 设置、Web SDK 设置）
* 发起 API 请求，例如创建消息和创建用户

在仪表板的 **Settings > Keys & IDs** 下或通过 [View apps](/reference/view-apps) API 找到您的应用 ID。

<Frame caption="Settings > Keys & IDs 中的应用 ID 位置">
  <img src="https://mintcdn.com/onesignal/W0DIQbUDatcgdZf6/images/dashboard/dashboard-keys-and-ids-app-id-number.jpg?fit=max&auto=format&n=W0DIQbUDatcgdZf6&q=85&s=07fa6040dbc41ffa7dff116a0b1ad575" alt="在密钥和 ID 设置页面突出显示的应用 ID 值" width="1375" height="528" data-path="images/dashboard/dashboard-keys-and-ids-app-id-number.jpg" />
</Frame>

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

***

## 组织 ID

\*\*组织 ID（Org ID）\*\*是一个 UUID (v4)，用于将计费计划下的所有应用分组。

您需要在以下组织级 API 中使用它：

* [创建应用](/reference/create-an-app)
* [更新应用](/reference/update-an-app)

在 **Organizations > Your Organization > Keys & IDs** 下或通过 [View an app](/reference/view-an-app) API 找到它。

<Frame caption="OneSignal 仪表板中的组织 ID 位置">
  <img src="https://mintcdn.com/onesignal/MWGmj5X1CnFliD-c/images/dashboard/dashboard-keys-and-ids-organization-id.png?fit=max&auto=format&n=MWGmj5X1CnFliD-c&q=85&s=b28d6312569975a67ca3eb1be9f568e4" alt="OneSignal 仪表板在密钥和 ID 下显示组织 ID" width="2560" height="1228" data-path="images/dashboard/dashboard-keys-and-ids-organization-id.png" />
</Frame>

***

## API 密钥

有两种 API 密钥。它们都用于对 REST API 请求进行身份验证，并且都必须妥善保密。请选择与您要执行的操作相匹配的一种：

| 密钥                                 | 用途                       |
| ---------------------------------- | ------------------------ |
| [应用 API 密钥](#app-api-key)          | 单个特定应用：发送消息、创建用户、读取统计信息。 |
| [组织 API 密钥](#organization-api-key) | 整个组织：创建应用和管理其他 API 密钥。   |

<Note>
  每个应用最多可创建 16 个应用 API 密钥，每个组织最多可创建 16 个组织 API 密钥。
</Note>

### 应用 API 密钥

将**应用 API 密钥**用于针对单个应用的任何 REST API 请求：发送消息；创建或更新用户；或读取消息历史记录。

仪表板从不显示现有 API 密钥的值。密钥 ID 列中的字符串只是内部标识符，不是密钥。要再次获得可用的密钥，请按照下面的步骤创建新的 API 密钥，或[轮换现有密钥](#rotate-a-key)。轮换会生成新值，同时保留相同的密钥 ID、名称和 IP 允许列表，旧值会立即停止工作。

<Frame caption="仪表板显示的是密钥 ID，而不是 API 密钥值。实际值（以 os_v2_app_ 开头）仅在创建或轮换密钥时显示一次。">
  <img src="https://mintcdn.com/onesignal/yYUi2EK-maheXJet/images/dashboard/api-key-list.png?fit=max&auto=format&n=yYUi2EK-maheXJet&q=85&s=e6c8dcfa23dc56ec4a2de364ffdffd99" alt="OneSignal 仪表板中的 API 密钥表，显示密钥 ID 列（不是 API 密钥值）" width="2728" height="1104" data-path="images/dashboard/api-key-list.png" />
</Frame>

**创建应用 API 密钥**

按照以下步骤在仪表板中创建应用 API 密钥，或使用 [Create API key](/reference/create-api-key) API。

<Steps>
  <Step title="导航到应用的 Settings > Keys & IDs">
    在 OneSignal 仪表板中，选择您的应用并转到 **Settings > Keys & IDs**。
  </Step>

  <Step title="点击 Add Key">
    输入一个描述性名称（例如 `Backend service`）。可选择添加 [IP 允许列表](#ip-allowlist)，使密钥只能从批准的服务器使用。
  </Step>

  <Step title="点击 Create，然后立即复制密钥值">
    密钥值以 `os_v2_app_` 开头，**仅显示一次**。请立即将其存储在密钥管理器或后端环境变量中。

    <Frame caption="生成的 API 密钥值，仅显示一次">
      <img src="https://mintcdn.com/onesignal/QOf62tdZP66tkOD2/images/docs/generated-api-key.png?fit=max&auto=format&n=QOf62tdZP66tkOD2&q=85&s=81c7a600d8d5f88b79c47a027acc0c41" alt="创建后显示的生成的 API 密钥" width="764" height="768" data-path="images/docs/generated-api-key.png" />
    </Frame>
  </Step>
</Steps>

<Warning>
  将应用 API 密钥视为密码：

  * 切勿在移动端或 Web 客户端代码中暴露它们。
  * 切勿将它们提交到公共代码仓库（如 GitHub）。
  * 将它们存储在安全的后端或密钥管理器中。
</Warning>

### 组织 API 密钥

将**组织 API 密钥**用于跨越组织中所有应用的操作。常见的端点：

* **应用管理：**[创建应用](/reference/create-an-app)、[查看应用](/reference/view-apps)
* **API 密钥管理：**[创建 API 密钥](/reference/create-api-key)、[删除 API 密钥](/reference/delete-api-key)、[轮换 API 密钥](/reference/rotate-api-key)

**创建组织 API 密钥：**

组织 API 密钥仅可在仪表板中创建。没有用于创建的 API 端点。

<Steps>
  <Step title="导航到组织的 Keys & IDs">
    在 OneSignal 仪表板中，转到 **Organizations > Your Organization > Keys & IDs**。
  </Step>

  <Step title="点击 Add Key 并命名">
    输入一个描述性名称（例如 `App provisioning`）。可选择添加 [IP 允许列表](#ip-allowlist)。
  </Step>

  <Step title="点击 Create，然后立即复制密钥值">
    密钥值以 `os_v2_app_` 开头，**仅显示一次**。请立即将其安全存储。
  </Step>
</Steps>

<Frame caption="可创建组织 API 密钥的组织 Keys & IDs 页面">
  <img src="https://mintcdn.com/onesignal/W0DIQbUDatcgdZf6/images/dashboard/default-org-api-keys-and-ids.jpg?fit=max&auto=format&n=W0DIQbUDatcgdZf6&q=85&s=d014d99705d175a153d43444b42adca3" alt="密钥和 ID 仪表板中的组织 API 密钥部分" width="1846" height="840" data-path="images/dashboard/default-org-api-keys-and-ids.jpg" />
</Frame>

<Warning>
  组织 API 密钥拥有对组织中每个应用的访问权限。请格外小心对待它们，仅与真正需要组织范围访问权限的服务共享。
</Warning>

***

## IP 允许列表

IP 允许列表是可选的，但强烈推荐。它将 API 密钥的使用限制为特定的 IP 地址，从而使泄露的密钥无法从其他地方使用。

* 输入以空格分隔的 CIDR 块（示例：`192.0.2.0/24 192.0.2.123/32`）。
* 来自非允许 IP 的请求将被拒绝。

使用 IP 允许列表的场景：

* 具有静态 IP 的后端服务。
* 高安全性的生产环境。

<Frame caption="创建启用了 IP 允许列表的 API 密钥">
  <img src="https://mintcdn.com/onesignal/QOf62tdZP66tkOD2/images/docs/ip-allowlist-config.png?fit=max&auto=format&n=QOf62tdZP66tkOD2&q=85&s=d2bdf5bec27c8a982c027d428687a3b9" alt="API 密钥创建弹窗中的 IP 允许列表配置字段" width="764" height="542" data-path="images/docs/ip-allowlist-config.png" />
</Frame>

***

## 管理 API 密钥

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

### 编辑密钥

更新名称或 IP 允许列表，但不更改密钥值。无需更改集成配置。

使用仪表板，或 [Update API key](/reference/update-api-key) API（仅限应用 API 密钥）。

### 轮换密钥

轮换会生成新的密钥，同时保留相同的密钥 ID、名称和 IP 允许列表。旧密钥会立即停止工作。

在以下情况轮换密钥：

* 密钥被泄露。
* 有访问权限的团队成员离职。
* 定期安全轮换到期。
* 您丢失了原始密钥值，需要可用的密钥。

<Warning>
  轮换密钥后，请更新所有使用旧值的服务。使用旧密钥的请求将立即失败。
</Warning>

使用仪表板，或 [Rotate API key](/reference/rotate-api-key) API（仅限应用 API 密钥）。

### 删除密钥

删除会永久移除密钥，并立即阻止使用该密钥的 API 访问。当密钥不再需要时使用删除操作。

使用仪表板，或 [Delete API key](/reference/delete-api-key) API（仅限应用 API 密钥）。

***

## 从传统 API 密钥迁移

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

<Steps>
  <Step title="创建新密钥">
    根据您要替换的传统密钥，创建一个新的[应用 API 密钥](#app-api-key)或[组织 API 密钥](#organization-api-key)。
  </Step>

  <Step title="更新您的代码">
    在每个针对 OneSignal 进行身份验证的服务中，使用新值替换传统密钥。
  </Step>

  <Step title="更新 API 基础 URL">
    将 API 基础 URL 从 `https://onesignal.com/api/v1/` 更改为 `https://api.onesignal.com`。
  </Step>

  <Step title="验证后停用传统密钥">
    在测试环境中测试 API 请求，然后在 **Settings > Keys & IDs** 中禁用或删除传统密钥。
  </Step>
</Steps>

<Check>
  在生产环境中禁用传统密钥之前，请先在测试环境中验证 API 请求。
</Check>

***

## 阻止 API 访问

要立即吊销密钥，请在 **Settings > Keys & IDs** 中[轮换](#rotate-a-key)或[删除](#delete-a-key)。使用旧值的请求会立即失败。

要停止消息发送或完全暂停应用，请参阅[禁用的应用和组织](./disabled-apps)。

***

## 安全最佳实践

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

***

## 常见问题

### 如何找到我的 API 密钥？

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

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

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

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

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

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

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

***

## 相关页面

<Columns cols={2}>
  <Card title="REST API 概述" icon="code" href="/reference/rest-api-overview">
    对请求进行身份验证并了解 OneSignal REST API。
  </Card>

  <Card title="速率限制" icon="clock" href="/reference/rate-limits">
    每个密钥的速率限制以及高容量集成的最佳实践。
  </Card>

  <Card title="审计日志" icon="file-shield" href="./audit-logs">
    按密钥、用户和时间查看 API 和仪表板活动。
  </Card>

  <Card title="禁用的应用和组织" icon="ban" href="./disabled-apps">
    暂停或关闭应用并了解计费影响。
  </Card>
</Columns>