> ## 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 密钥 > 新建」页，全屏表单，按填写密钥名称 → 可选 IP 白名单 → 勾选读/写权限范围的顺序创建一把新的 API 密钥；创建成功后一次性显示私钥。编辑已有密钥（改名称/IP/权限）走同版式页面。

## 这是什么

这是商户后台「**开发者**」模块下「**API 密钥**」页面的**创建密钥流程页**（页面标题「创建 API 密钥」）。从 API 密钥列表页右上角点「**创建 API 密钥**」进入，是一个全屏表单：左侧填「**密钥详情**」（密钥名称、IP 白名单），右侧勾选「**权限范围**」（每类资源的读取 / 写入权限），底部点「创建」完成。API 密钥用于以程序方式（服务器对服务器）调用 UQPAY 接口，任何持有该密钥的人都能在你授予的权限范围内调用你的 API。想新建一把密钥、或**编辑**已有密钥的名称 / IP 白名单 / 权限时，都在这一版式页面操作。

## 操作步骤

**创建一把新密钥：**

1. 左侧导航进入「**开发者**」，打开「**API 密钥**」页。
2. 点右上角「**创建 API 密钥**」，进入全屏创建页。
3. 填「**密钥名称**」（必填）：给密钥起一个便于识别的名称（例如「生产 API 密钥」）。
4. （可选）填「**IP 白名单**」：限制只有来自指定 IP 的调用才被接受。输入一个 IPv4 或 IPv6 地址（可带 CIDR 掩码，如 `10.0.0.0/24`、`2001:db8::/32`），按**回车**或**逗号**添加，也可直接**粘贴**一批一次性加入；输入时会弹出常用网段建议，用 ↑↓ 选、回车确认。已添加的会以标签形式显示，点标签上的「×」移除。留空则不限制来源 IP。
5. 在右侧「**权限范围**」区，为这把密钥勾选所需权限。权限按资源分组展示，每个资源一行、右侧有「**读取**」和「**写入**」两个勾选框：只读选「读取」，需要写操作则勾「写入」（勾「写入」会自动一并勾上「读取」）。可用分组顶部的列勾选框一键「全部只读 / 全部读写」，或用整个资源组的「全选…」批量勾选；也可用右上角「**全选**」/「**全部清除**」对整页批量操作。**至少要选一个权限**，否则无法创建。
6. 核对无误后点底部「**创建**」。若一个权限都没选，会提示「请至少选择一个权限。」；名称为空会提示补填。
7. 创建过程中系统可能要求**二次验证**（输入账户密码，或验证器验证码 / passkey），按弹窗完成即可。
8. 创建成功后进入密钥展示页，显示提示「API 密钥已创建」，并给出这把密钥的**私钥**。点眼睛图标可显示 / 隐藏明文，点复制按钮复制。**私钥仅此一次显示**，请立即复制并妥善保存，随后点「**完成，我已保存密钥**」返回列表。

**编辑一把已有密钥：**

1. 在 API 密钥列表页，点该密钥所在行末尾的「**⋯**」菜单 →「**编辑 API 密钥**」，进入同版式的编辑页。
2. 编辑页左侧顶部会显示该密钥的「**客户端 ID**」（只读，不可修改），下方可改「密钥名称」「IP 白名单」，右侧可改「权限范围」。
3. 改完点底部「**保存更改**」。编辑同样可能触发二次验证。编辑**不会**重新生成私钥（保存成功不会再显示密钥）。

## 字段与状态含义

**密钥详情（左栏）：**

| 字段     | 含义（商户视角）         | 备注                                    |
| ------ | ---------------- | ------------------------------------- |
| 密钥名称   | 这把密钥的识别名称        | 必填                                    |
| IP 白名单 | 允许调用该密钥的来源 IP 列表 | 支持 IPv4 / IPv6，可带 CIDR 掩码；留空则不限制来源 IP |
| 客户端 ID | 密钥的客户端标识（仅编辑页显示） | 只读，不可修改                               |

**权限范围（右栏）：** 按资源分组，每个资源可分别授予「**读取**」（只读）与「**写入**」（写操作）权限。只授予该密钥真正需要的权限即可，之后仍可在编辑页调整。相关操作项：

| 界面项                 | 含义                                  |
| ------------------- | ----------------------------------- |
| 读取 / 写入             | 单个资源的只读 / 写权限勾选框；勾「写入」会自动连带勾上「读取」   |
| 全部只读 / 全部读写         | 对某一资源组的整列一键勾选                       |
| 全选（分组内）             | 勾选某一资源组的全部读写权限                      |
| 全选 / 全部清除（页面右上）     | 对整页全部权限一键勾选 / 清空                    |
| 查看 API 文档 / 查看覆盖的接口 | 打开该资源对应的接口文档、或查看该权限覆盖哪些接口，便于确认要授予什么 |

> 底部会实时显示当前密钥名称与「N 个权限已选」。

**私钥展示（创建成功后）：** 显示这把密钥的完整私钥字符串，仅显示一次，页面提示「此密钥仅显示一次」「请妥善保存。关闭此对话框后您将无法再次查看。」

## 边界与常见处理

* **看不到「创建 API 密钥」入口**：一是你的账户没有 API 密钥写权限，需让管理员分配；二是账户尚未开通 OpenAPI 接口能力（未激活），此时入口不显示，需联系客户经理 / 管理员开通后再创建。
* **点「创建」提示"请至少选择一个权限"**：右侧「权限范围」里一个都没勾，至少勾选一个资源的读取或写入再提交。
* **IP 填不进去 / 提示「无效的 IP 地址」**：只接受合法的 IPv4 或 IPv6（可带 CIDR，如 `10.0.0.0/24`、`2001:db8::/32`）；检查格式后重试。
* **提示「IP 已添加」**：该 IP 已在白名单里，无需重复添加。
* **白名单填了 `0.0.0.0/0` 或 `::/0`**：等于允许任意来源 IP 调用，页面会给出英文安全提示「This key will accept calls from any IP」（该密钥将接受来自任意 IP 的调用），仅建议短期测试时使用，正式环境请收窄到你的服务器 IP。
* **私钥没来得及复制 / 忘了保存**：私钥只在创建成功时显示一次，之后无法再查看，也不能在编辑里重新生成；只能删除这把密钥后重新创建一把。
* **创建 / 保存时弹出要输密码或验证码**：这是创建 / 修改密钥的二次验证，按提示输入账户密码或验证器验证码 / passkey 即可继续；中途关闭弹窗则本次操作取消，不算失败。
* **编辑页一进去就跳回了列表**：编辑需要从列表的「⋯」菜单进入以带上目标密钥；直接刷新或用链接进入会因缺少上下文自动返回列表，请回列表用「编辑 API 密钥」重新进入。

## 常见问法（Q→A）

* **Q：怎么创建一把 API 密钥？** A：开发者 > API 密钥 > 右上角「创建 API 密钥」，填名称 →（可选）填 IP 白名单 → 勾选读/写权限 → 点「创建」，成功后立即复制显示的私钥。
* **Q：创建密钥必须填什么？** A：密钥名称必填、且至少选一个权限；IP 白名单可选。
* **Q：IP 白名单怎么填？必须填吗？** A：非必填。填一个或多个 IPv4/IPv6 地址（可带 CIDR 掩码，如 `10.0.0.0/24`、`2001:db8::/32`），回车或逗号添加，也可粘贴一批；留空则不限制来源 IP。
* **Q：权限范围怎么选？读取和写入有什么区别？** A：按资源逐项勾选，「读取」是只读、「写入」是写操作；勾「写入」会自动带上「读取」。只授予密钥需要的最小权限即可。
* **Q：创建后私钥在哪看？能再看一次吗？** A：创建成功页会显示完整私钥，仅显示一次，务必当场复制保存；关闭后无法再查看，也不能重新生成，遗失只能删除后重建。
* **Q：怎么修改已有密钥的名称 / IP / 权限？** A：在列表该行「⋯」菜单选「编辑 API 密钥」，在编辑页改名称、IP 白名单或权限范围后点「保存更改」。
* **Q：编辑密钥会换新的私钥吗？** A：不会。编辑只改名称 / IP / 权限，不会重新生成私钥。
* **Q：客户端 ID 能改吗？** A：不能，客户端 ID 只读，只在编辑页展示，用于确认你改的是哪一把密钥。
* **Q：为什么我看不到「创建 API 密钥」按钮？** A：多为没有 API 密钥写权限，或账户还没开通 OpenAPI 接口能力；请联系管理员分配权限或开通接口能力。
* **Q：创建时为什么让我再输一次密码 / 验证码？** A：这是创建密钥的二次验证，按弹窗输入账户密码或验证器验证码 / passkey 即可。
* **Q：把 IP 白名单填成 0.0.0.0/0 有风险吗？** A：等于允许任意 IP 调用，页面会提示仅建议短期测试；正式使用请把白名单收窄到你的服务器 IP。
* **Q：一把密钥能调哪些接口 / 覆盖哪些权限？** A：在权限范围里点资源旁的信息图标可「查看覆盖的接口」，或点「查看 API 文档」查阅对应接口文档。