管理者

本頁給負責發放金鑰的管理者。管理功能仍使用 /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 權限​

端點​

帳號​

金鑰​

用量政策​