認證與 API 金鑰
Bearer token、scope 授權模型、常見的權限組合，以及金鑰的生命週期
本服務 API 端點為：
https://api.norma.terathinker.com/v1所有 API 請求均需要帶一個 bearer 憑證：
Authorization: Bearer sk_live_9f2k7d3q1w8e連線一律強制 TLS 1.3，不提供 HTTP，協商較舊 TLS 版本的連線會被拒絕。
權限範圍 Scope
Scope 的命名採 resource:action 格式。建立 API 金鑰時需要設定該金鑰允許的權限，或在建立後於 Studio 中調整（惟增加權限時，需要通過加強驗證，詳見調整既有金鑰）。可以設定的權限列表如下：
| Scope | 授予 |
|---|---|
submissions:create | 建立提交（單筆與批次） |
submissions:read | 讀取提交、其作答與批閱進度 |
evaluations:read | 讀取批閱結果與版本歷史、覆核紀錄 |
evaluations:revise | 覆核分數（產生新的批閱結果版本） |
exams:read | 讀取考試 |
exams:manage | 建立考試、編輯標籤、封存與取消封存 |
questions:read | 讀取題目與評分標準定義 |
questions:manage | 建立、更新、封存、取消封存題目與評分標準 |
rosters:read | 讀取學生名冊 |
rosters:manage | 建立、取代、刪除學生名冊 |
設定 Scope 時，請特別注意以下的權限特性。
相同資源的「讀取權限」不會被「管理權限」隱含
管理權限（如 *.manage）並不包含對該資源的讀取權限（如 *.read），需要兩者權限時，兩者均必須明確勾選。
例如：既要建立提交、又要查詢批閱進度的金鑰，必須同時具備 submissions:create 與 submissions:read。
「讀取批閱結果/分數」與「讀取評分標準」的權限不同
evaluations:read 授予對分數、評語與批閱結果版本歷史的讀取權限，並不包含 questions:read，因此也不包含題幹與評分標準。
例如：對學生的展示畫面可以顯示該名學生自己的分數與評語，但同時不揭露評分標準。批閱結果的 payload 亦不會回傳評分標準的級距文字描述，而改以另行產生的評語 feedback 進行說明與揭露。所有評分標準級距的 description 需透過 questions:read 取得。
常見的權限組合
下表是多數整合實際需要的組合，Studio 的 API 建立畫面中亦提供一鍵勾選功能，便於查詢及使用：
| scope | 適用於 |
|---|---|
submissions:read、evaluations:read、exams:read、questions:read | 唯讀存取（儀表板、報表） |
submissions:create、submissions:read、evaluations:read | 建立與管理提交 |
submissions:read、evaluations:read、evaluations:revise | 人工批閱與覆核工具 |
exams:read、exams:manage、questions:read、questions:manage、rosters:read、rosters:manage | 考試、題目與名冊維護 |
| 上表全部 | 完整存取 |
金鑰白名單
金鑰可以設定操作 IP 白名單 ip_allowlist（使用 CIDR 指定）。來自清單外的請求會得到 403 ERR_FORBIDDEN 錯誤。
白名單亦可忽略不設定，並使其於允許來自所有位址的請求。
停用金鑰
您可以自 Studio 介面中停用金鑰。請注意金鑰在停用後，無法重新啟用。使用已停用的金鑰，會得到 401 ERR_API_KEY_DISABLED 錯誤。
調整既有金鑰
金鑰建立之後，名稱、scope、IP 允許清單都可以在 Studio 修改，不需要換掉金鑰或重新部署。
若在 Studio 中增加金鑰權限，則系統可能會要求加強驗證。
| 項目 | 可否變更 |
|---|---|
name | 可以 |
scopes | 可以 |
ip_allowlist | 可以 |
| 狀態 | 只能單向停用，且不可逆 |
| 金鑰 id、建立時間 | 建立時決定，之後不可變更 |
| 祕密值 | 不可變更 |
已停用的金鑰則不能修改。
祕密值
祕密值 sk_live_… 只在建立當下出現一次，之後無法透過任何方式或管道重新瀏覽取得。
金鑰外洩或日常輪換的處理
當 API 金鑰疑似或已外洩，或需要進行維運輪換時，請依照以下處理步驟更新您的 API 金鑰：
- 在 Studio 建立一把權限相同的新 API 金鑰
- 切換並更新原有 API 金鑰的所有程式碼與服務
- 停用舊的/外洩的 API 金鑰
停用 API 金鑰後，您不能取消並重新啟用。因此為了避免您的服務中斷，請務必先部署新的 API 金鑰後，再停用舊的 API 金鑰。
需要協助時，請聯絡 support@terathinker.com，並附上受影響 API 金鑰的 ak_ ID。請勿將 sk_live_… 的 API Secret 寄送給任何人（包括本服務團隊）。
加強驗證（step-up MFA）
當您在 Studio 中進行操作風險相對較高的管理行為時，網站可能會提示您重新驗證身分，以確保操作安全。例如：
- 建立 API 金鑰
- 放寬既有金鑰的權限（例如增加 scope，或放寬 IP 允許清單）
- 註冊 Webhook 端點
- 新增或停用 Webhook 簽章密鑰
- 覆核批閱結果（由人在 Studio 操作時）
驗證成功後工作階段會持續 15 分鐘 不需重複驗證。
相關
- 在 Studio 取得金鑰 — 金鑰與其他僅限 Studio 的操作
- 錯誤代碼一覽