> ## Documentation Index
> Fetch the complete documentation index at: https://developers.uqpay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API 密钥

> 商户后台「开发者 > API 密钥」页，查看、搜索、创建、编辑与删除用于程序化访问接口的 API 密钥，并为每把密钥设置名称、IP 白名单和权限范围。

## 这是什么

这是商户后台「**开发者**」模块下的「**API 密钥**」页面（左侧导航「开发者」→「API 密钥」，页面副标题「管理用于程序化访问的 API 密钥」）。API 密钥用于让你的系统以程序方式调用 UQPAY 接口。你在这里查看名下所有密钥、按名称或状态筛选，创建新密钥、编辑已有密钥（改名称、IP 白名单、权限范围）以及删除密钥。想接入接口、管理调用凭证、限制某把密钥的来源 IP 或权限时都从这里操作。页面右上角有「**接口文档**」链接，跳转到创建 API 密钥的接入指南。

## 操作步骤

进入并查看密钥列表：

1. 左侧导航点击「**开发者**」→「**API 密钥**」。
2. 列表展示名下所有密钥；用「**API 密钥名称**」搜索框按名称查找，用「**按状态筛选**」下拉按状态（所有状态 / 已启用 / 已禁用）缩小范围。已生效的筛选会在「筛选条件」区以标签显示，点标签上的「×」移除单项，或点「**全部清除**」清空。

创建一把新密钥：点右上角「**创建 API 密钥**」进入创建流程——填密钥名称、IP 白名单，勾选权限范围，提交后系统一次性展示私钥。完整步骤见\*\*「新建 API 密钥」页\*\*。

编辑一把密钥：

1. 在目标密钥所在行末尾点「**⋯**」菜单 →「**编辑 API 密钥**」，进入全屏编辑页。
2. 页面左侧显示只读的「**客户端 ID**」，可修改「**密钥名称**」和「**IP 白名单**」；右侧「**权限范围**」矩阵可勾选/取消该密钥的读取、写入权限。
3. 改好后点右下角「**保存更改**」。编辑操作**不会更换私钥**（私钥保持不变）。

删除一把密钥：

1. 在目标密钥所在行「**⋯**」菜单 →「**删除 API 密钥**」。
2. 弹窗二次确认（显示密钥名称、提示「此操作无法撤销」），点「**删除**」确认。

复制客户端 ID：列表「客户端 ID」列旁有复制按钮，点一下即复制完整 ID。

## 字段与状态含义

**列表列：**

| 列      | 含义（商户视角）                                    | 备注                |
| ------ | ------------------------------------------- | ----------------- |
| 名称     | 创建时给密钥起的名称                                  |                   |
| 客户端 ID | 密钥的公开标识（Client ID），调用接口时用                   | 行内有复制按钮           |
| IP 白名单 | 允许使用该密钥调用接口的来源 IP；多个时列表显示第一个并以「+N」折叠，悬停可看全部 | 为空显示「—」表示不限制来源 IP |
| 状态     | 密钥当前状态，见下                                   |                   |
| 创建时间   | 密钥创建日期时间                                    |                   |
| 最后更新   | 密钥最近一次修改时间                                  |                   |

**状态：**

| 状态  | 含义           |
| --- | ------------ |
| 已启用 | 密钥有效，可正常调用接口 |
| 已禁用 | 密钥被停用，暂不可调用  |

**IP 白名单**：可填 IPv4 或 IPv6 地址，支持带 CIDR 网段（如 `10.0.0.0/24`、`2001:db8::/32`）。在输入框回车或逗号即添加一条，可添加多条。留空表示不限制来源 IP；若填入代表「任意 IP」的开放网段（`0.0.0.0/0` 或 `::/0`），页面会提示该密钥将接受来自任意 IP 的调用，仅建议短期测试使用，正式环境请收窄到你的服务器 IP。

**权限范围（Scope）**：每把密钥可按资源分类授予权限，每类资源分「**读取**」与「**写入**」两种，可逐项勾选，也可按整类或按列（全部只读 / 全部读写）批量勾选。勾选「写入」会自动带上对应「读取」。创建或编辑时**至少要选择一个权限**，否则无法提交。密钥只能在被授予的权限范围内调用接口。

**客户端 ID 与私钥的区别**：客户端 ID 是公开标识，列表里始终可见、可复制；**私钥（密钥本体）只在创建成功时展示一次**，关闭后无法再次查看，需当场妥善保存。请像对待密码一样保管私钥，存放在密钥管理工具中、切勿提交到代码仓库，一旦泄露应立即删除该密钥并重建。

## 边界与常见处理

* **看不到「创建 API 密钥」按钮**：一是你的账号没有开发者密钥的写入权限，需让管理员分配；二是账户尚未开通 API 访问功能，需联系管理员或客户经理开通后入口才会出现。
* **看不到行末「⋯」菜单（无法编辑/删除）**：当前账号没有 API 密钥的写入权限，只能查看，需让管理员分配相应权限。
* **列表显示「暂无 API 密钥」**：账户下还没有任何密钥，提示「创建您的第一个 API 密钥以开始使用」，点「创建 API 密钥」新建。
* **筛选后「没有 API 密钥符合您的筛选条件」**：当前搜索/状态筛选没有匹配项，点「清除筛选」或「全部清除」再看。
* **私钥忘记保存 / 丢了**：私钥只在创建时展示一次，无法找回；删除该密钥后重新创建一把即可。
* **创建或编辑时被要求再次验证身份**：创建、编辑密钥属敏感操作，系统可能弹出二次验证（输入账户密码 / 验证码等），通过后操作才会生效。
* **想限制某把密钥只能从固定 IP 调用**：编辑该密钥，在「IP 白名单」填入允许的服务器 IP（可带网段），保存即可。
* **改了名称/IP/权限但私钥没变**：编辑不会更换私钥，只有删除重建才会得到新私钥。

## 常见问法（Q→A）

* **Q：API 密钥在哪里管理 / 在哪里看？** A：左侧「开发者」→「API 密钥」，列表即名下全部密钥。
* **Q：怎么创建一把 API 密钥？** A：在 API 密钥页右上角点「创建 API 密钥」，填名称、IP 白名单、勾选权限范围后提交，系统会一次性展示私钥，详见「新建 API 密钥」页。
* **Q：为什么我看不到「创建 API 密钥」按钮？** A：多为没有开发者密钥写入权限，或账户还没开通 API 访问功能；前者找管理员分配权限，后者联系管理员/客户经理开通。
* **Q：私钥忘了保存怎么办 / 能再看一次吗？** A：私钥只在创建时显示一次，关闭后无法再查看，也无法找回；删掉这把密钥重新创建即可。
* **Q：客户端 ID 和私钥有什么区别？** A：客户端 ID 是公开标识，列表里随时可见可复制；私钥是调用凭证，仅创建时展示一次，需当场保存并妥善保管。
* **Q：怎么限制某把密钥只能从我们服务器 IP 调用？** A：编辑该密钥，在「IP 白名单」里填允许的 IP（支持 CIDR 网段），保存即可；留空表示不限制来源 IP。
* **Q：IP 白名单填 0.0.0.0/0 是什么意思？** A：代表允许任意 IP 使用该密钥，风险较高，仅建议短期测试；正式使用请收窄到你的服务器 IP。
* **Q：什么是权限范围 / 怎么控制一把密钥能调哪些接口？** A：创建或编辑时在「权限范围」矩阵按资源勾选读取/写入权限，密钥只能在被授予的范围内调用，至少要选一个权限。
* **Q：怎么编辑一把密钥？改名称会换私钥吗？** A：在该密钥「⋯」菜单选「编辑 API 密钥」，可改名称、IP 白名单、权限范围；编辑不会更换私钥。
* **Q：怎么删除 / 停用一把密钥？** A：在该密钥「⋯」菜单选「删除 API 密钥」并确认即可删除（不可撤销）。
* **Q：密钥状态「已启用」「已禁用」是什么意思？** A：已启用表示密钥有效可调用，已禁用表示被停用暂不可调用。
* **Q：创建密钥时为什么让我再输一次密码 / 验证码？** A：这是敏感操作的二次身份验证，输入后即可继续创建。
* **Q：密钥泄露了怎么办？** A：立即在列表里删除该密钥，再重新创建一把新的，并更新你系统里使用的凭证。