API 密钥

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

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

测试模式 vs 真实模式

所有 Stripe API 请求，要么发生在测试模式，要么发生在真实模式。使用测试模式访问测试数据，使用真实模式访问实际账户数据。每种模式都有自己的一组 API 密钥。一个模式下的对象不能在另一模式下访问。例如，测试模式下的产品对象不能构成真实模式下付款的一部分。

私钥和公钥

默认情况下，所有账户总共有四个 API 键——两个用于测试模式，两个用于真实模式：

• 测试模式下的私钥：在测试模式下，使用此密钥对服务器上的请求进行身份验证。默认情况下，您可以不受任何限制地使用此密钥执行任何 API 请求。
• 测试模式下的公钥：在您的网页或移动应用程序的客户端代码中用此密钥进行测试。
• 真实模式下的私钥：在真实模式下，使用此密钥对服务器上的请求进行身份验证。默认情况下，您可以不受任何限制地使用此密钥执行任何 API 请求。
• 真实模式下的公钥：在准备启动您的应用程序时，在您的网页或移动应用程序的客户端代码中使用此密钥。

You can find your secret and publishable keys in API keys. When you’re logged in, Stripe’s documentation automatically populates code examples with your test mode API keys (only you can see these values). If you’re not logged in, our code examples include randomly generated API keys. You can replace them with your own test keys or log in to see the code examples populated with your test API keys. If you can’t view your API keys, ask the owner of your Stripe account to add you to their team, with the proper permissions.

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

保护您的密钥安全

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

用受限 API 密钥自定义 API 访问

要限制对 API 的访问，请创建受限 API 密钥。您可以配置受限 API 密钥，以允许对特定 API 资源进行读写访问。当使用代表您与 API 交互的微服务时，请定义受限密钥，仅允许微服务所需的最低访问权限。例如，如果您使用争议监测服务，请创建一个受限密钥，该密钥仅提供对争议相关资源的读取权限。该密钥允许服务获得它需要的数据，但不允许它进行任何更改或访问任何其他数据。

受限制的密钥不能与 Stripe API 的很多部分交互，因为它们的目的仅仅是降低使用或构建微服务时的风险。在开发您的 Stripe 集成的过程中，不要用受限制的密钥代替您账户的 API 私钥或公钥。

限制可发送 API 请求的 IP 地址

您可以通过限制可用来发送 API 请求的 IP 地址来提高私钥或受限密钥的安全性。此外，您可以将密钥限制在一个或多个 IP 地址或一个 IP 地址范围内。

显示测试模式的 API 私钥

在测试模式下，您可以任意多次显示一个 API 私钥。

在测试模式下显示 API 私钥：

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

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

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

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

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

滚动 API 密钥

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

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

要滚动 API 密钥：

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

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

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

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

删除私钥或受限 API 密钥

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

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

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

创建 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. 在添加注释字段中，输入保存密钥的位置，然后点击完成。

将密钥或受限密钥限制在一个 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 请求日志，点击任意密钥的溢出菜单()，然后选择查看请求日志。打开日志会使您返回到 Stripe 主管理平台。