# 受限 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 密钥。

您可以使用受限密钥作为防御措施，以在您的 Stripe 账户密钥泄露或被入侵时保护账户安全。如果恶意用户获得了受限 API 密钥，他们的操作将仅限于该密钥的权限。例如，您可以创建一个只能读取争议数据而不能执行其他操作的受限密钥。如果恶意用户获得了这个密钥，他们只能读取争议数据，无法创建收款、访问客户支付方式或触发付款。

Stripe 建议始终使用受限密钥，而非不受限密钥。使用受限密钥时务必遵循最佳实践，避免意外泄露或被盗用。参见[管理 API 密钥的最佳实践](https://docs.stripe.com/keys-best-practices.md)。

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

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

### 切换到受限 API 密钥的理由

- **限制潜在密钥被攻破的影响**：如果受限密钥被攻破，恶意用户只能访问您允许该密钥访问的特定资源。

- **安全地与第三方共享密钥**：Stripe 在大多数情况下不鼓励共享密钥，但对于某些第三方集成，您可能需要共享密钥。例如，如果供应商需要监控您的争议，可提供只读争议访问的受限密钥，而非您的不受限密钥。与第三方合作时，请确保他们遵循[最佳实践](https://docs.stripe.com/keys-best-practices.md)，如尽可能使用 IP 允许列表降低密钥泄露风险，并在合作结束时使密钥失效。

- **满足合规期望**：许多安全审计和合规框架要求遵循最小权限原则，受限密钥可以轻松实现。

- **结合 IP 限制**：您可以将受限密钥绑定到特定 IP 地址，增加额外防护层。

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

受限 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 用量

查看您的代码和任何第三方集成，记录您使用的 Stripe 产品以及当前使用密钥发出的 API 调用。

查看 Workbench 中密钥的[请求日志](https://dashboard.stripe.com/workbench/logs)。您可以使用下表将成功的 API 请求映射到对应 RAK 所需的权限。

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

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

### 在沙盒中创建一个受限密钥

Stripe 建议在创建真实模式密钥之前，先在 Stripe 沙盒中创建一个受限密钥。

1. 前往 Stripe 管理平台的 [API 密钥页面](https://dashboard.stripe.com/apikeys)。
1. 点击**创建受限密钥**。
1. 为它取一个描述性名称，比如 `billing-service-test`。
1. 根据之前观察到的 API 用量，为每个资源设置权限：**无权限**、**读取**或**写入**。

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

在测试或预备环境中，用受限密钥替换服务器环境中的密钥（例如在环境变量或密钥管理器中）。使用密钥的 Stripe SDK 和 HTTP 调用保持不变，唯一不同的是密钥值。

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

在测试模式中，通过 [密钥列表](https://dashboard.stripe.com/apikeys) 查看受限密钥日志：点击密钥旁的溢出菜单 (⋯)，选择**查看请求日志**。

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

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

检查您的应用日志是否有 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)页面中。
1. 找到您要配置的受限密钥。
1. 点击密钥旁边的溢出菜单 (⋯)。
1. 点击**查看请求日志**，查看该密钥发出的所有请求。

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

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

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

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

如果应用未正常运行，可筛选请求日志显示失败请求，然后在密钥菜单中编辑密钥权限，添加相应的 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 权限。为每个服务单独设置权限，可以在某个服务被攻破时，将密钥被盗的潜在影响降到最低。