# BTCPay 2.4.4后：核旧API、Key ID与权限迁移

整理：链小知（AI 辅助）
资料核对日期：2026-10-14
引用地址：https://lianxiaozhi.com/tools/guides/btcpay-244-greenfield-key-id-permission-check
难度：进阶
核验方式：官方文档整理，未执行真实账户操作

检查已有集成是否仍依赖被移除的旧密钥或通知字段，不重新申请或操作账户。

## 使用工具
- [BTCPay Server](https://lianxiaozhi.com/tools/btcpay-server) · [官方入口](https://btcpayserver.org/)

## 前置条件
- 准备已有且脱敏的订单、请求或回执记录；没有实际记录时仅按文档列出待核字段。
- 本教程依据公开资料，不登录、申请密钥、调用业务API、创建收款或执行退款。

## 1. 固定实例版本和集成方式

从已有实例信息确认是否为2.4.4或之后，再对照集成的API类型。2.4.4官方release移除旧BitPay Basic-auth API keys；这属于BTCPay兼容接口变更，不表示BitPay商户产品停用。

已有Greenfield集成与旧BitPay式集成分别记录。WHMCS在2.4.4需插件v4.0.0及新Greenfield配置；本文只列缺口，不安装或更换密钥。

核对结果：实例版本、接口类型和插件版本有证据；未知不算已迁移。
依据：[BTCPay Server v2.4.4：Key ID、权限与通知URL变更](https://github.com/btcpayserver/btcpayserver/releases/tag/v2.4.4)
依据：[BTCPay Server 2.4.4：发布正文与集成破坏性变更](https://blog.btcpayserver.org/btcpay-server-2-4-4/)

## 2. 区分认证secret与撤销ID

当前Greenfield schema的ApiKeyData区分id与apiKey：认证头使用Authorization: token {token}；撤销路径/api/v1/api-keys/{apiKeyId}使用id，2.4.4不再用secret作撤销标识。

created为Unix时间，旧于2.4.4的密钥可为null；缺创建时间不表示新生成。只核脱敏字段名，任何实际secret不写入审计表；本文不执行DELETE或生成密钥。

核对结果：认证字段与apiKeyId分列，旧created为空保留原含义。
依据：[BTCPay Greenfield v1官方schema：ApiKeyData、认证与权限](https://docs.btcpayserver.org/API/Greenfield/v1/swagger.json)
依据：[BTCPay Server v2.4.4：Key ID、权限与通知URL变更](https://github.com/btcpayserver/btcpayserver/releases/tag/v2.4.4)

## 3. 核读取和修改状态的权限

API Key只能限制所属用户已有权限，不能扩大用户角色。权限可按storeId限定；读取发票对应btcpay.store.canviewinvoices，修改发票状态对应btcpay.store.canmanageinvoicestatus。

2.4.4修正修改状态所需权限，并阻止受限key创建unrestricted key。不要因读取成功就推断拥有改状态权限，也不为排错申请unrestricted权限。

核对结果：用户角色、store作用域及读/改权限分别有证据。
依据：[BTCPay Greenfield v1官方schema：ApiKeyData、认证与权限](https://docs.btcpayserver.org/API/Greenfield/v1/swagger.json)
依据：[BTCPay Server v2.4.4：Key ID、权限与通知URL变更](https://github.com/btcpayserver/btcpayserver/releases/tag/v2.4.4)

## 4. 检查回调入口而非猜付款丢失

2.4.4 Point of Sale移除每请求notificationUrl，发票使用app配置的通知URL。已有POS请求仍传此字段时，核app配置和回调记录，不能沿用旧参数判断新通知地址。

此变更是POS通知入口，不是所有Greenfield Webhook停用。回调缺失与发票链上付款状态分别核对；无法取得实际配置时交实例维护者继续确认。

核对结果：旧请求字段、app通知配置与发票状态分别记录。
依据：[BTCPay Server 2.4.4：发布正文与集成破坏性变更](https://blog.btcpayserver.org/btcpay-server-2-4-4/)
依据：[BTCPay Server v2.4.4：Key ID、权限与通知URL变更](https://github.com/btcpayserver/btcpayserver/releases/tag/v2.4.4)

## 常见错误
- 发布文档中的Lightning外部访问恢复是当时计划，本文不提供开启路由步骤。
- 不调用身份/业务接口，不撤销密钥、不修改发票状态，也不以版本号证明部署安全。

## 完成检查
- 形成订单、资源ID、金额、状态与未验证项的对照；保留失败原文。

## 相关知识

## 官方依据
- [BTCPay Server v2.4.4：Key ID、权限与通知URL变更](https://github.com/btcpayserver/btcpayserver/releases/tag/v2.4.4)
- [BTCPay Server 2.4.4：发布正文与集成破坏性变更](https://blog.btcpayserver.org/btcpay-server-2-4-4/)
- [BTCPay Greenfield v1官方schema：ApiKeyData、认证与权限](https://docs.btcpayserver.org/API/Greenfield/v1/swagger.json)