# 受限 API 密钥

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

您可以使用受限 API 密钥 (RAK) 为您的 API 密钥分配特定的 Stripe API 权限。使用 RAK 可以将 API 密钥泄露给恶意方时对业务造成的潜在损害降到最低。如果受限 API 密钥没有完成某个 API 请求所需的权限，Stripe 会返回[无效请求错误](https://docs.stripe.com/error-handling.md#invalid-request-errors)。

## 什么是受限 API 密钥？

注册 Stripe 时，您会获得一个[秘密 API 密钥](https://docs.stripe.com/keys.md#obtain-api-keys)（以 `sk_live_` 或 `sk_test_` 开头）。任何持有此密钥的人、代理或系统都可以在您的 Stripe 账户中执行_任何_操作：创建收款、发放退款、读取客户数据、触发提现等。

受限 API 密钥 (RAK) 以 `rk_live_` 或 `rk_test_` 开头，只能执行您授权的操作。在 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/test/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 (...)` → **PaymentIntent：写入**
- `Customer.retrieve (...)` → **客户：读取**
- `Dispute.list(...)` → **争议：读取**

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

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

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

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

按照上述说明，使用测试模式下的受限密钥测试您的应用，使您的应用使用该密钥发起 Stripe API 请求。测试应用中使用 Stripe API 的每一个组件。

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

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