# API 密钥

用 API 密钥验证 API 请求。

Stripe 使用您账户的 API 密钥对 API 请求进行身份验证。如果请求未包含有效密钥，Stripe 将返回[无效请求错误](https://docs.stripe.com/error-handling.md#invalid-request-errors)。如果请求包含已删除或已过期的密钥，Stripe 将返回[身份验证错误](https://docs.stripe.com/error-handling.md#authentication-errors)。

您可以通过[开发人员管理平台](https://dashboard.stripe.com/test/apikeys)创建、显示、删除和轮换 API 密钥。在[ API 密钥](https://dashboard.stripe.com/test/apikeys)标签页中可以访问您的 API 密钥。

> #### 如果您是 Stripe 的新用户
> 
> - \**保障您的业务安全：**阅读我们的[密钥管理最佳实践](https://docs.stripe.com/keys-best-practices.md)。
- **构建和测试**：使用您的_沙盒（测试模式）密钥_。沙盒密钥开头为 `pk_test_`（可发布）、`rk_test_`（受限）和 `sk_test_`（秘密）。它们允许您在不影响真实数据的情况下进行测试。
- **当您准备好接受真实付款时**：切换到您的**真实模式密钥**，开头为 `pk_live_`、`rk_live_` 和 `sk_live_`。请参见[切换到真实模式](https://docs.stripe.com/keys.md#switch-to-live-mode)获取说明。
- **如果您需要查找 Webhook 签名密钥**：Webhook 密钥与 API 密钥是分开的。您可以在管理平台的 [Webhooks](https://dashboard.stripe.com/webhooks) 部分中的每个 Webhook 端点下找到它们。

## 密钥类型

当您注册 Stripe 账户时，我们会为您创建三种类型的 API 密钥：

| 类型                      | 安全公开 | 说明                                                                                                                                                                                           |
| ----------------------- | ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 受限 API 密钥 (RAK)`rk_...` | 否    | 您可以控制权限的 API 密钥。即使恶意方获取了您的密钥，也能将对业务的潜在损害降到最低。您可以创建任意数量的 RAK，并将它们分配给应用程序的不同部分。[本指南](https://docs.stripe.com/keys/restricted-api-keys.md)介绍了如何配置和使用 RAK。                                       |
| 可发布 API 密钥              | 是    | 可放在前端代码或您发布的应用程序中的 API 密钥。                                                                                                                                                                   |
| 秘密 API 密钥`sk_...`       | 否    | 在所有 Stripe API 上拥有不受限制权限的 API 密钥。由于无法限制其权限，我们不建议在新的应用场景中使用秘密密钥；对于现有集成，我们建议将秘密密钥的使用迁移到 RAK。                                                                                                   |
| 组织 API 密钥 `sk_org_...`  | 否    | 组织级 API 密钥。与账户级受限密钥或秘密密钥相同，但在[组织](https://docs.stripe.com/get-started/account/orgs.md)级别运行，可同时管理多个 Stripe 账户。[本指南](https://docs.stripe.com/keys/organization-api-keys.md)介绍如何配置和使用组织 API 密钥。 |

我们还支持由特定托管平台签发的[托管 API 密钥](https://docs.stripe.com/keys/managed-api-keys.md)。托管密钥是由托管平台直接交付给您的托管应用的秘密 API 密钥。您无需直接处理托管密钥，由托管提供商为您签发和轮换。

> #### Webhook 签名密钥
> 
> Webhook 签名密钥不是 API 密钥——它们是每个 Webhook 独有的密钥，供您的 Webhook 接收器用于身份验证 Webhook 确实来自 Stripe。您可以在管理平台的 [Webhooks](https://dashboard.stripe.com/webhooks) 部分找到每个 Webhook 端点的签名密钥。

如果您在 2026 年 5 月之前创建了 Stripe 账户，您可能没有任何受限 API 密钥。我们建议您创建 RAK 并从秘密密钥迁移。

您有责任安全管理您的 API 密钥。请阅读我们的[保护 API 密钥的最佳实践](https://docs.stripe.com/keys-best-practices.md)指南。

### 沙盒与真实模式

所有 Stripe API 请求均在*沙盒* (A sandbox is an isolated test environment that allows you to test Stripe functionality in your account without affecting your live integration. Use sandboxes to safely experiment with new features and changes)或*真实模式* (Use this mode when you’re ready to launch your app. Card networks or payment providers process payments)下进行。您可以在沙盒中测试您的集成并访问测试数据，在真实模式中访问真实的账户数据。两种模式各有一套独立的 API 密钥，且不同模式下的对象无法互通访问。例如，沙盒中的[产品对象](https://docs.stripe.com/api/products/object.md)无法用于真实模式下的支付。

| 类型   | 何时使用                                                            | 对象                                                                                                                         | 如何使用                                                                       | 考虑                                                                                                                                                   |
| ---- | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| 沙盒   | 使用沙盒及其关联的测试 API 密钥，和构建集成时一样。在沙盒中，卡组织和支付处理商不处理付款。                | API 调用返回的是模拟的对象。例如，您可以检索并使用测试用的 `account`、`payment`、`customer`、`charge`、`refund`、`transfer`、`balance` 和 `subscription` 对象。 | 使用[测试信用卡和账户](https://docs.stripe.com/testing.md#cards)。您不能接受真实支付方式或使用真实账户。 | [Identity](https://docs.stripe.com/identity.md) 不执行任何验证检查。此外，Connect [account objects](https://docs.stripe.com/api/accounts/object.md) 不返回敏感字段。      |
| 真实模式 | 当您准备好启动您的集成并真正收款时，使用真实模式及其关联的真实 API 密钥。在真实模式下，卡组织和支付处理商确实会处理付款。 | API 调用返回的是真实对象。例如，您可以检索并使用真实的 `account`、`payment`、`customer`、`charge`、`refund`、`transfer`、`balance` 和 `subscription` 对象。   | 接受真实信用卡，可使用客户账户。您可以为信用卡和账户接受实际付款授权、收款并捕获。                                  | 争议流程也更加细致，但[测试流程](https://docs.stripe.com/testing.md#disputes)较为简单。此外，有些[支付方式](https://docs.stripe.com/payments/payment-methods.md)的支付流程更加细致，要求更多步骤。 |

## 密钥安全防护

只有可发布密钥可以安全地暴露在您的应用程序后端之外。您有责任保护其他 Stripe API 密钥，包括受限 API 密钥。以下是保护密钥的一些方法：

- 将敏感密钥存储在您的托管平台提供的密钥保管库中。[这篇博文](https://stripe.dev/blog/securing-stripe-api-keys-aws-automatic-rotation)提供了一个示例。如果您无法使用密钥保管库，请使用环境变量向后端应用程序提供密钥。
- 请勿将密钥放在源代码或已纳入版本控制的配置文件中。

- [将密钥限制为特定 IP 地址](https://docs.stripe.com/keys.md#limit-api-secret-keys-ip-address)，以便只有您的服务器才能使用这些密钥。

- 当可访问密钥的团队成员离开您的组织时，请[定期轮换密钥](https://docs.stripe.com/keys.md#rolling-keys)。
- 请勿通过电子邮件、聊天或其他未加密渠道共享密钥。

如需全面指南，请参阅[秘密 API 密钥管理最佳实践](https://docs.stripe.com/keys-best-practices.md)。我们还维护了[一套技能库](https://github.com/stripe/ai/tree/main/skills)，以帮助 AI 智能体遵循这些最佳实践。

## 管理您的 API 密钥

使用[管理平台](https://dashboard.stripe.com/apikeys)创建、显示、修改、删除和轮换您的 API 密钥。

#### 创建受限 API 密钥

在大多数应用场景下使用[受限 API 密钥](https://docs.stripe.com/keys/restricted-api-keys.md) (RAK)。使用 RAK，您可以精确分配集成所需的权限，从而降低恶意方在获取您的密钥后可能对您的业务造成的损害。

- 请按照[受限 API 密钥](https://docs.stripe.com/keys/restricted-api-keys.md) 的说明创建 RAK、配置其权限，并从秘密密钥迁移。

#### 创建 API 私钥

仅当您的集成需要不受限制地访问所有 Stripe API 和资源时，才创建非受限的秘密 API 密钥。如果恶意方获取了您的秘密密钥，可能会对您的业务造成损害。我们建议使用 RAK 来替代。

1. 在 [API 密钥](https://dashboard.stripe.com/test/apikeys)标签页中，点击**创建密钥**。
1. 在弹出的对话框中，输入我们通过邮件或短信发送给您的验证码。如果对话框未自动跳转，可点击**继续**。
1. 在**密钥名称**字段中输入名称，然后点击**创建**。
1. 点击密钥内容即可复制该密钥。
1. 保存密钥的值。以后无法再检索到它。
1. 在**添加备注**字段中输入您保存该密钥的位置，然后点击**完成**。

### 显示 API 密钥

在真实模式下创建秘密密钥时，我们会在您保存之前显示一次该密钥。请在保存前复制密钥，因为之后无法再显示。

在真实模式下，您只能显示我们为您创建的 API 密钥，例如默认秘密密钥或计划轮换生成的秘密密钥。在沙盒模式下，您可以随时查看所有 API 密钥，包括受限密钥和秘密密钥。

> 将敏感密钥存储在不会丢失的地方，例如平台提供的密钥保管库。请勿将密钥放入应用程序代码中。

可发布 API 密钥不属于敏感信息，因此我们默认显示它们，您无需执行任何操作即可显示。

我们无法找回您遗忘或失去访问权限的密钥。如果丢失密钥，请轮换或删除，然后创建新的密钥。

#### 在真实模式下显示 RAK

您只能显示我们为您创建的真实模式 RAK。如果您自己创建了 RAK，则在显示一次后将无法再次查看。

1. 在真实模式下的 [API 密钥](https://dashboard.stripe.com/apikeys) 选项卡上，在**受限密钥**列表中，点击您想显示的密钥的**显示真实密钥**选项。
1. 点击密钥内容即可复制该密钥。
1. 将密钥值保存在您平台的[密钥保管库](https://docs.stripe.com/keys-best-practices.md#use-a-secrets-vault)中。如果您的平台不提供密钥保管库，则使用环境变量。
1. 点击**隐藏真实密钥**。

#### 在真实模式下显示秘密 API 密钥

您只能显示我们为您创建的真实模式秘密密钥。如果您自己创建了秘密密钥，则在显示一次后将无法再次显示。

1. 在真实模式下的 [API 密钥](https://dashboard.stripe.com/apikeys) 选项卡上，在**标准密钥**列表中，点击您想显示的密钥的**显示真实密钥**选项。
1. 点击密钥内容即可复制该密钥。
1. 将密钥值保存在您平台的[密钥保管库](https://docs.stripe.com/keys-best-practices.md#use-a-secrets-vault)中。如果您的平台不提供密钥保管库，则使用环境变量。
1. 点击**隐藏真实密钥**。
1. 点击目标密钥对应的溢出菜单 (⋯)，然后选择**编辑密钥**，为该密钥添加备注。
1. 在**备注**字段中输入您保存该密钥的位置，然后点击**保存**。

### 限制 API 密钥的访问 IP 地址

您可以将密钥或受限 API 密钥限制在一个 IP 地址范围内，或限制在一个或多个特定 IP 地址上。Stripe 建议对所有真实模式密钥启用 IP 限制，以防止从未经授权的位置使用。在适用情况下（例如，为了区分暂存环境和生产环境），请对不同的密钥使用不同的 IP 允许列表。

所填 IP 地址必须采用 IPv4 协议，且您可以指定任意有效的 CIDR 地址段。例如，您可以将 `100.10.38.0 - 100.10.38.255` 这个地址段表示为 `100.10.38.0/24`，该地址段内的所有 IP 地址均以 `100.10.38` 开头。

1. 在 [API 密钥](https://dashboard.stripe.com/test/apikeys)标签页的**受限密钥**或**标准密钥**列表中，点击您想要显示的密钥对应的溢出菜单 (⋯)。

1. 选择**管理 IP 限制** > **限制仅允许指定 IP 地址访问**。

1. 请执行以下任一操作：

   - 在**IP地址**字段中输入一个或多个单独的 IP 地址。
   - 如需添加 IP 地址段，请在 **IP 地址**字段中输入该地址段的起始地址（采用无类别域间路由 (CIDR) 表示法），并在 **CIDR** 字段中输入网络前缀长度。

1. 如需添加其他 IP 地址或 IP 地址段，点击 **+ 添加**。

1. 点击**保存**。

### 修改 API 密钥的名称或备注

1. 在 [API 密钥](https://dashboard.stripe.com/test/apikeys)标签页中，点击您想要修改的密钥对应的溢出菜单（⋯）。
1. 选择**编辑密钥**。
1. 请执行以下操作：
   - 如需修改密钥名称，可在**密钥名称**字段中输入新的名称。
   - 如需修改备注内容，可在**备注**字段中输入新的备注文本。
1. 点击**保存**。

### 使 API 密钥失效

如果您使 API 密钥或受限 API 密钥失效，则必须新建一个密钥并更新使用该失效密钥的代码。任何使用失效密钥的代码，都无法再进行 API 调用。

> 您无法使可发布密钥失效。

1. 在 [API 密钥](https://dashboard.stripe.com/test/apikeys)标签页的**受限密钥**或**标准密钥**列表中，点击您希望使其失效的密钥的溢出菜单（⋯）。
1. 选择**使密钥失效**。
1. 在对话框中，点击**使密钥失效**。如果您不希望使密钥失效，请点击**取消**。

### 轮换 API 密钥

轮换 API 密钥会吊销原密钥，并生成一个可立即使用的新密钥。您也可以为 API 密钥设置定时轮换计划。替换后的密钥命名规则如下：

- 替换后的可发布密钥名称固定为`可发布密钥`。
- 替换后的密钥名称始终为`密钥`。
- 替换后的受限密钥名称与被轮换的密钥名称相同。

您可以通过编辑操作，修改 API 密钥或受限 API 密钥的名称。

以下情境需要执行 API 密钥轮换操作：

- 如果您在真实模式下遗失了 API 密钥或受限 API 密钥，且无法从管理平台中找回。
- 如果 API 密钥或受限 API 密钥遭到泄露，您需要吊销该密钥以阻止所有可能利用此密钥发起的恶意 API 请求。
- 如果拥有密钥访问权限的团队成员离职或岗位变动时。
- 如果您的政策要求按特定间隔轮换密钥。

#### 轮换 API 密钥

1. 在 [API 密钥](https://dashboard.stripe.com/test/apikeys)标签页中，点击您想要轮换的密钥对应的溢出菜单（⋯）。
1. 选择**轮换密钥**。
1. 从**有效期**下拉菜单中选择一个有效期。如果选择**立即**，旧密钥将被删除；如果指定具体时间，密钥名称下方会显示该密钥的剩余有效时长。
1. 点击**轮换 API 密钥**。
1. 点击密钥内容即可复制该密钥。
1. 保存密钥的值。以后无法再检索到它。
1. 在**添加备注**字段中输入您保存该密钥的位置，然后点击**保存**或**完成**。

### 恢复 API 密钥的访问权限

如果 API 密钥超过 180 天未被用于创建转账、提现或更新提现目的地，其访问权限可能会受到限制。您将无法使用受限访问密钥来创建提现和转账，或创建提现目的地。您可以恢复访问权限，以便正常使用该密钥或执行被阻止的操作。

#### 如需恢复 API 密钥的访问权限

1. 在 [API 密钥](https://dashboard.stripe.com/test/apikeys)标签页中，点击您想要恢复的密钥对应的溢出菜单（⋯）。
1. 选择**恢复访问权限**。
1. 点击**恢复**。

## 查看某个密钥的 API 请求日志

如需[打开 API 请求日志](https://docs.stripe.com/development/dashboard/request-logs.md)，请点击任意密钥对应的溢出菜单 (⋯)，然后选择**查看请求日志**。打开日志后，系统会将您重定向至 Stripe 管理平台。

## 切换到真实模式

当您准备好接受真实付款时，请使用生产模式 API 密钥，而非沙盒（测试）密钥。在 [API 密钥](https://dashboard.stripe.com/apikeys)页面上，将开关从**沙盒模式**切换到**真实模式**。此时页面将显示您的真实模式 API 密钥。

> #### 完整的上线检查清单
> 
> 切换 API 密钥只有一步。请审核完整的[上线检查清单](https://docs.stripe.com/get-started/checklist/go-live.md)，以确保您的集成已准备好投入生产。

### 可发布密钥（客户端）

复制您的**真实模式可发布密钥**（以 `pk_live_` 为开头），并替换您客户端代码中的 `pk_test_` 密钥。将此密钥嵌入代码或应用程序中是安全的。

### 受限或秘密 API 密钥（服务器端）

服务端 API 密钥属于敏感信息，请阅读我们的[秘密 API 密钥管理最佳实践](https://docs.stripe.com/keys-best-practices.md)。我们建议您为服务端代码生成[受限 API 密钥](https://docs.stripe.com/keys/restricted-api-keys.md)，以便在密钥意外泄露或遭到入侵时，将业务损失降至最低。

1. 开始在后端应用中使用真实模式密钥之前，请先从代码中移除所有硬编码的 API 密钥，改为使用[密钥保管库](https://docs.stripe.com/keys-best-practices.md#use-a-secrets-vault)来提供沙盒密钥，并确认您的应用依然能正常运行。如果您的平台不提供密钥保管库，您可以使用环境变量。
1. [显示](https://docs.stripe.com/keys.md#reveal-an-api-key)并复制您的**真实模式密钥**（以 `rk_live_` 或 `sk_live_` 开头），并将其安全存储在您的服务器环境中。
1. 配置您的服务器环境，让其为您的应用程序提供真实模式密钥，而不是沙盒密钥。

#### Webhook 签名密钥（服务器端）

如果您使用 Webhook，请更新每个 Webhook 端点的 URL，并从管理平台的 [Webhook](https://dashboard.stripe.com/webhooks) 部分复制新的**签名私钥**。

## See also

- [管理秘密 API 密钥的最佳实践](https://docs.stripe.com/keys-best-practices.md)
- [防范 API 密钥泄露](https://support.stripe.com/questions/protecting-against-compromised-api-keys)
- [为什么我的 API 密钥访问受限？](https://support.stripe.com/questions/why-does-my-api-key-have-limited-access)