API 密钥

Stripe 会利用您账户的 API 密钥验证您的 API 请求。如果某个请求不包含有效密钥，Stripe 将返回无效请求错误。如果请求中包含已删除或过期的密钥，则 Stripe 将返回身份验证错误。

用开发人员管理平台创建、显示、删除和轮换 API 密钥。要访问 v1 API 密钥，请选择管理平台上的 API 密钥选项卡。

密钥类型

默认情况下，所有账户总共有四个 API 密钥，两个在沙盒中，两个在真实模式中：

• 沙盒私钥：在沙盒中测试时，使用此密钥对服务器上的请求进行身份验证。默认情况下，您可以不受任何限制地使用此密钥执行任何 API 请求。为测试和开发保留此密钥，确保您不会意外修改您的真实客户或收款。
• 沙盒公钥：在您的网页或移动应用程序的客户端代码中用这个密钥进行测试。为测试和开发保留此密钥，确保您不会意外修改您的真实客户或收款。
• 真实模式下的私钥：在真实模式下，使用此密钥对服务器上的请求进行身份验证。默认情况下，您可以不受任何限制地使用此密钥执行任何 API 请求。
• 真实模式下的公钥：在准备启动您的应用程序时，在您的网页或移动应用程序的客户端代码中使用此密钥。

您的私钥和公钥位于管理平台的 API 密钥选项卡中。如果您无法查看您的 API 密钥，请让您的 Stripe 账户以适当权限将您添加到他们的团队。

当您登录到 Stripe 后，我们的文档会自动用您的测试 API 密钥填充代码示例。只有您可以看到这些值。如果您没有登录，我们的代码示例中会包含随机生成的 API 密钥。您可以用自己的测试密钥替换它们，或者登录查看用您自己的测试 API 密钥填充的示例代码。

下表显示了随机生成的 API 私钥和公钥的示例：

沙盒与真实模式

所有 Stripe API 请求都发生在沙盒环境或真实模式下。使用沙盒访问测试数据，在真实模式下访问实际账户数据。每种模式都有自己的一组 API 私钥。一种模式下的对象无法被另一种模式访问。例如，沙盒产品对象不能是真实模式付款的一部分。

轮换 API 密钥

轮换密钥会将其撤销，并生成一个替换密钥。您可以立即轮换密钥，也可以计划在特定时间后轮换密钥。在以下示例等场景中轮换密钥：

• 如果您是在真实模式，则丢失 API 私钥或限制性密钥的话，不能从管理平台恢复它，必须更换。
• 如果一个私钥或受限密钥被泄露，您需要撤销它来阻止任何可能使用它的潜在的恶意 API 请求。
• 您的策略要求在一定的时间间隔内轮换密钥。

要轮换 API 密钥，请执行以下作：

1. 打开 API 密钥页面。
2. 在要轮换的密钥所在的行中，点击溢出菜单()，然后选择轮换密钥。
3. 从到期日期下拉列表中选择到期日期。
4. 点击轮换 API 密钥。
5. 该对话框显示新的密钥值。点击它进行复制。
6. 保存密钥的值。以后无法再检索到它。
7. 在添加注释字段中，输入保存密钥的位置，然后点击完成或保存。

如果到期日期选择的是现在，则我们删除旧密钥。如果您选择的是其他时间，则可以在其名称下方看到它距离到期的时间。

不论旧密钥的到期时间如何，新密钥都可以立即使用。

当您轮换公钥时，替换密钥的名称始终是 Publishable key。当您轮换私钥时，替换密钥的名称始终是 Secret key。当您轮换受限密钥时，替换密钥的名称与轮换密钥的名称相同。您可以通过点击其溢出菜单并选择编辑密钥，来重命名私钥或受限密钥。

查看 API 请求日志

要打开 API 请求日志，点击任意密钥的溢出菜单()，然后选择查看请求日志。打开日志会使您返回到 Stripe 主管理平台。

私钥和受限密钥

使用管理平台创建、删除、显示和修改私钥和受限密钥。

创建 API 私钥

创建 API 私钥：

1. 打开 API 密钥页面。
2. 点击创建私钥。
3. Stripe 会以电子邮件或短信的方式给您发送一个验证码。（和任何电子邮件或短信一样，它可能不会立即到达。）在对话框中输入验证码。如果对话没有自动继续，请点击继续。
4. 在密钥名称字段输入一个名称。
5. 点击创建。
6. 该对话框显示新的密钥值。点击它进行复制。
7. 保存密钥的值。以后无法再检索到它。
8. 在添加注释字段中，输入保存密钥的位置，然后点击完成。

创建受限 API 密钥

受限 API 密钥只允许您指定的最低访问的级别。

创建受限的 API 密钥：

1. 打开 API 密钥页面。
2. 您可以从头开始创建受限密钥，也可以从克隆现有的受限密钥开始。
   • 要从头开始创建受限密钥，请点击创建受限密钥。在这种情况下，所有权限的默认值是无。
   • 要克隆现有密钥，点击溢出菜单()，然后在要克隆的密钥的行中选择复制密钥。在这种情况下，每个权限的默认值是它在克隆密钥中的值。
3. 在密钥名称字段中，输入名称。如果克隆了现有密钥，则默认名称是所克隆密钥的名称。
4. 对于希望新密钥访问的每个资源，选择要允许该密钥使用的权限。如果您使用 Connect，您还可以选择在访问 Connect 子账户时允许此密钥的权限。可用的权限有无、读、或写。
5. 点击创建密钥。
6. Stripe 会以电子邮件或短信的方式给您发送一个验证码。（和任何电子邮件或短信一样，它可能不会立即到达。）在对话框中输入验证码。如果对话没有自动继续，请点击继续。
7. 该对话框显示新的密钥值。点击它进行复制。
8. 保存密钥的值。以后无法再检索到它。
9. 在添加注释字段中，输入保存密钥的位置，然后点击完成。

删除私钥或受限 API 密钥

删除某个密钥后，任何使用该密钥的代码都不能再进行 API 调用。删除密钥后，创建一个新密钥并更新代码来使用它。

要删除密钥，请执行以下操作：

1. 在开发人员管理平台上，选择 API 密钥选项卡。
2. 在标准密钥或受限密钥列表中找到要删除的密钥。点击这个密钥所在行的溢出菜单()，然后选择删除密钥。
3. 如果确定要删除密钥，请点击删除 API 密钥对话框中的删除密钥。否则，点击取消。

在沙盒环境中显示 API 私钥

在沙盒环境中，您可以任意多次显示一个 API 私钥。

要在沙盒中显示私钥，请执行以下作：

1. 在开发人员管理平台上，选择 API 密钥选项卡。
2. 在标准密钥列表中，点击密钥行中的显示测试密钥。
3. 通过点击来复制密钥的值。
4. 保存密钥的值。
5. 点击隐藏测试密钥。

显示真实模式的私钥或受限 API 密钥

在真实模式下，Stripe 只向您显示一次私钥或受限 API 密钥（安全起见）。请妥善保管密钥，以防丢失。为帮助您记住它的保存位置，您可以在管理平台中添加密钥备忘。一旦丢失，可轮换或将它删除，然后重新创建一个。

在真实模式下显示私钥或受限密钥并附加注释：

1. 在开发人员管理平台上，选择 API 密钥选项卡。
2. 点击要显示的密钥所在行的标准密钥列表中的显示真实密钥或受限密钥。
3. 通过点击来复制密钥的值。
4. 保存密钥的值。
5. 点击隐藏测试密钥。
6. 点击密钥旁的溢出菜单()，然后选择编辑密钥。
7. 在注释字段中，输入保存密钥的位置，然后点击保存。
8. 如果您在 Stripe 引入此功能之前创建了密钥，请点击隐藏真实密钥。

将密钥或受限密钥限制在一个 IP 地址列表或范围内

将使用密钥的 API 请求限制到一个或多个特定的 IP 地址或 IP 地址范围：

1. 打开 API 密钥页面。
2. 点击要显示的密钥所在行的标准密钥列表或受限密钥列表中的溢出菜单()，然后选择管理 IP 限制。
3. 点击仅限于使用一组 IP 地址。
4. 输入 IP 地址或 IP 地址范围：
   • 对于单个 IP 地址，在 IP 地址字段中输入。
   • 对于 IP 地址范围，在无类别域间路由 (CIDR) 表示法中输入范围。在 IP 地址字段，输入该范围的第一个地址。在 CIDR 字段，输入网络前缀大小。
   • 也可以选择批量管理选项卡并输入单个的 IP 地址和范围，用空格分隔。在一个选项卡中所作更改会显示在另一个选项卡中。
5. 要添加另一个地址或范围，请点击 + 添加。
6. 点击保存。

更改私钥或受限 API 密钥的名称或注释

要更改私钥或受限密钥的名称或注释文本：

1. 打开 API 密钥页面。
2. 点击要更改的密钥所在行的溢出菜单 ()，然后选择编辑密钥。
3. 如果要更改名称，请在密钥名称中输入新名称。
4. 如果要更改注释文本，请在注释中输入新的注释文本。
5. 点击保存。

保护您的密钥安全

任何人都可以用您真实模式下的 API 私钥来代您的账户进行任何 API 调用，例如创建收款或执行退款。按照 API 私钥最佳实践保护您的密钥安全。