權杖管理

此功能為 團隊與企業 (Team & Enterprise) 方案的一部分。

權杖管理（Tokens Management）讓組織管理員能夠監控組織內的存取權杖，確保組織資源的安全存取。

若要了解權杖管理政策生效時的成員體驗——包括如何檢查權杖狀態、會遇到哪些錯誤，以及拒絕與撤銷對權杖的影響——請參閱 實施權杖管理政策的組織中的權杖。

查看與管理存取權杖

權杖列表功能可顯示組織內的所有存取權杖。管理員可以：

• 監控權杖使用情形，識別或預防潛在的安全風險
  • 未經授權存取私人資源（「洩漏」）
  • 過於廣泛的存取範圍
  • 權杖清理不完善（例如：長時間未更換的權杖）
• 識別非活躍或未使用的權杖

精細化權杖（Fine-grained tokens）會顯示其特定的權限

已撤銷的權杖預設會從列表中隱藏。使用列表上方的顯示已撤銷權杖 (Show revoked tokens) 切換按鈕，即可將其包含在檢視中。

無論組織的權杖政策為何，任何已撤銷的權杖都會顯示 REVOKED（已撤銷）狀態徽章。PENDING（待處理）、APPROVED（已核准）與 DENIED（已拒絕）徽章僅會出現在啟用了「要求管理員核准」政策的組織中，因為這些狀態僅透過核准流程產生。

權杖政策

「團隊 (Team)」與「企業 (Enterprise)」組織的管理員可以強制執行以下政策：

審查權杖授權

當權杖政策設定為「要求管理員核准」時，組織管理員可以審查存取組織資源的所有精細化權杖詳情，並核准或拒絕存取權。當新權杖進入「待處理」狀態時，最多 5 名電子郵件地址經過驗證的組織管理員會收到通知，其中包含前往權杖審查頁面的直接連結。若權杖為自動核准（例如：創建者本身為組織管理員），則不會發送通知。

• Pending（待處理）的權杖正在等待管理員決策
• Approved（已核准）的權杖已獲得授權並處於啟用狀態
• Denied（已拒絕）的權杖已被封鎖，無法存取組織資源

當權杖被核准或拒絕時，權杖擁有者會收到電子郵件通知。

拒絕並非永久性：被拒絕的權杖日後可由管理員核准，恢復其存取權。同樣地，已核准的權杖也可隨時被拒絕，這會立即移除其基於核准的存取權。

只有在啟用「要求管理員核准」政策時，管理員才能看到權杖名稱。

成員被封鎖時的畫面

權杖處於「待處理」或「已拒絕」狀態的成員，在存取組織資源時會收到 403 錯誤訊息：「由於組織的權杖政策，您的權杖必須先經由組織核准，才能存取此資源。」

對於「待處理」和「已拒絕」狀態，錯誤訊息是相同的。若要查看狀態，成員可以導覽至個別權杖的編輯頁面。組織管理員的權杖管理設定頁面會顯示所有成員權杖的狀態徽章。

拒絕 (Deny) 與撤銷 (Revoke) 的比較

管理員有兩種方式可以移除權杖對組織的存取權：

在管理核准工作流程內的存取權時使用拒絕 (Deny)（權杖會轉變為 denied 狀態，日後可重新核准）。當您需要永久切斷權杖對組織的存取權時，請使用撤銷 (Revoke)。

撤銷權杖

此功能為 企業 (Enterprise) 方案及以上版本的一部分。

組織管理員可以在權杖詳情頁面撤銷任何成員的存取權杖。無論組織是否使用「要求管理員核准」政策，皆可進行撤銷。已撤銷的權杖無法再存取組織的資源，但在其他地方仍可繼續運作。權杖擁有者會在撤銷時收到電子郵件通知。

即使日後變更或停用組織的權杖政策，已撤銷的權杖仍保持撤銷狀態。撤銷在組織層級是永久性的——沒有「取消撤銷」的操作。如果成員需要恢復存取權，他們必須刪除該已撤銷的權杖並建立一個新的。如果組織使用「要求管理員核准」政策，新權杖將會從「待處理」狀態開始，並需要管理員核准。

權杖已遭撤銷的成員在存取資源時會收到 403 錯誤訊息：「您的權杖已被組織管理員撤銷，您無法再存取組織資源。請聯繫管理員以獲取更多資訊。」 無論組織是否使用「要求管理員核准」政策，都會顯示此訊息。

透過 API 撤銷

管理員也可以透過提供原始權杖值，以程式化方式撤銷權杖。這對於自動化工作流程（例如祕密掃描）非常有用，當偵測到洩漏的權杖時，可以立即將其撤銷。

# ORG_NAME should be your organization name and ADMIN_HF_TOKEN an admin's access token
# LEAKED_HF_TOKEN should contain the raw token value to revoke
curl -X POST "https://huggingface.co/api/organizations/${ORG_NAME}/settings/tokens/revoke" \
  -H "Authorization: Bearer ${ADMIN_HF_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"token": "${LEAKED_HF_TOKEN}"}'

為避免在 Shell 歷史記錄或日誌中洩漏權杖值，請透過環境變數或檔案傳遞，並避免將原始權杖直接貼上到命令列中。

管理員無法撤銷自己的權杖（上述程式碼片段中的 LEAKED_HF_TOKEN 不能與 ADMIN_HF_TOKEN 值相同）。

程式化權杖簽發

對於需要為成員以程式化方式簽發存取權杖的組織（例如用於內部平台、CI/CD 管線或自訂整合），請參閱 OAuth 權杖交換 (OAuth Token Exchange)。此企業方案功能允許您的後端服務為組織成員簽發具備範圍限制的權杖，且無需使用者進行互動式同意。