Jetons d'accès utilisateur

Qu'est-ce que les jetons d'accès utilisateur ?

Les jetons d'accès utilisateur sont la méthode recommandée pour authentifier une application ou un notebook auprès des services Hugging Face. Vous pouvez gérer vos jetons d'accès dans vos paramètres.

Les jetons d’accès permettent aux applications et aux notebooks d’effectuer des actions spécifiques définies par le périmètre des rôles présentés ci-dessous :

• fine-grained : les jetons ayant ce rôle peuvent être utilisés pour accorder un accès fin à des ressources spécifiques, telles qu’un modèle particulier ou des modèles au sein d’une organisation donnée. Ce type de jeton est utile dans les environnements de production, car il vous permet d’utiliser votre propre jeton sans partager l’accès à l’ensemble de vos ressources.

• read : les jetons ayant ce rôle ne peuvent être utilisés que pour accorder un accès en lecture aux dépôts que vous pouviez lire. Cela inclut les dépôts publics et privés que vous, ou une organisation dont vous êtes membre, possédez. Utilisez ce rôle si vous n’avez besoin que de lire du contenu depuis le Hugging Face Hub (par exemple lors du téléchargement de modèles privés ou de l’exécution d’inférence).

• write : les jetons ayant ce rôle accordent en outre un accès en écriture aux dépôts pour lesquels vous disposez d'un accès en écriture. Utilisez ce jeton si vous devez créer ou pousser du contenu vers un dépôt (par exemple, lors de l'entraînement d'un modèle ou de la modification d'une fiche de modèle).

Si vous êtes membre d'une organisation avec un rôle de lecture/écriture/administration, vos jetons d'accès utilisateur (User Access Tokens) pourront lire/écrire les ressources en fonction des permissions du jeton (lecture/écriture) et de l'appartenance à l'organisation (lecture/écriture/administration).

Comment gérer les jetons d'accès utilisateur ?

Pour créer un jeton d'accès, accédez à vos paramètres, puis cliquez sur l'onglet Access Tokens. Cliquez sur le bouton New token pour créer un nouveau User Access Token.

Sélectionnez un rôle et un nom pour votre jeton, et voilà - vous êtes prêt à démarrer !

Vous pouvez supprimer et actualiser les jetons d’accès utilisateur en cliquant sur le bouton Gérer.

Comment utiliser les jetons d'accès utilisateur ?

Il existe de nombreuses façons d’utiliser un User Access Token pour accéder au Hugging Face Hub, vous offrant ainsi la flexibilité nécessaire pour créer des applications remarquables sur sa base.

Les jetons d'accès utilisateur peuvent être :

• utilisé à la place d'un mot de passe pour accéder au Hugging Face Hub avec git ou avec une authentification de base.
• transmis en tant que bearer token lors de l'appel aux Inference Providers.
• utilisé dans les bibliothèques Python de Hugging Face, telles que transformers ou datasets :

from transformers import AutoModel

access_token = "hf_..."

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

Essayez de ne pas divulguer votre jeton ! Bien que vous puissiez toujours le révoquer, quiconque pourra lire ou écrire dans vos dépôts privés en attendant, ce qui est 💩 Consultez Révoquer un jeton divulgué si un jeton a été exposé.

Bonnes pratiques

Nous vous recommandons de créer un jeton d'accès par application ou par usage. Par exemple, vous pourriez avoir un jeton distinct pour :

• Une machine locale.
• Un notebook Colab.
• Un serveur d'inférence personnalisé remarquable.

De cette manière, vous pouvez invalider un jeton sans affecter vos autres utilisations.

Nous recommandons également d'utiliser uniquement des jetons à granularité fine pour un usage en production. En cas de fuite, l'impact sera réduit, et ils peuvent être partagés au sein de votre organisation sans affecter votre compte.

Par exemple, si votre application de production a besoin d’un accès en lecture à un modèle sous licence, un membre de votre organisation peut demander l’accès au modèle, puis créer un jeton granulaire avec un accès en lecture à ce modèle. Ce jeton peut ensuite être utilisé dans votre application de production sans lui accorder l’accès à l’ensemble de vos modèles privés.

Pour les pipelines CI/CD

Si vous n’avez besoin d’accéder au Hub que depuis un workflow CI/CD (GitHub Actions, GitLab CI, CircleCI, …), vous pouvez éviter de stocker un jeton d’accès en tant que secret CI. Consultez Trusted Publishers, qui échange le jeton d’identité OpenID Connect (OIDC) de votre fournisseur CI contre un jeton Hub à durée de vie courte au début de chaque exécution — soit avec un périmètre limité au dépôt (pour publier des modèles, des jeux de données, des Spaces ou des kernels, ou pour les récupérer en lecture seule), soit avec un périmètre limité à l’utilisateur (pour lire les dépôts restreints auxquels vous avez accès et obtenir les limites de débit de votre compte).

Pour les organisations Enterprise

Si votre organisation a besoin d’émettre des jetons de manière programmatique pour ses membres sans exiger que chaque utilisateur crée son propre jeton, consultez OAuth Token Exchange. Cette fonctionnalité du plan Enterprise est idéale pour construire des plateformes internes, des pipelines CI/CD ou des intégrations personnalisées qui doivent accéder aux ressources Hugging Face au nom des membres de l’organisation.

Révoquer un jeton divulgué

Si l’un de vos jetons a fuité, supprimez-le ou actualisez-le depuis l’onglet Jetons d’accès de vos paramètres.

Si vous avez trouvé le jeton d’accès Hugging Face d’une autre personne, vous pouvez l’invalider à l’aide du point de terminaison POST /api/credentials/revoke. Vous n’avez besoin d’aucun droit sur le compte ou l’organisation propriétaire du jeton.

# 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}\"]}"

Vous pouvez passer plusieurs valeurs de jeton dans le tableau credentials lors d'un seul appel, ce qui est pratique pour les pipelines de détection de secrets qui signalent les résultats par lots.

Chaque jeton soumis qui correspond à un jeton existant est immédiatement invalidé et cesse de fonctionner partout — contrairement à la révocation au niveau de l’organisation, qui ne coupe l’accès du jeton qu’à une seule organisation. Le propriétaire du jeton est notifié par e-mail et doit créer un nouveau jeton pour rétablir l’accès.

Le point de terminaison répond toujours par 202 Accepted, que les jetons soumis existent ou non, si bien que sa réponse ne peut pas être utilisée pour vérifier la validité d’un jeton. Soumettre à nouveau le même jeton est sans danger : les appels répétés n’ont aucun effet et le propriétaire n’est notifié qu’une seule fois.

Pour éviter de divulguer les valeurs des jetons dans l’historique du shell ou les journaux, transmettez-les via des variables d’environnement ou des fichiers, et évitez de coller des jetons bruts directement dans les lignes de commande.

Jetons dans les organisations disposant de politiques de gestion des jetons

Les organisations disposant des formules Team et Enterprise peuvent imposer des politiques de jetons qui affectent le fonctionnement de vos jetons lors de l’accès aux ressources de cette organisation.

Lorsque votre jeton nécessite une approbation (organisations Team & Enterprise)

Lorsque vous créez un jeton à granularité fine, limité à une organisation qui exige l’approbation d’un administrateur, le jeton passe automatiquement à l’état Pending. Il ne peut pas accéder aux ressources de cette organisation tant qu’un administrateur ne l’a pas approuvé. Vous recevrez une notification par e-mail lorsque votre jeton sera approuvé ou refusé.

Vous pouvez vérifier l’état depuis votre page de liste de jetons : un jeton en attente affiche une icône d’heure de sable orange à côté de son badge de permissions, et un jeton refusé ou révoqué affiche une icône d’exclamation rouge. Un bandeau d’erreur rouge apparaît également sur la page de modification du jeton si celui-ci a été refusé ou révoqué.

Si vous êtes administrateur de l’organisation, les jetons à granularité fine que vous créez et qui sont limités à cette organisation sont approuvés automatiquement — aucune étape de revue n’est requise.

Lorsque votre jeton est refusé (organisations Team & Enterprise)

Si votre jeton est refusé, vous recevrez une notification par e-mail. Le jeton reste dans votre compte et peut toujours être utilisé pour les ressources en dehors de l’organisation. Un jeton refusé peut être approuvé ultérieurement par un administrateur, ce qui restaure l’accès sans que vous ayez besoin de créer un nouveau jeton.

Lorsque vous tentez d'utiliser un jeton refusé sur des ressources d'organisation, vous recevrez une erreur 403.

Lorsque votre jeton est révoqué (organisations Enterprise)

La révocation est permanente. Contrairement au refus, un jeton révoqué ne peut pas être rétabli. Si votre jeton a été révoqué, vous devez le supprimer et en créer un nouveau. Si l’organisation exige l’approbation d’un administrateur, le nouveau jeton démarrera dans un état en attente.

Lorsque vous tentez d’utiliser un jeton révoqué sur des ressources d’organisation, vous recevez une erreur 403 avec le message suivant : « Votre jeton a été révoqué par l’administrateur de l’organisation, vous ne pouvez plus accéder aux ressources de l’organisation. Veuillez les contacter pour plus d’informations. »

La révocation n'affecte que l'organisation qui l'a effectuée. Le jeton continue de fonctionner normalement pour toutes les autres ressources auxquelles il est associé.

Lorsque votre organisation n'autorise que des jetons à granularité fine (organisations Team & Enterprise)

Si votre organisation a défini une politique exigeant des jetons à granularité fine, les jetons en lecture/écriture seront rejetés avec une erreur 403 lorsqu’ils sont utilisés sur les ressources de cette organisation.