SCOPES & TOKENS

Scopes and tokens

Access is a bitmap the user approves and a short-lived signed token your app carries. Every bit is grantable, and the user approves each one separately.

訪問權限 = 用戶同意的一張位圖 + 你的應用攜帶的一枚帶簽名的短期令牌。每一個位都可以授出，由用戶逐項同意。

The scope bits

Bit	Scope	Allows	Risk	Status
`1`	`recordings.read` `SCOPE_RECORDINGS_READ`	Read, list and search transcripts, summaries and speaker identity. Also what makes `recording.ready` fire.	Medium — data leaving is irreversible	GRANTABLE
`2`	`audio.live` `SCOPE_AUDIO_LIVE`	Live audio stream into your foreground app while the user holds the button.	High	GRANTABLE
`4`	`capture.control` `SCOPE_CAPTURE_CONTROL`	Start and stop recording. Requires the exclusive control lease.	Medium	GRANTABLE
`8`	`device.manage` `SCOPE_DEVICE_MANAGE`	Trigger OTA, enrol a voiceprint, read and write settings including LED and haptics, delete.	High	GRANTABLE
`16`	`recordings.audio` `SCOPE_RECORDINGS_AUDIO`	Download the original audio file. Deliberately separate from reading text.	High — the raw voice of everyone in the room	GRANTABLE
`32`	`device.status.read` `SCOPE_DEVICE_STATUS_READ`	Battery, storage, firmware version, connection state, smart-wake switch, last sync. Live over BLE; from the cloud as a snapshot with `observedAt`.	Low	GRANTABLE
`64`	`insights.read` `SCOPE_INSIGHTS_READ`	Weekly insights, speaking share, to-dos. Separate from `recordings.read`: an insight is not the transcript.	Medium — derived data leaving	GRANTABLE
`128`	`events.subscribe` `SCOPE_EVENTS_SUBSCRIBE`	Card and processing events, over webhooks and BLE. Payloads carry no transcript text.	Medium	GRANTABLE

位	權限	可做什麼	風險級	狀態
`1`	`recordings.read` `SCOPE_RECORDINGS_READ`	讀取、列出與搜索轉寫、摘要和說話人身份。也是 `recording.ready` 會推送的前提。	中——數據外流不可逆	可授權
`2`	`audio.live` `SCOPE_AUDIO_LIVE`	用戶按住按鍵時，實時音頻流入你的前台 App。	高	可授權
`4`	`capture.control` `SCOPE_CAPTURE_CONTROL`	開始與停止錄音。需要互斥的控制權租約。	中	可授權
`8`	`device.manage` `SCOPE_DEVICE_MANAGE`	觸發 OTA、聲紋註冊、讀寫設置（含 LED 與振動）、刪除。	高	可授權
`16`	`recordings.audio` `SCOPE_RECORDINGS_AUDIO`	下載音頻原件。刻意與讀取文字分開。	高——房間裡每個人的原聲	可授權
`32`	`device.status.read` `SCOPE_DEVICE_STATUS_READ`	電量、存儲、固件版本、連接狀態、智能喚醒開關、最近同步。經 BLE 為實時值；經雲端為附 `observedAt` 的快照。	低	可授權
`64`	`insights.read` `SCOPE_INSIGHTS_READ`	週洞察、發言佔比、待辦。獨立於 `recordings.read`：洞察不等於原文。	中——派生數據外流	可授權
`128`	`events.subscribe` `SCOPE_EVENTS_SUBSCRIBE`	卡片與處理事件，經 webhook 與 BLE 送達。載荷不含轉寫正文。	中	可授權

Bits combine with a bitwise OR. Reading text plus the audio file is 1 | 16 = 17. Registering or requesting an undefined bit is rejected outright.

transcription.create (SCOPE_TRANSCRIPTION_CREATE in the SDK) is not a card bit: it is a processing permission held on the server, asked for on the same consent screen, that lets your app upload audio for transcription or re-summarization.

權限位按位或組合。讀文字加音頻原件就是 1 | 16 = 17。登記或申請未定義的位會被直接拒絕。

transcription.create（SDK 中為 SCOPE_TRANSCRIPTION_CREATE）不是卡片權限位，而是保存在服務端的處理授權，在同一個授權頁上申請，允許你的應用上傳音頻做轉寫或重新摘要。

ASK NARROW

The token carries the intersection of what your app registered and what the user approved, so over-registering buys you nothing and shows up on their consent screen. Ask for recordings.audio only if you actually process audio — most integrations want the text.

只申請你需要的

令牌裡寫的是「應用登記」與「用戶同意」的交集，多申請沒有任何好處，而且會原樣出現在用戶的同意頁上。真的要處理音頻才申請 recordings.audio——多數接入只需要文字。

The capability token

The token is issued by the cloud, signed with Ed25519, and sent to you Base64Url-encoded without padding. Wire format v1 is a 41-byte fixed-length payload plus a 64-byte signature — 105 bytes raw, 140 characters encoded. It is a bearer credential: treat it like a password.

令牌由雲端簽發、Ed25519 簽名，以無填充的 Base64Url 編碼交給你。線協議 v1 為 41 位元組定長載荷加 64 位元組簽名——原始 105 位元組，編碼後 140 字元。它是 bearer 憑證：請當成密碼對待。

Field	Size	Content
`ver`	1B	Fixed at 1
`app_id`	4B	Your app id
`user_uuid`	16B	The authorizing user
`device_id`	8B	Target device; 0 on the cloud path
`scopes`	4B	The granted bitmap
`iat` / `exp`	4B + 4B	Issued and expiry in epoch seconds; exp = iat + 60 days
`sig`	64B	Ed25519 over the first 41 bytes; integers big-endian

WHERE THE TOKEN IS CHECKED

In the cloud on every call, and on the card for every BLE session: the card verifies the signature, expiry, scopes and the user the token was issued for, offline. The card does not run third-party code and does not accept a signing key you supply.

令牌在哪裡被校驗

雲端在每次調用時校驗；卡片在每個 BLE 會話中離線校驗簽名、有效期、權限以及令牌簽發給哪位用戶。卡片不執行第三方代碼，也不接受你提供的簽名密鑰。

The life of a grant

Stage	What happens
Granted	The user approves scope by scope. One grant per (user, app); re-authorizing updates it rather than stacking.
Carried	Your app sends the token as `X-Vyslo-Token`. The server re-checks the grant on every call, not just at issue.
Renewed	Swap the token for a fresh one about weekly. Renewal re-checks that the grant stands and the app is not banned.
Expired	60 days after issue. This is the offline grace period: long enough that a card and a phone out of coverage keep working.
Revoked	The user revokes in the VYSLO app. The server refuses your next call immediately and the app is appended to that user's revocation list, whose version is monotonic.

階段	發生什麼
授出	用戶逐項確認。每個（用戶，應用）只有一份授權；重新授權是更新，不是疊加。
攜帶	你的應用用 `X-Vyslo-Token` 發送令牌。服務端在每一次調用時重新校驗授權，不只在簽發時。
續簽	大約每週換一枚新令牌。續簽會重新確認授權仍有效、應用未被封禁。
過期	簽發後 60 天。這就是離線寬限期：長到足以讓沒有信號的卡與手機照常工作。
撤銷	用戶在 VYSLO App 內撤銷。服務端立即拒絕你的下一次調用，該應用被加入此用戶的撤銷單，單號單調遞增。

Revocation on the server is immediate. Revocation on a card is not an instant guarantee and we will not describe it as one: the card enforces a revocation once it has received and verified the new state, and a fully offline card runs out its remaining validity. A longer grace period is a slower recall — that is a dial, not a free choice.

服務端撤銷是即時的。卡片上的撤銷不是即時保證，我們也不會這樣描述：卡片在收到並驗證新狀態後才拒絕該授權，完全離線的卡片按剩餘有效期執行。寬限期越長，收回越慢——這是一個旋鈕，不是免費的選擇。

Two gates beyond scope

A physical press for destructive operations. Unbinding a card, deleting all recordings and resetting a voiceprint need a button press on the card itself, on top of device.manage. The rule applies to the VYSLO app as well — everyone goes through the same gate.

The visibility gate. A recording whose visibility is not visible is never pushed and never returned, whatever scopes you hold. There is no flag to opt out of this.

破壞性操作需要物理按鍵。清卡片綁定、刪除全部錄音、重置聲紋，除 device.manage 外還需要在卡片上按一下實體鍵。這條規則對 VYSLO App 同樣生效——人人過同一道安檢。

可見性閘門。visibility 不是 visible 的錄音永不推送、永不返回，無論你持有什麼權限。沒有繞過它的開關。

What we deliberately keep closed

The firmware signing chain. Private keys stay in-house, the bootloader takes no third-party key and there is no unlock mode. You can trigger an update; the card only ever runs an image we signed.
The raw BLE protocol as a public contract. What we promise is the SDK API and the cloud API. The protocol itself ships inside the SDK so it can keep evolving — and so that opening access stays reversible.
Voiceprint judgment and enrolment embeddings are not open to a bring-your-own model. Identity is the primitive we are accountable for.

固件簽名鏈。私鑰不外發，bootloader 不加第三方公鑰，沒有解鎖模式。你可以觸發升級；卡片永遠只跑我們簽名的鏡像。
裸 BLE 協議不作為公開承諾。我們對外承諾的是 SDK API 與雲 API。協議本體隨 SDK 交付，以便繼續演進——也讓「開放」保持可逆。
聲紋判決與註冊 embedding 不開放自帶模型。身份是我們必須負責的那個原語。

Previous← MCP NextCapability status →