# 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)标签页中可以查看您的 v1 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 密钥](https://docs.stripe.com/keys/restricted-api-keys.md) (RAK) 视为敏感信息，切勿将其暴露在服务器环境之外。为确保您的业务安全，请阅读并理解[秘密 API 密钥管理的最佳实践](https://docs.stripe.com/keys-best-practices.md)。 请使用沙盒密钥（而非真实模式密钥）进行开发、[测试](https://docs.stripe.com/testing.md)以及应用调试，以确保不会意外修改到真实客户或扣款数据。 | 类型 | 安全公开 | 默认生成 | 说明 | | ------------------------------ | ---- | ---- | ---------------------------------------------------------------------------------------------------------------------------------- | | 沙盒秘密密钥 `sk_test_` | 否 | 是 | 在沙盒环境中进行测试时，请在服务器端对请求进行身份验证。默认情况下，您可以使用此密钥执行任何 API 请求，且不受任何限制。 | | 沙盒受限 API 密钥 (RAK) `rk_test_` | 否 | 否 | 与秘密密钥类似，但其 Stripe API 权限可由您自行控制。您可以在代码的不同部分使用不同的受限 API 密钥 (RAK)，以便精确地将权限匹配到各个应用组件。在创建真实模式 RAK 之前，请先使用沙盒 RAK 来调整您应用的 Stripe API 权限。 | | 沙盒可发布密钥 `pk_test_` | 是 | 是 | 在您的网页或移动应用的客户端代码中测试请求。 | | 真实模式秘密密钥 `sk_live_` | 否 | 是 | 在真实模式下，用于在服务器端对 API 请求进行身份验证。默认情况下，您可以使用此密钥发起任意无限制的 API 请求。 | | 真实模式受限 API 密钥 (RAK) `rk_live_` | 否 | 否 | 为服务端组件分配自定义权限，让应用的每个部分都精确获得其所需的 Stripe API 权限。使用受限 API 密钥 (RAK) 替代秘密密钥，可以在密钥意外泄露或应用遭到入侵时，限制可能造成的损失。 | | 真实模式可发布密钥 `pk_live_` | 是 | 是 | 当您准备发布应用时，可在网站或移动应用的客户端代码中使用此密钥。 | 您可以在 Stripe 管理平台中找到您的 [API 密钥](https://dashboard.stripe.com/apikeys)。如果您无法查看自己的 API 密钥，但需要为应用管理密钥，请联系您的 Stripe 账户所有者，请其将您添加至他们的[团队](https://docs.stripe.com/get-started/account/teams.md)并授予相应权限。 如果您已登录 Stripe，我们的文档会在某些位置显示您的测试 API 密钥，以便说明 API 的使用方法。只有您本人能看到这些密钥值。如果您未登录，我们的代码示例中则会包含随机生成的 API 密钥。 > #### Webhook 签名密钥 > > Webhook 签名密钥不是 API 密钥——它们是每个 Webhook 独有的密钥，供您的 Webhook 接收器用于身份验证 Webhook 确实来自 Stripe。您可以在管理平台的 [Webhooks](https://dashboard.stripe.com/webhooks) 部分找到每个 Webhook 端点的签名密钥。 ## 密钥安全防护 任何人都可以使用您的真实模式秘密密钥，代表您的账户发起任何 API 调用，例如创建扣款或执行退款。*您有责任保管好您的密钥*。请遵循以下最佳实践保护您的密钥： - 将密钥存储在机密保管库或加密的环境变量中。不要将密钥存储在源代码或已纳入版本控制的配置文件中。 - 请尽可能使用[受限 API 密钥](https://docs.stripe.com/keys.md#create-restricted-api-secret-key)而非机密密钥。受限密钥仅允许访问您的集成所需的具体 API 资源，从而降低密钥泄露造成的影响。 - [将密钥绑定至特定 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)。 ## 沙盒与真实模式 所有 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)无法用于真实模式下的支付。 | 模式 | 密钥前缀 | 目的 | | ------ | ---------------------------------- | ---------------------- | | 沙盒（测试） | `pk_test_`, `sk_test_`, `rk_test_` | 安全地构建和测试您的集成。不会产生真实收款。 | | 真实 | `pk_live_`, `sk_live_`, `rk_live` | 接受真实客户的真实付款。 | > #### 真实模式密钥访问 > > 真实模式下的 API 密钥或受限 API 密钥仅可被查看一次。如果不慎遗失，将无法从管理平台中找回。遇此情况，您可以先执行轮换或删除操作，再重新生成新密钥。 | 类型 | 何时使用 | 对象 | 如何使用 | 考虑 | | ---- | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | 沙盒 | 使用沙盒及其关联的测试 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)的支付流程更加细致，要求更多步骤。 | ## 切换到真实模式 当您准备好接受真实付款时，请使用生产模式 API 密钥，而非沙盒（测试）密钥。在 [API 密钥](https://dashboard.stripe.com/apikeys)页面上，将开关从**沙盒模式**切换到**真实模式**。此时页面将显示您的真实模式 API 密钥。 ### 可发布密钥（客户端） 1. 复制您的**真实模式可发布密钥**（以 `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 密钥。改为使用密钥保管库或环境变量来提供沙盒密钥，并确认您的应用仍然可以正常运行。 1. 显示并复制您的**真实模式密钥**（以 `rk_live_` 或 `sk_live_` 开头），并将其安全地存储在您的服务器环境中。请注意——每个真实模式的受限密钥或秘密密钥您只能查看一次。 1. 配置您的服务器环境，让其为您的应用程序提供真实模式密钥，而不是沙盒密钥。 1. 如果您使用 Webhook，请更新每个 Webhook 端点的 URL，并从管理平台的 [Webhook](https://dashboard.stripe.com/webhooks) 部分复制新的**签名私钥**。 > #### 完整的上线检查清单 > > 切换 API 密钥只有一步。审核完整的[上线检查清单](https://docs.stripe.com/get-started/checklist/go-live.md)，以确保您的集成已准备好投入生产。 ## 私钥和受限密钥 您可以通过管理平台，执行密钥和受限密钥的创建、查看、修改、删除及轮换操作。 ### 创建 API 密钥 建议用户创建 RAK，而不是使用密钥。使用密钥可能会增加安全漏洞的影响。 - 我们建议在大多数应用场景下创建[受限 API 密钥](https://docs.stripe.com/keys/restricted-api-keys.md) (RAK)。使用受限 API 密钥，您可以精确分配集成所需的权限，从而降低恶意行为者在获取您的密钥后可能对您的业务造成的损害。仅当您的集成需要访问所有 Stripe API 和资源时，才创建无限制的秘密 API 密钥。 #### 创建受限 API 密钥 1. 在 [API 密钥](https://dashboard.stripe.com/test/apikeys)标签页中，请执行以下任一操作： - 如需创建新的受限密钥，点击**创建受限密钥**。该密钥的所有权限默认均为**无权限**。 - 如需克隆现有密钥，点击目标密钥对应的溢出菜单 (⋯)，然后选择**复制密钥**。新克隆密钥的各项权限默认与被克隆的密钥保持一致。 1. 在**密钥名称**字段中输入名称。如果您是克隆现有密钥，新密钥的默认名称将与被克隆的密钥名称一致。 1. 针对您希望新密钥能够访问的每一项资源，选择对应的权限：**无**、**只读**或**读写**。如果您使用了 Connect，还可以设置该密钥在访问 Connect 子账户时所拥有的权限。 1. 点击**创建密钥**。 1. 在弹出的对话框中，输入 Stripe 通过邮件或短信发送给您的验证码。如果对话框未自动跳转，可点击**继续**。 1. 点击密钥内容即可复制该密钥。 1. 保存密钥的值。以后无法再检索到它。 1. 在**添加备注**字段中输入您保存该密钥的位置，然后点击**完成**。 #### 创建 API 密钥 1. 在 [API 密钥](https://dashboard.stripe.com/test/apikeys)标签页中，点击**创建密钥**。 1. 在弹出的对话框中，输入 Stripe 通过邮件或短信发送给您的验证码。如果对话框未自动跳转，可点击**继续**。 1. 在**密钥名称**字段中输入名称，然后点击**创建**。 1. 点击密钥内容即可复制该密钥。 1. 保存密钥的值。以后无法再检索到它。 1. 在**添加备注**字段中输入您保存该密钥的位置，然后点击**完成**。 ### 显示 API 密钥 您可以在沙盒模式或真实模式下显示受限 API 密钥或秘密 API 密钥。 在真实模式下，Stripe 每个受限 API 密钥或秘密 API 密钥只会向您显示一次。请将密钥保存在不会丢失的地方，但不要存放在应用程序的代码中。为了提醒自己存储位置，您可以在管理平台中为该密钥添加备注。如果丢失了密钥，您可以轮换或删除它，然后重新创建一个。 > #### 显示真实模式下的密钥 > > 在真实模式下创建私钥或受限 API 密钥后，我们会在您保存它之前显示它。保存前必须复制密钥，因为之后不能再复制。您只能显示默认私钥或由预定轮换产生的密钥。 #### 在真实模式下显示密钥或受限 API 密钥 1. 在真实模式下的 [API 密钥](https://dashboard.stripe.com/apikeys)标签页中，在**标准密钥**或**受限密钥**列表内，点击您想要查看的密钥对应的**显示真实密钥**。 1. 点击密钥内容即可复制该密钥。 1. 请将密钥值保存在安全的地方，例如您平台上的密钥保管库或后端环境变量配置中。 1. 点击**隐藏测试密钥**。 1. 点击目标密钥对应的溢出菜单 (⋯)，然后选择**编辑密钥**，为该密钥添加备注。 1. 在**备注**字段中输入您保存该密钥的位置，然后点击**保存**。 > 在 Stripe 推出此功能之前创建的密钥，在被查看后不会自动隐藏，您需要点击**隐藏真实密钥**，手动隐藏这些密钥。 ### 限制 API 密钥的访问 IP 地址 您可以将机密 API 密钥或受限 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 密钥 如果您在[组织](https://docs.stripe.com/get-started/account/orgs.md)中有多个 Stripe 商家账户，您可以在组织级别配置单个 API 密钥。组织级别 API 密钥提供以下功能： - **任意账户访问权限**：可以使用组织 API 密钥，访问组织内任意账户的资源。 - **限制权限**：将组织 API 密钥的权限限制为仅对特定资源授予读取或写入权限。 - **集中化管理**：您可以在组织的管理平台的 [API 密钥](https://dashboard.stripe.com/org/api-keys/secret)标签页中，创建并管理组织 API 密钥。 ### 行为 组织 API 密钥的行为与账户级 API 密钥不同，包括： - 他们没有公钥。将所有组织 API 密钥视为私钥。 - 无论其权限级别如何，它们都具有相同的 `sk_org` 前缀。 - 使用组织 API 密钥发出的所有 API 请求都必须包含 `Stripe-Context` 标头，以识别受影响的账户。 - 使用组织 API 密钥发出的所有 API 请求都必须包含 `Stripe-Version` 头，以确保贵组织集成的一致性和可预测性。 ### 使用组织 API 密钥 使用组织 API 密钥时，还必须： - 通过包含 `Stripe-Version` 头来指定 API 版本。使用 [Stripe SDK](https://docs.stripe.com/sdks/set-version.md) 时，SDK 会自动设置 API 版本。 - 通过包含 `Stripe-Context` 头来识别受 API 请求影响的账户。 例如，给定以下组织结构： ``` Organization (org_6SD3oI0eSQemPzdmaGLJ5j6) ├── Platform account (acct_1R3fqDP6919yCiFv) | └── Connected account (acct_1032D82eZvKYlo2C) └── Standalone account (acct_1aTnTtAAB0hHJ26p) ``` 您可以使用组织 API 密钥访问独立账户的余额。也可以使用相同的密钥对平台 Connect 子账户进行相同的调用。 ```curl curl https://api.stripe.com/v1/balance \ -u {{ORG_SECRET_KEY}}: \ -H "Stripe-Version: {{STRIPE_API_VERSION}}" \ -H "Stripe-Context: {{CONTEXT_ID}}" ``` 在上述代码示例中，请将 `{{CONTEXT}}` 替换为对应的值： - 对于独立账户，请使用 `acct_1aTnTtAAB0hHJ26p`。 - 对于 Connect 子账户，请使用能够同时标识平台和关联账户的路径，格式参考 `acct_1R3fqDP6919yCiFv/acct_1032D82eZvKYlo2C`。 在使用组织密钥的任何 API 请求中，您必须使用上下文和 API 版本来指定相关账户。 组织没有可发布 API 密钥，因为它们无法接受付款。您可以使用组织 API 密钥，为组织内的任意账户创建 PaymentIntent，但在执行客户端操作时，必须使用已有的、特定于账户的可发布密钥。 ## 管理 API 密钥 [Vercel](https://vercel.com/docs/integrations/ecommerce/stripe) 等部分第三方平台，可以在您安装集成时代为创建和管理 API 密钥。这些密钥称为托管 API 密钥，平台程序化地创建它们，而不是您在管理平台手动创建。 托管 API 密钥会与其他密钥并列出现在 [API 密钥](https://dashboard.stripe.com/test/apikeys)标签页，并标注托管平台名称。 下表总结了非托管密钥和托管密钥之间的区别。 | | 非托管密钥 | 托管密钥 | | ---- | ----------------- | -------------------- | | 密钥创建 | 您在管理平台中创建密钥 | 平台利用该 API 创建密钥 | | 用户互动 | 您从管理平台复制密钥并在平台中配置 | 平台将自动处理密钥设置 | | 密钥交付 | 在管理平台中展示给您 | 直接送达平台 | | 密钥管理 | 您控制轮换和有效期 | 平台管理密钥生命周期；您可随时使密钥失效 | ### 撤销托管密钥访问权限 您可以通过以下任一操作随时撤销托管 API 密钥： - **使密钥失效**：在 [API 密钥](https://dashboard.stripe.com/apikeys)标签页，点击托管密钥的溢出菜单（⋯），然后使其失效。这会立即撤销平台的访问权限，但不会移除集成。 - **卸载集成**：从您的 Stripe 账户卸载平台的应用。卸载应用时，您可以立即使托管密钥失效或保持其激活状态。 ## 查看 API 请求日志 如需[打开 API 请求日志](https://docs.stripe.com/development/dashboard/request-logs.md)，请点击任意密钥对应的溢出菜单 (⋯)，然后选择**查看请求日志**。打开日志后，系统会将您重定向至 Stripe 管理平台。 ## 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)