トークン管理

この機能は、Team & Enterprise プランの一部です。

Tokens Managementにより、組織管理者は組織内のアクセストークンを管理し、組織リソースへの安全なアクセスを確保できます。

トークン管理ポリシーが適用されている場合のメンバー体験について、トークンのステータス確認方法、想定されるエラー、および拒否と失効がトークンに与える影響については、トークン管理ポリシーが適用されている組織のトークンを参照してください。

アクセス トークンの表示と管理

トークン一覧機能では、組織内のすべてのアクセストークンが表示されます。管理者は以下を行うことができます。

• トークンの使用状況を監視し、潜在的なセキュリティリスクを特定または防止します:
  • プライベートリソースへの不正アクセス（「リーク」）
  • 広すぎるアクセススコープ
  • 最適化されていないトークン衛生管理（例：長期間ローテーションされていないトークン）
• 未使用または無効なトークンを特定する

細粒度のトークンは、その特定の権限を表示します:

失効したトークンは、デフォルトでは一覧に表示されません。一覧の上部にある失効したトークンを表示のトグルをオンにすると、表示に含めることができます。

組織のトークンポリシーに関わらず、失効したトークンにはすべてREVOKEDステータスバッジが表示されます。PENDING、APPROVED、DENIEDバッジは、承認フローによってのみこれらの状態が作成されるため、「管理者の承認を要求する」ポリシーが有効になっている組織でのみ表示されます。

トークンポリシー

Team & Enterpriseの組織管理者は、以下のポリシーを強制できます。

トークン認証の確認

トークンポリシーが「管理者の承認を要求」に設定されている場合、組織管理者は、組織が所有するリソースにアクセスするすべてのファイングレインドトークンの詳細を確認し、アクセスを承認または拒否できます。新しいトークンが保留状態になると、確認済みのメールアドレスを持つ最大50人の組織管理者に、トークンレビューページへの直接リンクを伴う通知が送信されます。トークンが自動承認された場合（作成者が組織管理者であるためなど）、通知は送信されません。

• Pending トークンは管理者の判断を待っています
• 承認済みトークンは承認されており、有効な状態です
• 拒否トークンは、組織のリソースへのアクセスがブロックされました

トークンが承認または拒否されると、トークンの所有者にメール通知が送信されます。

拒否は恒久的ではありません。拒否されたトークンは、管理者によって後日承認され、アクセスが復元される場合があります。同様に、すでに承認されているトークンも、いつでも拒否することができ、これにより承認に基づくアクセスが即座に削除されます。

トークン名は、「管理者の承認を必須にする」ポリシーが有効な場合のみ、管理者にのみ表示されます。

ブロックされた場合、メンバーが見るもの

トークンが保留中または拒否されているメンバーは、組織のリソースにアクセスする際に403エラーを受信します: “組織のトークンポリシーにより、このリソースにアクセスするには、組織によるトークンの承認が必要です。”

保留中と拒否の両方の状態で、エラーメッセージは同じです。ステータスを確認するには、メンバーが個々のトークンの編集ページに移動できます。組織管理者のトークン管理設定ページには、すべてのメンバーのトークンのステータスバッジが表示されます。

Deny と Revoke

管理者は、組織へのトークンのアクセスを削除するために2つの方法があります。

承認ワークフロー内でアクセスを管理する場合は deny を使用します（トークンは denied 状態に移行し、後で再承認できます）。組織へのトークンのアクセスを完全に切断する必要がある場合は revoke を使用します。

APIによるトークンの一覧表示

設定UIに表示されるトークンの一覧は、プログラム的にも利用できます:

# ORG_NAME should be your organization name and ADMIN_HF_TOKEN an admin's access token
curl -H "Authorization: Bearer ${ADMIN_HF_TOKEN}" \
  "https://huggingface.co/api/organizations/${ORG_NAME}/settings/tokens"

レスポンスはメンバーアクセストークンの配列です。完全なスキーマについては、OpenAPIリファレンスを参照してください: GET /api/organizations/<name>/settings/tokens

デフォルトでは、失効したトークンは非表示です。UIの「失効したトークンを表示する」トグルと同様に、q=status:allを渡すことでこれらを含めることができます。

トークンの無効化

この機能は、Enterprise プラン以上でご利用いただけます。

組織管理者は、トークン詳細ページから任意のメンバーのアクセストークンを失効させることができます。失効機能は、組織が「管理者の承認を必須にする」ポリシーを使用しているかどうかに関係なく利用可能です。失効されたトークンは、組織のリソースにアクセスできなくなりますが、他の場所では引き続き機能します。トークンの失効時、トークンの所有者にはメール通知が送信されます。

失効したトークンは、組織のトークンポリシーが後で変更または無効化された場合でも、失効したままです。失効は組織レベルで恒久的であり、失効解除の操作はありません。メンバーがアクセスを復元する必要がある場合は、失効したトークンを削除して新しいトークンを作成する必要があります。組織が「管理者の承認を必須にする」ポリシーを使用している場合、新しいトークンは保留状態から始まり、管理者の承認が必要になります。

トークンが取り消されたメンバーは、403エラーと以下のメッセージを受信します: “あなたのトークンは組織管理者によって取り消されました。組織リソースへのアクセスはもうできません。詳細については、管理者にお問い合わせください。” このメッセージは、組織が“Require administrator approval”ポリシーを使用しているかどうかに関係なく表示されます。

APIによる失効

管理者は、トークンIDを使用してトークンをプログラム的に取り消すこともできます。これは、トークンを即座に取り消す必要がある自動化ワークフローに便利です。

# ORG_NAME should be your organization name and ADMIN_HF_TOKEN an admin's access token
# TOKEN_ID is the 24-character id shown on the org token settings page (or returned by the tokens listing API)
curl -X POST "https://huggingface.co/api/organizations/${ORG_NAME}/settings/tokens/${TOKEN_ID}/revoke" \
  -H "Authorization: Bearer ${ADMIN_HF_TOKEN}"

管理者は自分のトークンを無効化できません。認証に使用されたトークンとトークン ID が一致するリクエストは、403 エラーで拒否されます。

このエンドポイントは、トークンがあなたの組織にアクセスする権限のみを失効します。トークンは、所有者の他のリソースに対しては引き続き機能します。漏洩したトークンをすべての場所で無効にするには、認証を必要とせず、生のトークン値のバッチを受け入れるPOST /api/credentials/revokeを使用してください。

プログラマティックなトークン発行

この機能は、Enterprise プラン以上でご利用いただけます。

メンバーに対してプログラムでアクセストークンを発行する必要がある組織（内部プラットフォーム、CI/CD パイプライン、カスタム統合など）は、OAuth トークン交換を参照してください。この Enterprise プランの機能により、バックエンドサービスは、インタラクティブなユーザーの同意を必要とせずに、組織メンバーのスコープ付きトークンを発行できます。

サービスアカウント

この機能は、Enterprise プラン以上でご利用いただけます。

組織が所有する自動アクセスのために、管理者はService Accountsを作成し、組織のリソースにスコープを限定した細粒度のトークンを発行できます。