ユーザーアクセストークン

User Access Tokens とは？

User Access Tokensは、Hugging Faceサービスへのアプリケーションやノートブックの認証に推奨される方法です。アクセストークンは、設定で管理できます。

アクセストークンは、アプリケーションやノートブックが、以下のロールのスコープで指定された特定のアクションを実行できるようにします。

• fine-grained: このロールを持つトークンは、特定のモデルや特定の組織内のモデルなど、特定のリソースへの細粒度のアクセスを提供するために使用できます。このタイプのトークンは、すべてのリソースへのアクセスを共有せずに独自のトークンを使用できるため、本番環境で有用です。

• read: このロールのトークンは、読み取り可能なリポジトリへの読み取りアクセスを提供するためにのみ使用できます。これには、あなたまたはあなたが所属する組織が所有するパブリックおよびプライベートのリポジトリが含まれます。Hugging Face Hubからコンテンツを読み取る必要がある場合（プライベートモデルのダウンロードや推論の実行など）には、このロールを使用してください。

• write: このロールを持つトークンは、書き込みアクセス権を持つリポジトリに対して追加で書き込みアクセスを付与します。リポジトリにコンテンツを作成またはプッシュする必要がある場合（モデルの学習やモデルカードの変更など）には、このトークンを使用してください。

組織のメンバーであり、read/write/admin ロールを持っている場合、User Access Tokens は、トークンの権限（read/write）および組織のメンバーシップ（read/write/admin）に基づいて、リソースの読み取り/書き込みを行うことができます。

User Access Tokensを管理するには？

アクセストークンを作成するには、設定画面に移動し、Access Tokensタブをクリックします。New tokenボタンをクリックして、新しいUser Access Tokenを作成します。

トークンに役割と名前を選択すると、これで準備完了です!

Manage ボタンをクリックして、User Access Tokens を削除および更新できます。

User Access Tokensの使用方法

User Access Token を使用して Hugging Face Hub にアクセスする方法は多岐にわたり、その上に優れたアプリを構築するために必要な柔軟性を提供します。

User Access Tokens は、以下のいずれかです：

• git または基本認証で Hugging Face Hub にアクセスする際に、パスワードの代わりに使用されます。
• Inference Providersを呼び出す際に、bearer tokenとして渡されます。
• transformersやdatasetsなどの Hugging Face Python ライブラリで使用されます:

from transformers import AutoModel

access_token = "hf_..."

model = AutoModel.from_pretrained("private/model", token=access_token)

トークンの漏洩にはご注意ください。トークンはいつでもローテーション（更新）できますが、その間、誰でもあなたのプライベートリポジトリを読み書きできてしまうため、💩 です。トークンが漏洩した場合は、漏洩したトークンの失効を参照してください。

ベストプラクティス

アプリや用途ごとに1つのアクセストークンを作成することをお勧めします。例えば、以下のような用途ごとに個別のトークンを作成できます。

• ローカルマシン。
• Colabノートブック。
• 素晴らしいカスタム推論サーバーです。

この方法により、他の使用に影響を与えることなく、1つのトークンを無効化できます。

本番環境での使用には、細粒度のトークンのみを使用することをお勧めします。トークンが漏洩した場合の影響を軽減でき、アカウントに影響を与えることなく組織内で共有できます。

例えば、本番環境のアプリケーションがゲート付きモデルへの読み取りアクセスを必要とする場合、組織のメンバーがそのモデルへのアクセスをリクエストし、その後、そのモデルへの読み取りアクセス権限を持つファイングレイントークンを作成できます。このトークンを本番環境のアプリケーションで使用することで、すべてのプライベートモデルへのアクセスを付与せずに済みます。

CI/CD パイプライン向け

CI/CD ワークフロー（GitHub Actions、GitLab CI、CircleCI など）からのアクセスのみが必要な場合、アクセストークンを CI シークレットとして保存することを完全に回避できます。各実行の開始時に、CI プロバイダーの OpenID Connect (OIDC) アイデンティティトークンを Hub の短期間有効なトークンと交換する Trusted Publishers を参照してください。スコープはリポジトリ単位（モデル、データセット、Spaces、カーネルの公開、または読み取り専用での取得）またはユーザー単位（アクセス権限を持つゲート付きリポジトリの読み取り、およびアカウントのレート制限の取得）のいずれかです。

エンタープライズ組織向け

組織内で、各ユーザーが個別にトークンを発行するのではなく、メンバーのトークンをプログラムで発行する必要がある場合は、OAuth Token Exchangeを参照してください。このEnterpriseプランの機能は、組織メンバーに代わってHugging Faceのリソースにアクセスする必要がある内部プラットフォーム、CI/CDパイプライン、またはカスタム統合の構築に最適です。

リークしたトークンの無効化

ご自身のトークンのいずれかが漏洩した場合は、設定のAccess Tokensタブから削除または更新してください。

他の人の Hugging Face アクセストークンを見つけた場合、POST /api/credentials/revoke エンドポイントを使用して無効化できます。トークンを所有するアカウントまたは組織に対する権限は必要ありません。

# LEAKED_HF_TOKEN should contain the raw token value to revoke
curl -X POST "https://huggingface.co/api/credentials/revoke" \
  -H "Content-Type: application/json" \
  -d "{\"credentials\": [\"${LEAKED_HF_TOKEN}\"]}"

1回の呼び出しでcredentials配列に複数のトークン値を渡すことができるため、バッチで検出結果を報告するシークレットスキャンパイプラインに便利です。

送信されたトークンが既存のものと一致すると、即座に無効化され、すべての場所で使用できなくなります。組織レベルの失効とは異なり、後者は単一の組織へのトークンのアクセスを遮断するだけです。トークンの所有者にはメールで通知され、アクセスを回復するには新しいトークンを作成する必要があります。

エンドポイントは、送信されたトークンのいずれかが存在したかどうかに関わらず、常に202 Acceptedで応答します。そのため、この応答を使用してトークンの有効性を調査することはできません。同じトークンを再度送信しても無害です。繰り返し呼び出しは何も実行せず、所有者には一度のみ通知が行われます。

シェル履歴やログにトークン値が漏洩しないようにするため、環境変数やファイル経由で渡すようにし、生のトークンをコマンドラインに直接貼り付けないでください。

トークン管理ポリシーが設定されている組織のトークン

Team プランおよび Enterprise プランの組織では、トークンポリシーを強制できます。このポリシーは、その組織のリソースにアクセスする際にトークンがどのように動作するかに影響します。

トークンが承認を必要とする場合（Team & Enterprise組織）

管理者の承認が必要な組織にスコープを限定したファイングレインのトークンを作成すると、そのトークンは自動的にPending状態になります。管理者が承認するまで、その組織のリソースにアクセスできません。トークンが承認または拒否された場合、メールで通知が届きます。

トークン一覧ページからステータスを確認できます。保留中のトークンは、権限バッジの横にオレンジ色の砂時計アイコンが表示され、拒否または取り消されたトークンは、赤色の感嘆符アイコンが表示されます。また、トークンが拒否または取り消された場合、そのトークンの編集ページにも赤色のエラーバナーが表示されます。

組織の管理者である場合、その組織にスコープを限定して作成したファイングレイントークンは自動的に承認されます。レビュー手順は不要です。

トークンが拒否された場合（Team & Enterprise組織）

トークンが拒否された場合、メールによる通知が届きます。トークンはアカウントに保持され、組織外のリソースには引き続き使用できます。拒否されたトークンは、後で管理者によって承認されることがあり、その場合、新しいトークンを作成することなくアクセスが復元されます。

拒否されたトークンを組織のリソースに対して使用しようとすると、403エラーが発生します。

トークンが失効した場合（エンタープライズ組織）

取り消しは恒久的です。拒否とは異なり、取り消されたトークンは復元できません。トークンが取り消された場合は、削除して新しいトークンを作成する必要があります。組織で管理者の承認が必須の場合、新しいトークンは保留状態から始まります。

リボークされたトークンを組織のリソースに対して使用しようとすると、403エラーと以下のメッセージが返されます: 「あなたのトークンは組織管理者によって無効化されました。これ以上組織のリソースにアクセスすることはできません。詳細については、管理者にお問い合わせください。」

取り消しは、取り消しを行った組織にのみ影響します。トークンは、スコープが設定されている他のすべてのリソースに対して引き続き正常に機能します。

組織がファイングレイントークンのみを許可している場合（Team & Enterprise 組織）

組織が細粒度トークンを必須とするポリシーを設定している場合、読み書きトークンはその組織のリソースに対して使用されると403エラーで拒否されます。