Source: https://cryptanio.com/zh/wiki/restrict-api-key-to-one-project/
Language: zh

# 如何将 API 密钥限制在单个项目内

为单个项目的服务器端账单核对创建专用密钥：选择项目、只读权限和必要的 API 部分，设置 IP 与有效期，再验证访问边界。

更新日期: 2026-11-14

API 密钥可以绑定到一个 Cryptanio 项目。下面以订单核对程序为例：它需要读取网店的[账单](<https://cryptanio.com/zh/wiki/shenme-shi-zhangdan/>)，但不应获取同一账户下其他项目的数据。该程序需要专用密钥：项目绑定决定数据范围，权限和 API 部分则决定允许执行的操作。

密钥名称和您应用中的项目编号，本身都不能限制访问。必须将限制保存到密钥的策略中。这些访问权限适用于公开 API v1；密钥不是登录账户管理页面的密码。

## 1\. 准备项目和权限 {#section-f7d3bf7436690692}

您需要账户所有者或管理员权限，以及一个现有、已启用且具有“支付”服务的项目。先确认您了解项目名称和用途：选错项目后，密钥可能仍然有效，但访问范围并不符合预期。

打开“API 密钥”。在“创建 API 键”表单的“标签”中填写名称，例如“商店订单核对”。单独命名有助于区分服务器程序，但实际保护由接下来的字段决定。

## 2\. 选择模式和具体项目 {#section-b8ace6fe4b6fa67e}

要读取真实账单，请在“模式”字段中选择“正式环境”。密钥必须与服务器请求的数据模式一致。

在“项目”字段中选择所需项目，而不是“所有项目”。账户页面会提示访问受所选项目服务的限制。项目绑定与服务访问权限同时生效：密钥本身不会启用服务，也不会扩展服务的功能。

## 3\. 仅保留账单读取权限 {#section-08522b0a9309256a}

在控制访问权限的“进入”字段中选择“唯读”。在“API 诸部”中保留“账单”，如果程序不需要其他部分，就取消其勾选。普通的账单状态核对不需要管理地址、webhook 或模拟功能的权限。

如果另一台服务器需要创建账单，则必须具有“读与写”权限和对应的 API 部分。应为其分配用途明确的另一把密钥，不要无必要地扩大核对程序的权限。写入权限仅在所选部分内生效，并不会开放整个 API。

## 4\. 设置 IP 和有效期 {#4-ip}

在“允许IP地址”中填写服务器的公网出口 IP 或必要的 CIDR 地址范围，每行一项。这里需要的是请求到达 API 时的来源地址，而不是买家的 IP。如果使用托管服务或代理，请确认实际出口地址。

字段留空表示允许任何 IP。如果服务器使用多个出口地址，应在配置时全部考虑，否则正确的密钥也可能无法通过校验。IP 限制是对项目和 API 部分选择的补充，不能替代它们。

如有需要，设置“到期时间”。所选日期的有效期截至 UTC 当天结束。请与集成的运行期限保持一致：密钥过期并不表示客户没有付款。

## 5\. 创建密钥并保存秘密值 {#section-c4ffbd0eaf95a857}

点击“创建密钥”，如果账户页面要求安全验证，请完成验证。从弹出的窗口复制秘密值，并保存在运行核对程序的服务器上。不要将其放入客户端 JavaScript、付款链接、与买家的通信或公开日志中。

关闭窗口后，不要指望从列表恢复秘密值：列表仅显示密钥的缩略标识。请检查表示访问范围的“边际”、项目、可用的 API 部分、有效期和状态。如需向开发者提供访问，应通过适当的安全存储交付，而不是将密钥连同说明公开发布。

## 6\. 验证允许和禁止的访问 {#section-760a382cc8c0e3eb}

从使用已允许 IP 的服务器读取该项目中一张已知账单。下面是 API 目录中的读取示例；请使用您自己的账单 ID 和刚创建的密钥：

```bash
#!/usr/bin/env bash
set -euo pipefail
: "${CRYPTANIO_RESOURCE_ID:?Set CRYPTANIO_RESOURCE_ID}"
: "${CRYPTANIO_API_KEY:?Set CRYPTANIO_API_KEY}"
urlencode() {
  local LC_ALL=C text="$1" char index
  for ((index=0; index<${#text}; index++)); do
    char="${text:index:1}"
    case "$char" in [a-zA-Z0-9.~_-]) printf '%s' "$char" ;; *) printf '%%%02X' "'$char" ;; esac
  done
}
response_file="$(mktemp)"
trap 'rm -f "$response_file"' EXIT
transfer_status=0
http_status="$(curl \
  --silent --show-error --max-time 30 --request GET \
  --header "Authorization: Bearer $CRYPTANIO_API_KEY" \
  --header 'Accept: application/json' \
  "https://api.cryptanio.com/v1/invoices/$(urlencode "$CRYPTANIO_RESOURCE_ID")" \
  --output "$response_file" --write-out '%{http_code}')" || transfer_status=$?
if [[ "$http_status" == 2?? ]]; then
  cat "$response_file"
  exit "$transfer_status"
fi
printf 'HTTP %s\n' "$http_status" >&2
cat "$response_file" >&2
exit 1
```

[下载示例](</wiki/examples/ae4ad34d7f9814c6019ca3494a7e6c605b0f2488e3bd223a4a4ce34ae8c220da.sh>)

接着，用您另一个项目中的已知账单验证访问边界：不应返回该账单的数据。列表也应始终限定在所选项目内。即使已启用“账单”部分，这把密钥也不能创建或修改账单。后续如何组织核对流程，见[通过 API 检查付款的指南](<https://cryptanio.com/zh/wiki/check-payment-api-without-webhook/>)。

如果请求失败，请检查项目、模式、IP、有效期和权限。不要因一次访问错误就判定未付款，也不要用账户通用密钥替换受限密钥。应根据[账单](<https://cryptanio.com/zh/wiki/shenme-shi-zhangdan/>)状态判断付款情况。

## 之后如何调整访问权限 {#section-48796000aeddaa08}

在现有密钥处点击“进入”，修改项目、API 部分、IP 或有效期，然后选择“保存访问权限”。模式在创建密钥时选定。“旋转”会更换秘密值并立即停用旧值；“释曰”会撤销密钥，停止其使用。更换之前，应准备好服务器客户端的更新，以免订单核对中断。

标签: [付款](https://cryptanio.com/zh/wiki/tag/payments/), [API](https://cryptanio.com/zh/wiki/tag/api/)

## 相关文章

- [什么是付款账单](https://cryptanio.com/zh/wiki/shenme-shi-zhangdan/)
- [如何不使用 webhook，通过 API 检查付款](https://cryptanio.com/zh/wiki/check-payment-api-without-webhook/)
- [如何在自己的网站接受 USDC 付款](https://cryptanio.com/zh/wiki/accept-usdc-payments-on-website/)