API 密钥

API 密钥是每个服务器到服务器 Liqfy 请求进行身份验证的方式。本页面面向为其账户管理密钥的仪表盘/管理员用户——如果您只需要使用密钥，请参阅快速入门。

#密钥格式

text

lq_live_<24-byte-base64url>      ← production
lq_test_<24-byte-base64url>      ← sandbox / test

明文仅在签发时显示一次。
服务器端仅保留 SHA-256 指纹和一个 12 个字符的前缀（例如 lq_live_xyz），用于在仪表盘中显示。
丢失了密钥？无法找回——请轮换以签发新密钥。

确切的前缀因品牌而异（此处为 lq_live_ / lq_test_）；通用的是格式 <prefix>_live_… / <prefix>_test_…。切勿在用于判断密钥类型的代码中硬编码前缀——官方 SDK 接受任何品牌的前缀，并提供 isTestKey 辅助函数，改为读取 _test_ 段。

#在 API 上使用密钥

对 /v1/* 的服务器到服务器调用在标准的 Authorization: Bearer 请求头中携带密钥：

text

Authorization: Bearer lq_live_...

旧版 apikey: lq_live_... 请求头出于兼容性仍被接受（网关会将 Bearer 改写为内部的 apikey 形式）。新集成应仅发送 Bearer，不发送其他请求头。如果请求同时携带两个请求头，将使用 Authorization: Bearer 中的密钥。缺失或无效的密钥返回 401。

网关在每次请求时通过检查密钥是否以该品牌的测试前缀（lq_test_）开头，来判断它是测试密钥还是正式密钥。任何不以测试前缀开头的密钥都被视为**正式（live）**密钥。客户端无法通过发送自己的模式请求头来强制路由到沙盒——网关始终会根据密钥覆盖该请求头。

同一密钥还可解锁位于 /docs/payments 和 /docs/webhooks 的 OpenAPI 门户；没有密钥时，它们会像其他受保护路由一样返回 401。

密钥认证路由上的速率限制按账户（密钥背后的网关 consumer）计数，而非按 IP 计数，因此同一账户的所有密钥共享同一配额。响应中会提供 X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset 和 Retry-After，以便您进行退避。

切勿记录密钥。 不要记录在应用日志、CI 输出或错误报告中——明文就是凭据本身，指纹的存在正是为了让您在讨论某个密钥时无需引用其明文。

#IP 允许列表

账户可以将 API 密钥流量限制在一组 CIDR 范围内。在该防护所覆盖的路由上，来自列表之外地址的请求会在路由执行前被拒绝并返回 403——其 permission_error 信封格式与错误相同，且问题并不在于密钥本身。

范围： 允许列表在核心账户路由上强制执行——钱包、提现、交易、MED 案例、api-keys 和 neighbours。资金流转路由 /v1/charges、/v1/pix/charges、/v1/payments 和 /v1/webhooks 不受每账户允许列表覆盖（网关的 ip-restriction 仅保护 /v1/admin）。

请包含您的集成所使用的每个出口地址：生产服务器、CI 运行器、故障转移主机以及您云区域的 NAT 地址。此处条目错误会以失败关闭（fail closed）方式处理——请求永远不会到达密钥检查，因此“密钥有效，但仍返回 403”的报告通常是允许列表导致的。

如需添加、更改或删除范围，请联系支持团队（suporte@liqfy.com.br）；该列表按账户维护。

#认证——这些端点使用 JWT，而非 API 密钥

所有 /v1/api-keys/* 端点均为 JWT 认证（即 POST /v1/auth/login 返回的同一仪表盘登录令牌）。它们不受 Kong 的 apikey 插件管控——否则会陷入先有鸡还是先有蛋的问题。

text

Authorization: Bearer <dashboard JWT>

JWT 中的账户声明（claim）限定了每项操作的范围——您只能管理自己账户的密钥。

权限： 账户的任何活跃成员都可以列出密钥。签发、轮换和吊销需要账户的 OWNER 或 ADMIN 角色；其他任何角色都会收到 403，错误码为 API_KEY_ROLE_REQUIRED。

#端点

#签发密钥

text

POST /v1/api-keys

bash

curl -X POST https://api.liqfy.com.br/v1/api-keys \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{ "label": "production-backend", "test": false }'

字段	类型	必填	说明
`label`	string	否	自由格式，≤ 64 个字符。在仪表盘中供人工查看。
`test`	boolean	否	`true` 时签发 `lq_test_…` 密钥。默认为 `false`。

响应 201 Created

json

{
  "id": "5b3a9c1d-...",
  "apiKey": "lq_live_F8A2K7M3N9PQRSTUVWXYZAB",
  "fingerprint": "9a3f7e1c5d8b2a40",
  "prefix": "lq_live_F8A",
  "label": "production-backend",
  "createdAt": "2026-04-25T18:32:11.000Z",
  "mode": "live"
}

mode 表示密钥的环境：test（沙盒，扣款永远不会到达真实的提供商）或 live。这与网关用于路由扣款的规则相同；请读取此字段，而不是比较前缀。

apiKey 仅在此处显示。 请立即将其存储在密钥管理器中。仪表盘在后续加载时不会再显示它。

#列出您的密钥

text

GET /v1/api-keys

仅返回元数据——不包含明文。

json

{
  "data": [
    {
      "id": "5b3a9c1d-...",
      "prefix": "lq_live_F8A",
      "label": "production-backend",
      "createdAt": "2026-04-25T18:32:11.000Z",
      "mode": "live"
    },
    {
      "id": "7f1c4e9a-...",
      "prefix": "lq_test_QRX",
      "label": "ci-tests",
      "createdAt": "2026-04-12T09:14:08.000Z",
      "mode": "test"
    }
  ],
  "access": { "canManage": true }
}

access.canManage 表示调用者是否可以签发、轮换和吊销密钥（账户所有者或管理员）。

#轮换密钥

text

POST /v1/api-keys/{id}/rotate

以原子方式吊销指定的密钥并签发一个新密钥。请定期使用（每 90 天一次较为合理），或在怀疑密钥泄露时使用。

bash

curl -X POST https://api.liqfy.com.br/v1/api-keys/5b3a9c1d-.../rotate \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{ "label": "production-backend (rotated 2026-04-25)" }'

响应结构与签发密钥完全相同——包括新的明文。

新密钥沿用旧密钥的环境：轮换测试密钥会签发另一个测试密钥，轮换正式密钥会签发另一个正式密钥。标签也会保留，除非您发送新的 label。不属于您账户的 id 会返回 404，且不会吊销任何密钥。

运维提示： 此调用完成的那一刻，旧密钥即停止工作。请在调用轮换之前将新密钥部署到您的服务器，或者先签发一个并行密钥以安排短暂的重叠期，待新密钥就位后再吊销旧密钥。

#吊销密钥

text

DELETE /v1/api-keys/{id}

永久生效——无法撤销。

bash

curl -X DELETE https://api.liqfy.com.br/v1/api-keys/5b3a9c1d-... \
  -H "Authorization: Bearer $JWT"

响应 200 OK

json

{ "revoked": true }

#安全检查清单

像对待密码一样对待 lq_live_…——切勿提交到代码库、切勿记录到日志、切勿粘贴到 Slack 中。
存储在密钥管理器中（1Password、Vault、AWS Secrets Manager、GitHub Actions secrets 等）。
每个环境使用不同的密钥（生产环境使用 lq_live_…，预发布/CI 使用 lq_test_…）。
每个服务一个密钥 / 每台开发者机器一个密钥——发生泄露时更容易吊销单个密钥。
按计划轮换。至少每季度一次；高敏感度工作负载每月一次。
员工离职时立即吊销。
为仪表盘的“密钥已签发”/“密钥已轮换”审计事件设置告警。

#各项数据的存储位置

存储位置	存储内容
Kong（`key-auth` 插件）	明文密钥——用于认证入站请求。
Liqfy 数据库（商户记录）	`kongConsumerUsername`——商户 slug，用于反向查找。绝不存储明文。
审计日志	签发/轮换/吊销事件，包含签发用户的 ID 和密钥指纹。
仪表盘	仅前缀 + 标签。

#CLI 替代方案

对于在工作站上进行的运维/入驻操作，可以通过内部配置 CLI 执行相同的操作（仅限运维的工具；不属于公共 API 或 SDK）。该 CLI 直接与 Kong Admin API 通信，其签发的密钥与通过 HTTP 签发的密钥可互换使用。

#常见问题

问：我可以同时拥有多个正式密钥吗？ 答：可以——这对于零停机轮换和按服务隔离很有用。没有硬性上限。请注意，同一账户的所有密钥共享该账户的速率限制配额。

问：创建后我立即丢失了明文。 答：它已无法找回。请轮换（或吊销后重新签发）——按设计不提供任何找回途径。

问：如何判断哪个密钥发出了哪个请求？ 答：仪表盘的请求日志会在每次调用中显示密钥指纹。按 apiKeyFingerprint 筛选即可归因流量。

问：我可以将密钥限制为仅访问某些端点/方法吗？ 答：暂不支持。按密钥划分的权限范围已列入第二阶段路线图。目前，每个密钥都拥有完整的账户访问权限。