權限與角色

每個 token 屬於一個使用者，使用者有一個角色；角色決定你能呼叫哪些端點、看得到誰的資料。

本篇說明角色與其典型範圍、權限字串怎麼對應到端點、為何業務只看得到自己的訂單，以及哪些功能受模組與自訂角色控制。

角色總覽

cairn 內建六種角色。admin / sales / op / accountant 是後台員工角色，customer 是顧客，guide 是嚮導受限登入。

說明

只有 sales 與 admin 可被指派為訂單的負責人。guide 是受限登入，不能進後台或管理其他使用者；customer 只能操作自己的資料。

每個端點都要求一個 權限字串，格式是 resource.action（資源 + 動作）。API 參考逐端點標了它要求的權限——你的角色被授予該權限，才呼叫得動。

一個資源的不同動作可分別授權：例如 op 有 order.read / order.update / order.adjust，但沒有 order.create；accountant 只有 order.read。讀與寫分開——能看不代表能改。

呼叫端點時，伺服器依你 token 的角色檢查所需權限；不足即回 403 forbidden。

部分端點除了權限檢查，還會依 token 的使用者自動限縮可見範圍。最典型的是訂單：

範圍由伺服器依 token 的使用者重新判定，不接受用參數覆寫。落在範圍外的資源，對你而言形同不存在——查詢列表時不會出現，直接取用會回 404 not_found（而非 403，避免洩漏存在性）。

注意

不要用 owner-scope 當唯一授權假設。admin / op / accountant 等管理角色看得到全部訂單；owner-scope 是業務心理隔離的範圍限縮，不是逐租戶隔離（租戶隔離由網域天然完成，見總覽）。

部分進階功能屬可選模組，租戶可能未啟用。即使你的角色有對應權限，模組關閉時相關端點仍會回 403 module_disabled：

模組閘先於權限檢查：先確認租戶啟用了模組，再看你的角色有沒有權限。

兩個 403 要分開處理：module_disabled 代表「整個功能未開通」（要租戶在設定啟用模組），forbidden 代表「你這個角色沒權限」（要換有權限的 token 或調整角色）。

除了六個內建角色，admin 可以建立自訂角色，用「資源 × 動作」矩陣勾選要授予哪些 resource.action。

透過 roles API 可列出角色（內建 + 自訂）並讀取單一角色的完整權限矩陣；指派使用者角色與建立員工帳號走 staff API。

提示

要查「某個 token 為何被擋」，先看 API 參考該端點標的權限字串，再用 roles API 對照該使用者角色的權限矩陣有沒有那一格；若端點屬模組功能，也確認租戶啟用了該模組。