管理者

本页给负责发放密钥的管理者。管理功能仍使用 /v1 端点；v1 数据 API 停用后，这些端点仍然可用。

权限如何运作

名词	说明
帐号（principal）	一个人或一个系统。它有一份 grant（权限上限），可选择指定用量政策
权限上限（grant）	帐号最多能拥有的数据范围、管理权限与授权
密钥（key）	属于某个帐号，有自己的数据范围与管理权限，必须在帐号的 grant 之内。一个帐号可以有多把密钥，例如本人一把、agent 一把
生效权限	密钥范围与帐号 grant 的交集。请求只要超出其中一边，整个请求都会被拒绝

管理者只能管理权限不超过自己的帐号与密钥，也不能发出比自己更大的权限。

数据范围

字段	类型	说明
`kinds`	string[]	数据种类，例如 `["book_snapshot"]`
`reference`	bool	参考数据
`venues`、`all_venues`	string[]、bool	交易所，或全部
`instruments`、`all_instruments`	int[]、bool	商品编号，或全部
`time`	`{start, end}`	事件时间范围；省略表示不限
`history`	bool	历史读取与导出
`live`	bool	实时订阅
`book_depth`、`all_book_depth`	int、bool	盘口档数，或全部
`export`	bool	创建导出

venues 与 instruments 会保存，但尚未套用到 /v2 请求；目前请用 kinds、history、live、export 与盘口档数控制访问。

管理权限

管理权限	允许的操作
`admin.principals`	创建帐号，修改 grant 与用量政策
`admin.keys`	发行、列出、查看、撤销与轮替密钥；修改密钥的范围与到期日
`admin.quota`	创建与修改用量政策；指定帐号的政策
`admin.data`	数据管理、推导与实时 K 线工作
`admin.reference`	参考数据与 K 线规格

管理权限只给管理者。一般用户的 grant 不包含任何管理权限。

添加用户

ADMIN='vmk_...'
API=https://data.cyberun.cloud
H=(-H "Authorization: Bearer $ADMIN" -H "Content-Type: application/json")

# 1. Optional: a usage policy shared by several principals
curl -s "${H[@]}" $API/v2/admin/quota/policies -d '{
  "name": "trader", "requests_per_min": 600, "output_bytes_per_min": 536870912,
  "jobs_per_hour": 20, "concurrency": 4,
  "subscriptions": 4, "event_bytes_per_min": 16777216, "scanned_bytes_per_min": 1073741824}'
# -> {"id": "<policy-id>"}

# 2. Principal: grant is the ceiling; normal users get no capabilities
curl -s "${H[@]}" $API/v2/admin/principals -d '{
  "name": "trader-alice",
  "grant": {"data": {"kinds": ["book_snapshot"], "reference": true,
                     "all_venues": true, "all_instruments": true,
                     "history": true, "live": true, "export": true,
                     "all_book_depth": true},
            "caps": []},
  "policy": "<policy-id>"}'
# -> {"id": "<principal-id>"}

# 3. Key: the secret appears only in this answer
curl -s "${H[@]}" $API/v2/admin/keys -d '{
  "owner": "<principal-id>",
  "scope": {"data": {"kinds": ["book_snapshot"], "reference": true,
                     "all_venues": true, "all_instruments": true,
                     "history": true, "live": true, "export": true,
                     "all_book_depth": true},
            "caps": []},
  "expires_in": "2160h"}'
# -> {"key": "vmk_...", "record": {"id": "...", "principal": "...",
#      "created": "...", "expires": "..."}}

给 agent 用的话，对同一个帐号再发一把范围较窄的密钥，例如拿掉 live 与 export。

v2 权限

功能	grant 与密钥范围需要
`/v2/catalog/*`、`/v2/schemas`	任何有效密钥
`/v2/data`、`/v2/bars`	`book_snapshot`（K 线可用 `bar`）、`history`，快照另需盘口档数
`/v2/exports`	上述快照权限加上 `export`
`/v2/stream`	`book_snapshot`、`live`、盘口档数

用 veinmeshctl 可以用旗标修改 grant 与密钥范围，不必重写整份 JSON：

veinmeshctl principal grant <principal> --add-kinds book_snapshot --history --live --export --book-depth all
veinmeshctl key scope <key-id> --add-kinds book_snapshot --history --live --export --book-depth all

CLI 不会给出超过调用者本身的权限，并会说明超出哪一部分。

端点

帐号

方法与路径	请求内容	响应	管理权限
`POST /v2/admin/principals`	`{"name", "grant", "policy"?}`	`{"id"}`	`admin.principals`
`GET /v2/admin/principals`		`{"principals": [...]}`，只含调用者权限内者	`admin.principals`
`GET /v2/admin/principals/{id}`		帐号与 grant	`admin.principals`
`PUT /v2/admin/principals/{id}/grant`	`{"grant": {...}}`	204	`admin.principals`
`PUT /v2/admin/principals/{id}/policy`	`{"policy": "<id>"}`；空字符串表示移除	204	`admin.quota`

缩小 grant 会立即限制该帐号的每一把密钥。

密钥

方法与路径	请求内容	响应
`POST /v2/admin/keys`	`{"owner", "scope": {"data": ..., "caps": []}, "expires_in"?}`	`{"key", "record"}`
`GET /v2/admin/keys?owner=<principal-id>`		`{"keys": [...]}`，不含 secret
`GET /v2/admin/keys/{id}`		单笔记录与范围
`GET /v2/whoami`		调用者的密钥、帐号与生效权限
`POST /v2/admin/keys/{id}/revoke`		204
`POST /v2/admin/keys/{id}/rotate`	`{"overlap"?: "24h"}`	`{"key", "record"}`
`PUT /v2/admin/keys/{id}/scope`	`{"scope": {...}}`	204
`PUT /v2/admin/keys/{id}/expiry`	`{"expires": "2027-01-01T00:00:00Z"}`	204

除 whoami 外都需要 admin.keys。

expires_in 以小时计，例如 2160h。默认与最长有效期见限制。
overlap 默认 0（旧密钥立即失效），最长 24 小时。旧密钥不会超过原本的到期日。
撤销约一分钟内生效；使用中的连接会收到通知并关闭。
密钥 id 是 vmk_<id>_<secret> 中间的 <id>；secret 不会再显示。

用量政策

POST /v2/admin/quota/policies，需要 admin.quota：不带 id 是创建，带 id 是修改；响应 {"id"}。

字段	说明	默认
`name`	名称	必填
`requests_per_min`	每分钟请求数（HTTP、MCP 调用与 WebSocket 连接）	必填；0 表示不限
`output_bytes_per_min`	每分钟响应字节	必填；0 表示不限
`jobs_per_hour`	每小时工作数，例如计算	必填；0 表示不限
`concurrency`	同时请求数	必填；0 表示不限
`subscriptions`	同时 WebSocket 订阅数	4；0 表示不限
`event_bytes_per_min`	每分钟 WebSocket 推送字节	16 MiB；0 表示不限
`scanned_bytes_per_min`	每分钟查找读取的字节	创建时 1 GiB；修改时省略则维持原值；0 表示不限

注意

没有指定政策的帐号不受用量限制。政策目前套用于 v1 端点；/v2 尚未强制运行。仍请指定政策，以便 v2 开始运行时行为正确。

超过限制会回 quota_exceeded（429）并附 reset_after；单一请求本身超过限制则回 resource_exhausted（413）。

权限如何运作​

数据范围​

管理权限​

添加用户​

v2 权限​

端点​

帐号​

密钥​

用量政策​