API 令牌
API 令牌让程序可以使用面板的 API：你的计费脚本、机器人、监控任务。每个令牌以一个管理员账户的身份行事，权限永远不会超出该账户。本页位于 访问控制 → API 令牌，对主管理员开放。
令牌受哪些限制
令牌从三个方面被收窄，每次请求都会重新检查：
- 身份：令牌绑定的管理员。令牌能看到该管理员能看到的内容。绑定到代理商的令牌只能看到该代理商的用户，并消耗它的配额。删除该管理员会同时删除令牌。
- 角色：令牌所处的层级，永远不高于其管理员的层级。管理员被降级时，令牌也随之降级。
- 作用域：令牌在该角色内可以访问的路由，并与其管理员角色的权限取交集。收窄管理员的角色会立即收窄绑定到它的所有令牌，无需重新签发。
以上任何修改都会在令牌的下一次请求时生效。
创建令牌
- 点击 添加。
- 说明：令牌的用途，方便以后辨认。
- 身份：令牌获得其权限的管理员。
- 角色：层级，最高不超过该管理员的层级。
- 作用域：保持 不限制 即可访问角色所能访问的所有路由（包括以后版本新增的作用域），或取消勾选后自行选择。
- 插件标识：普通集成请留空。它用于属于某个手动添加的插件的令牌（参见 扩展页面）。
- 每分钟请求数：
0表示使用面板默认值 120。 - 有效期（天）：
0表示永不过期。 - 点击 保存。
随后面板会 只显示一次 令牌。请在关闭对话框之前复制它：面板只保存其哈希值，因此无法再次显示。丢失的令牌只能删除并重新创建。
TIP
如果你的账户开启了两步验证，当你上一次输入验证码已超过十分钟时，创建或删除令牌都会再次要求输入验证码。
每次请求都要带上令牌：
curl -H "Authorization: Bearer $NEXORA_TOKEN" \
https://panel.example.com/your-base-path/api/v1/me/api/v1/me 会返回令牌代表哪个管理员，以及它拥有哪些作用域。
作用域
:write 作用域包含对应的 :read。面板表单中显示的是第二列的名称；API 和 API 文档使用第一列的名称。
| 作用域 | 显示为 |
|---|---|
users:read | 查看用户 |
users:write | 创建与编辑用户 |
nodes:read | 查看节点 |
nodes:write | 配置节点 |
tunnels:read | 查看隧道 |
tunnels:write | 配置隧道 |
nodes:install | 通过 SSH 安装节点 |
templates:read | 查看模板 |
templates:write | 编辑模板 |
pool:read | 查看入站、出站与规则集 |
pool:write | 编辑入站、出站与规则集 |
certificates:read | 查看证书 |
certificates:write | 签发与编辑证书 |
settings:read | 查看设置 |
settings:write | 修改设置 |
stats:read | 流量、报表与健康状态 |
tools:write | 密钥生成工具 |
admins:write | 管理操作员与角色 |
tokens:write | 管理 API 令牌 |
license:write | 管理许可证 |
backup:read | 下载备份 |
backup:write | 创建与删除备份 |
backup:deliver | 向备份聊天发送文件 |
security:read | 查看封禁列表 |
security:write | 修改封禁列表 |
webhooks:read | 查看事件订阅者 |
webhooks:write | 修改事件订阅者 |
services:read | 查看面板服务 |
services:write | 配置和测试面板服务 |
只授予程序所需的最少权限。有三个作用域属于面板自身的管理：admins:write、tokens:write 和 license:write。除非程序确实需要，否则不要授予；没有它们的令牌无法创建账户，也无法签发新令牌，因此即使泄露，也无法让自己永久存在。backup:read 可以读出包含所有凭据的整个数据库，nodes:install 能以 root 身份登录你的服务器，因此这两个作用域同样需要谨慎对待。
有几个路由对所有令牌关闭，无论其作用域如何：修改调用者自己的密码、其仪表盘布局、重启面板、面板更新以及还原备份。另有几个路由对所有令牌开放：/api/v1/me、作用域列表和事件目录。
速率限制
每个令牌每分钟有一定的请求额度（除非你另行设置，否则为 120）。每个响应都带有 X-RateLimit-Limit、X-RateLimit-Remaining 和 X-RateLimit-Reset。超出额度的请求会得到 429 和 Retry-After；请等待相应的秒数后再发送下一个请求。
列表
| 列 | |
|---|---|
| 说明 | 令牌由插件持有时带有 扩展：名称 标签 |
| 身份 | 令牌绑定的管理员 |
| 角色 | 它的层级 |
| 作用域 | 不限制，或作用域的数量（指向它可查看列表） |
| 最近使用 | 最近一次使用的时间；指向它可查看请求来源地址 |
| 到期时间 | 到期日期，或永不过期 |
令牌创建后不能编辑：请删除它并重新创建。由插件持有的令牌不能在这里删除；它随插件一起在 扩展页面 页面上修改或移除。
API
本页顶部的 API 文档 会打开本安装的 API 参考，其中已填入你自己的地址：每个路由、它所需的作用域、列表与分页、使用 Idempotency-Key 的重试，以及状态码。同样的内容也在 API 参考 中。
请基于 /api/v1 前缀进行开发。它是稳定的公开接口。不带版本的 /api 前缀属于面板界面自身，可能随界面一起变化。
相关页面
- 管理员 和 角色：令牌所属管理员可以做什么。
- Webhook 与事件：接收事件，而不是轮询。
- API 参考：API 参考。
- 审计日志：令牌修改了什么。