# 受限 API 密钥

使用受限 API 密钥控制您的应用对 Stripe API 的访问权限。

您可以使用受限 API 密钥 (RAK) 为您的 API 密钥分配特定的 Stripe API 权限。在您向 [AI 智能体提供 API 密钥](https://docs.stripe.com/keys.md#agent-keys)时，推荐使用 RAK 类型的密钥。如果 API 密钥暴露给恶意用户，使用 RAK 可以限制对您的业务造成的潜在损害。如果受限 API 密钥没有完成 API 请求所需的正确权限，Stripe 会返回[无效请求错误](https://docs.stripe.com/error-handling.md#invalid-request-errors)。

## 什么是受限 API 密钥？

受限 API 密钥 (RAK) 是您的服务器端应用程序包含在 Stripe API 请求中的 API 密钥。RAK 以 `rk_live_` 或 `rk_test_` 开头。与可以在您的 Stripe 账户中执行任何操作的密钥不同，RAK 只能执行您授予其权限的操作。当您在 Stripe 管理平台中创建 RAK 时，您可以选择该密钥可以访问的 Stripe 资源以及每个资源的权限：**读取**、**写入**或**无**。所有 Stripe API 均支持受限 API 密钥。

将 RAK 作为一种防御措施来保护您的 Stripe 账户，以防您的密钥被泄露或盗用。如果恶意用户获得了一个 RAK，他们也只有该密钥的权限范围。例如，您可以创建一个只能读取争议数据而无法进行任何其他操作的 RAK。如果恶意用户获得了这个密钥，他们只能读取争议数据，而无法创建扣款、访问客户支付方式或触发付款。

Stripe 建议始终使用 RAK 代替无限制的密钥，尤其是在将密钥提供给 AI 智能体时。可以通过 RAK 的权限设置来限制智能体在您账户中可以执行的操作。

在使用 RAK 时，应始终遵循[最佳实践](https://docs.stripe.com/keys-best-practices.md)，以避免意外泄露或被盗用。对待 RAK 应与对待 API 密钥一样谨慎。

## 为什么要使用受限密钥而不是不受限密钥？

|  | 不受限密钥 (`sk_`) | 受限密钥 (`rk_`) |
| --- | --- | --- |
| **访问范围** | 对所有 API 资源的完全访问权限 | 只有您分配的权限 |
| **泄露后的影响** | 恶意用户可以对您的账户做任何操作 | 恶意用户只能执行密钥允许的操作 |
| **适用于 AI 智能体** | 智能体可能会在您的账户中执行您不希望的操作 | 您可以明确控制智能体的权限 |
| **第三方共享** | 危险：将完全控制权交给第三方 | 更安全：仅提供第三方所需的访问权限 |
| **最小权限原则** | 无法通过不受限密钥实现 | 您可以给密钥最低限度的权限 |
| **监管合规** | 您可以控制谁可以访问您的密钥，但无法控制密钥的用途 | 您可以控制谁能访问您的密钥，同时也可以控制这些密钥可以执行的操作 |
| **Stripe 建议** | 谨慎使用，严格防护 | **优先**：尽可能使用受限密钥 |

## 创建受限 API 密钥

1. 在 [API 密钥](https://dashboard.stripe.com/apikeys)选项卡中，请执行以下任一操作：
   - 要创建新的受限密钥，请点击**创建受限密钥**。
   - 如需克隆现有密钥，点击目标密钥对应的溢出菜单 (⋯)，然后选择**复制密钥**。新克隆密钥的各项权限默认与被克隆的密钥保持一致。
2. 如果您正在创建新密钥，可以选择使用预配置的权限集，也可以从零开始自定义权限。
3. 在**密钥名称**字段中输入名称。如果您是克隆现有密钥，新密钥的默认名称将与被克隆的密钥名称一致。
4. 针对您希望新密钥能够访问的每一项资源，选择对应的权限：**无**、**只读**或**读写**。如果您使用了 Connect，还可以设置该密钥在访问 Connect 子账户时所拥有的权限。所有权限的默认值为**无**。
5. 点击**创建密钥**。
6. 在对话框中，完成我们发送给您的双因素验证。
7. 点击密钥内容即可复制该密钥。
8. 保存密钥的值。以后无法再检索到它。
9. 在**添加备注**字段中输入您保存该密钥的位置，然后点击**完成**。

## 从不受限密钥迁移为受限密钥

在您的服务器环境中，受限 API 密钥可直接替代秘密 API 密钥。要使用受限 API 密钥，应像使用秘密密钥一样在代码中提供，同时遵循[最佳实践](https://docs.stripe.com/keys-best-practices.md)，避免意外泄露密钥。所有 Stripe API 均支持受限 API 密钥。您需要为每个受限密钥配置权限，以发挥其全部安全优势。

以下部分描述了一个逐步方法，指导您如何从秘密密钥迁移为受限密钥。参见[为受限 API 密钥分配权限](https://docs.stripe.com/keys/restricted-api-keys.md#assign-permissions)，了解如何减少受限密钥的权限。

### 在沙盒中创建受限 API 密钥

在创建真实模式密钥之前，请先在[沙盒](https://docs.stripe.com/keys.md#test-live-modes)中创建受限 API 密钥。

1. 在 Stripe 管理平台的 [API 密钥页面](https://dashboard.stripe.com/apikeys)上，点击**创建受限密钥**。
2. 为新密钥设置一个描述性名称，例如 `billing-service-test`。
3. 暂时不要为密钥设置任何权限。请在查看秘密密钥的现有使用情况后，再设置权限。

### 查看密钥的 API 用量

以秘密密钥现有的 API 用量为基准，为 RAK 设置权限。

- 查看您的代码和任何第三方集成，记录您使用的 Stripe 产品以及当前使用密钥发出的 API 调用。
- 查看秘密密钥的[请求日志](https://docs.stripe.com/keys.md#view-request-logs)，以了解成功的 API 请求。

使用下表将成功的 API 请求映射到您的 RAK 所需的权限。根据您观察到的 API 用量，将每个资源的权限设置为 **无**、**读取** 或 **写入**。写入权限包含读取权限：任何能够写入 API 资源的密钥也可以读取该资源。

| HTTP 方法 | RAK 权限类型 |
| --- | --- |
| GET | 读取 |
| POST | 写入 |
| DELETE | 写入 |

例如，如果您看到使用秘密密钥成功调用 `GET /v1/customers`，则需要为替换 RAK 的[客户](https://docs.stripe.com/api/customers.md)资源添加读取权限。

### 配置预备环境以使用受限密钥

在测试或预演应用中，将服务器环境中的密钥替换为受限密钥（例如，存放在[密钥保管库](https://docs.stripe.com/keys-best-practices.md#use-a-secrets-vault)中；如果您的平台不提供密钥保管库，则使用环境变量）。使用密钥的 Stripe SDK 和 HTTP 调用功能完全相同，唯一的区别仅在于密钥的数值不同。

### 检查受限密钥的请求日志是否有错误并调整权限

在沙盒环境的[密钥列表](https://dashboard.stripe.com/apikeys)中查看受限密钥日志：点击该密钥旁的溢出菜单 (⋯)，然后选择**查看请求日志**。

如果您发现任何错误信息，比如 `403 ERR`，编辑受限密钥权限以添加失败的操作：

1. 点击密钥旁边的溢出菜单 (⋯)。
2. 选择**编辑密钥**。
3. 在沙盒中重复测试，确认已为受限密钥分配正确权限。

检查您的应用日志是否有 Stripe API 错误。如果随请求发送的受限密钥权限不正确，响应正文会显示错误消息，说明需要添加哪些权限。

### 创建一个真实模式的受限密钥

在真实模式下创建一个新的受限密钥，其权限应与您测试过的沙盒密钥相匹配。

### 配置您的生产环境使用受限密钥

在生产环境使用该新密钥，配置方式与您在预发环境配置沙盒密钥的方式相同。

### 停用旧密钥

当您确认沙盒环境全部功能正常后，请在管理平台中对旧私密密钥执行[轮换](https://docs.stripe.com/keys.md#rolling-keys)或[使其失效](https://docs.stripe.com/keys.md#delete-secret-key)。此举可确保该密钥后续无法被任何人使用。如需设置安全缓冲期（缓冲期内仍可恢复使用该密钥），可选择延迟过期（最长 7 天）。

## 为受限 API 密钥分配权限

您可以根据最小权限原则配置受限密钥，以满足特定应用场景：密钥应仅具备完成其任务所需的最少权限。以下是几种实用的分配权限方法。

### 审核请求日志以确定权限

1. 前往管理平台的 [API 密钥](https://dashboard.stripe.com/apikeys)页面中。
2. 找到您正在配置的受限密钥。
3. 点击密钥旁边的溢出菜单 (⋯)。
4. 点击**查看请求日志**，查看该密钥发出的所有请求。

使用受限密钥测试后，检查您的应用调用的 API 端点，查看应用具体使用了哪些资源，以及对这些资源是读取还是写入操作：

- `GET` 请求为读取操作
- `POST` 和 `DELETE` 请求为写入操作

如果您的应用在测试中运行正常，可列出请求日志中成功的调用，并与分配给受限密钥的权限进行对照。未使用的权限可以移除。要编辑密钥的权限：

1. 点击溢出菜单 (⋯)。
2. 点击**编辑密钥**。

如果应用未正常运行，可筛选请求日志显示失败请求，然后在密钥菜单中编辑密钥权限，添加相应的 Stripe API 权限。

### 审查您的代码

可通过搜索代码库中的 Stripe SDK 调用来建立所需权限列表，并将每个调用映射到管理平台中对应权限。例如：

- `PaymentIntent.create(...)` → **Payment Intents：写入**
- `Customer.retrieve (...)` → **客户：读取**
- `Dispute.list(...)` → **争议：读取**

然后将受限密钥权限配置为仅匹配实际所需权限。

### 先赋予宽泛权限，再删除不需要的权限

可以先为受限密钥赋予宽泛权限，再根据密钥实际使用情况删除多余权限。

在沙盒环境中，从 API 密钥菜单创建一个受限密钥。可用权限按类别分组。如果您知道您的 Stripe API 使用不包含某个特定类别（例如 Stripe Billing），可以为该类别选择**无权限**。否则，对于与您的 Stripe API 使用相关的类别，选择**写入**。**写入**权限包含**读取**权限：如果一个密钥可以写入某个 API 资源，它也可以读取该资源。

使用沙盒受限密钥，按上述方法测试应用，确保应用可凭借该密钥发起 Stripe API 请求。对应用中所有调用 Stripe API 的组件均进行测试。

## 每个服务或应用场景使用一个受限密钥

如果您有多个使用 Stripe API 的服务（例如计费服务、报表服务和 webhook 处理器），请为每个服务创建一个独立的受限密钥，并仅授予每个服务所需的 Stripe API 权限。为每个服务单独设置权限，可以在某个服务被攻破时，将密钥被盗的潜在影响降到最低。

## See also

- [API 密钥](https://docs.stripe.com/keys.md)
- [管理私密 API 密钥的最佳实践](https://docs.stripe.com/keys-best-practices.md)
- [上线检查清单](https://docs.stripe.com/get-started/checklist/go-live.md)
