API 权限范围
一把 API Key 能调用哪些接口，由它持有的权限范围（scope）决定。建 Key 的步骤见用 API Key 调用接口。
登录界面的你始终拥有全部权限。权限范围只约束 API Key。
新建 API Key 时，「权限」按功能分组，每组分「读」「写」，短信与语音另有一档计费权限。默认勾选全部的「读」。
| 「权限」分组 | scope | 读能做的事 | 写能做的事 |
|---|---|---|---|
| 「设备」 | device:read / device:write |
设备列表与状态 | 改设备名称与本机号码、重新扫描设备、改设备接管清单、删除设备、设置呼叫转移等补充业务 |
| 「卡与 eSIM」 | card:read / card:write |
卡、eSIM Profile、卡策略 | 切换、下载、删除 eSIM Profile；切换卡槽；改卡策略、短信中心号码；管理读卡器 |
| 「网络（含换 IP）」 | network:read / network:write |
驻网状态、信号 | 换 IP、飞行模式、选网、IP 类型、发 USSD |
| 「代理」 | proxy:read / proxy:write |
代理实例、流量、节点 | 起停代理实例、改流量额度、改节点与订阅、改 VoWiFi 出口 |
| 「短信」 | sms:read / sms:write / sms:send |
短信与会话 | write：标已读、置顶、拦截规则、黄页标记，不花钱；send：发短信，会计费 |
| 「语音」 | voice:read / voice:write / voice:call |
通话记录、录音、转写 | write：录音与转写开关、删录音，不花钱；call：拨号、接听、挂断，会计费 |
| 「自动化」 | automation:read / automation:write |
脚本与运行历史 | 改脚本、手动运行脚本 |
| 「系统」 | system:read / system:write |
系统信息、监控指标、审计日志 | AI 服务设置、浏览器推送订阅、所在地区 |
- 有同组的「写」「发短信（计费）」或「打电话（计费）」，就自动有同组的「读」。
- 列表里带
sms:send或voice:call的 Key 会标「含计费」。 - 每个接口需要哪个 scope，写在「API 文档」里每个接口的说明中。
- 调用超出权限的接口返回 403，响应里写着需要哪个 scope。
只能在界面里做的操作
Section titled “只能在界面里做的操作”还有一档 admin，等于全部权限。新建界面不提供它。下面这些操作只给 admin，也就是只能由你登录后在界面里做：
| 类别 | 操作 |
|---|---|
| 账号与密钥 | 改登录口令、管理登录会话与锁定、身份验证器；新建、列出、吊销 API Key |
| 通知与两步验证 | 改通知渠道、发测试通知、改短信转发规则、改通知渠道验证码 |
| 底层硬件 | AT 命令、切换控制面、重启模组、改模组的底层配置、添加设备 |
| 日志与调试 | 读日志、开关调试域、原始信令抓取、改运营商参数 |
| 备份与数据 | 下载备份、恢复备份、改数据保留期限 |
| 下载与内核 | 改 GitHub 下载加速、安装和删除代理内核 |
| Linphone 接听 | SIP 网关的设置与配置链接 |
能改通知渠道就能把登录验证码和全部短信转走，所以它不归 system:write。
选权限的建议
Section titled “选权限的建议”只给这件事用得到的：
| 用途 | 勾选 |
|---|---|
| 只看状态、拉短信 | 保留默认的全部「读」 |
| 定时换 IP 的脚本 | 「网络（含换 IP）」的「写」 |
| 发验证码短信的服务 | 「短信」的「发短信（计费）」 |
| Prometheus 抓取指标 | 只要「系统」的「读」 |
会产生费用、作用到真实网络或不能撤销的接口，用 API Key 调用时必须再带两个请求头。在界面里做同样的操作时，确认框会替你带上。
| 请求头 | 填什么 | 不带或填错时 |
|---|---|---|
X-NSIM-Confirm |
被操作对象的标识符，例如设备 ID、ICCID。不能填 true |
返回 409，错误码 confirmation_required，响应里的 confirm_with 说明该填哪个标识符 |
Idempotency-Key |
每次操作一个新的唯一字符串，至少 8 个字符，例如 uuidgen 的输出 |
缺失返回 400 |
带同一个 Idempotency-Key 的重复请求不会再执行一次：
| 情况 | 结果 |
|---|---|
| 24 小时内同键、同请求 | 直接返回第一次的结果，并带响应头 Idempotency-Replayed: true |
| 同键、请求方法、路径或请求体不同 | 返回 422，错误码 idempotency_key_reused |
| 同键的上一次还在执行 | 返回 409，错误码 request_in_flight |
属于危险操作的有：
- 拨号、接听视频通话、发短信与彩信、群发、发起 USSD。
- 切换、下载、停用、删除 eSIM Profile；切换卡槽；改短信中心号码。
- 改卡策略，例如飞行模式、移动数据、VoLTE、VoWiFi 开关；选网。
- 重启模组、换 IP、切换控制面、发 AT 命令、删除设备、改设备接管清单。
- 设置呼叫转移、呼叫等待、呼叫限制。
- 永久删除短信、删除录音、删除自动化脚本、回滚脚本版本、手动运行脚本、删除节点与订阅。
- 吊销 API Key、恢复备份、改数据保留期限、删除代理内核。
完整清单以「API 文档」为准，每个危险接口的说明里都写着后果。
经 API Key 的写操作都记进审计日志，标明是哪把 Key，在「诊断 › 审计」里查看，见诊断页。