# 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 吗？ > > - **构建和测试？**使用您的**沙盒（测试模式）密钥**。沙盒密钥以 `pk_test_`（可发布）和 `sk_test_`（私钥）为开头。它们可让您测试，且不影响真实数据。 - **准备好接受真实付款了吗？**切换到您的**真实模式密钥**，它们以 `pk_live_` 和 `sk_live_` 开头。有关说明，请参阅[切换到真实模式](https://docs.stripe.com/keys.md#switch-to-live-mode)。 - \**在寻找您的 Webhook 签名私钥吗？**Webhook 私钥与 API 密钥是分开的。可在管理平台的 [Webhook](https://dashboard.stripe.com/webhooks) 部分中，在每个 Webhook 端点下方找到它们。 ## 密钥类型 默认情况下，所有账户共有四个 API 密钥： | 类型 | 说明 | | --------- | ----------------------------------------------------------------------------------------- | | 沙盒密钥 | 在沙盒中，用于在服务器端对请求进行身份验证。默认情况下，您可以使用此密钥发起任意无限制的 API 请求。请将此密钥仅用于测试和开发场景，以避免意外修改真实环境中的客户数据或收款。 | | 沙盒可发布密钥 | 在网站或移动应用的客户端代码中用于测试请求。请将此密钥仅用于测试和开发场景，以避免意外修改真实环境中的客户数据或收款。 | | 真实模式密钥 | 在真实模式下，用于在服务器端对 API 请求进行身份验证。默认情况下，您可以使用此密钥发起任意无限制的 API 请求。 | | 真实模式可发布密钥 | 当您准备发布应用时，可在网站或移动应用的客户端代码中使用此密钥。 | 您的密钥与可发布密钥均可在管理平台的 [API 密钥](https://dashboard.stripe.com/test/apikeys)标签页中查看。如果您无法查看 API 密钥，请联系您的 Stripe 账户所有者，将您添加至[团队](https://docs.stripe.com/get-started/account/teams.md)并为您配置相应的权限。 > #### 受限 API 密钥 > > 您可以在管理平台中生成[受限 API 密钥](https://docs.stripe.com/keys-best-practices.md#limit-access)，以启用对 API 的可自定义和限制性访问。但是，Stripe 默认不提供任何受限密钥。 > #### 在寻找您的 Webhook 签名私钥吗？ > > Webhook 签名私钥不是 API 密钥。您可以在管理平台的 [Webhook](https://dashboard.stripe.com/webhooks) 部分，查找各 Webhook 端点的签名私钥。选择一个端点并展开**签名密钥**部分。 如果您已登录 Stripe 账户，我们的文档会自动在代码示例中填充您的测试 API 密钥，且这些密钥值仅对您可见。如果您未登录，代码示例中会使用随机生成的 API 密钥，您可将其替换为自己的测试密钥；您也可以登录，查看自动填充了您的测试 API 密钥的代码示例。 ### API 密钥示例 下表展示了随机生成的密钥与可发布密钥示例： | 类型 | 值 | 何时使用 | | --- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | 私钥 | `sk_test_BQokikJOvBiI2HlWgH4olfQ2` | \**仅限服务器端。**在您的后端代码中使用此密钥（例如在环境变量中），向 Stripe 进行 API 调用。请妥善保管——绝不能分享、提交到源代码控制，也不要在浏览器或移动应用中暴露。任何拥有此密钥的人，都可以用您的账户进行 API 调用。 | | 可公开 | `pk_test_TYooMQauvdEDq54NiTphI7jx` | \**客户端（浏览器或移动应用）。**在您的前端代码中使用此密钥，通过 [Stripe Elements](https://docs.stripe.com/payments/elements.md) 或 [Stripe Checkout](https://docs.stripe.com/payments/checkout.md) 工具安全地收集支付信息。此密钥可以公开。 | | 已限制 | 以 `rk_test_` 开头的字符串 | \**仅限服务器端，权限有限。**类似于密钥，但您可以选择它能访问哪些 Stripe API 资源。当您希望限制系统或第三方可以执行的操作时，使用受限密钥代替密钥。参见[受限 API 密钥](https://docs.stripe.com/keys-best-practices.md#limit-access)。 | ### 密钥安全防护 任何人都可以使用您的真实模式密钥以您账户的名义进行任何 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_` | 安全地构建和测试您的集成。不会产生真实收款。 | | 真实 | `pk_live_`、`sk_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 密钥。这与管理平台中的密钥页面相同——您可以使用开发人员管理平台右上角的开关，在**测试模式**和**真实模式**之间进行切换。 1. 在[开发人员管理平台](https://dashboard.stripe.com/apikeys)中，通过右上角的模式开关，禁用**测试模式**。页面现在显示您的真实模式 API 密钥。 1. 复制您的**真实模式可发布密钥**（以 `pk_live_` 为开头），并替换您客户端代码中的 `pk_test_` 密钥。 1. 显示并复制您的**真实模式密钥**（以 `sk_live_` 为开头），并替换您的服务器端代码中的 `sk_test_` 密钥。请妥善保管——您只能查看一次。 1. 如果您使用 Webhook，请更新每个 Webhook 端点的 URL，并从管理平台的 [Webhook](https://dashboard.stripe.com/webhooks) 部分复制新的**签名私钥**。 > #### 完整的上线检查清单 > > 切换 API 密钥只有一步。审核完整的[上线检查清单](https://docs.stripe.com/get-started/checklist/go-live.md)，以确保您的集成已准备好投入生产。 ## 组织 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 密钥或受限 API 密钥。其中，[受限 API 密钥](https://docs.stripe.com/keys-best-practices.md#limit-access)仅拥有您所指定的访问权限等级。 #### 创建 API 密钥 1. 在 [API 密钥](https://dashboard.stripe.com/test/apikeys)标签页中，点击**创建密钥**。 1. 在弹出的对话框中，输入 Stripe 通过邮件或短信发送给您的验证码。如果对话框未自动跳转，可点击**继续**。 1. 在**密钥名称**字段中输入名称，然后点击**创建**。 1. 点击密钥内容即可复制该密钥。 1. 保存密钥的值。以后无法再检索到它。 1. 在**添加备注**字段中输入您保存该密钥的位置，然后点击**完成**。 #### 创建受限 API 密钥 1. 在 [API 密钥](https://dashboard.stripe.com/test/apikeys)标签页中，请执行以下任一操作： - 如需创建新的受限密钥，点击**创建受限密钥**。该密钥的所有权限默认均为**无权限**。 - 如需克隆现有密钥，点击目标密钥对应的溢出菜单 (⋯)，然后选择**复制密钥**。新克隆密钥的各项权限默认与被克隆的密钥保持一致。 1. 在**密钥名称**字段中输入名称。如果您是克隆现有密钥，新密钥的默认名称将与被克隆的密钥名称一致。 1. 针对您希望新密钥能够访问的每一项资源，选择对应的权限：**无**、**只读**或**读写**。如果您使用了 Connect，还可以设置该密钥在访问 Connect 子账户时所拥有的权限。 1. 点击**创建密钥**。 1. 在弹出的对话框中，输入 Stripe 通过邮件或短信发送给您的验证码。如果对话框未自动跳转，可点击**继续**。 1. 点击密钥内容即可复制该密钥。 1. 保存密钥的值。以后无法再检索到它。 1. 在**添加备注**字段中输入您保存该密钥的位置，然后点击**完成**。 ### 显示 API 密钥 您可以在沙盒或真实模式中显示 API 密钥或受限 API 密钥。 在真实模式下，出于安全考虑，Stripe 仅会向您展示一次 API 密钥。请将密钥妥善保存在不会丢失的位置。为了方便记忆存储位置，您可以在管理平台中为该密钥添加备注。如果不慎遗失密钥，您可以执行轮换或删除操作，再重新生成新密钥。 > #### 显示真实模式下的密钥 > > 在真实模式下创建私钥或受限 API 密钥后，我们会在您保存它之前显示它。保存前必须复制密钥，因为之后不能再复制。您只能显示默认私钥或由预定轮换产生的密钥。 #### 在沙盒中显示 API 密钥 1. 在 [API 密钥](https://dashboard.stripe.com/test/apikeys)标签页的**标准密钥**列表中，点击**密钥**行对应的**显示测试密钥**。您可以不限次数地查看该 API 密钥。 1. 点击密钥内容即可复制该密钥。 1. 保存密钥的值。 1. 点击**隐藏测试密钥**。 #### 在真实模式下显示密钥或受限 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 请求日志 如需[打开 API 请求日志](https://docs.stripe.com/development/dashboard/request-logs.md)，请点击任意密钥对应的溢出菜单 (⋯)，然后选择**查看请求日志**。打开日志后，系统会将您重定向至 Stripe 管理平台。 ## See also - [Best practices for managing secret API keys](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)