Tokens de acceso de usuario

¿Qué son los tokens de acceso de usuario?

Los tokens de acceso de usuario son la forma preferida de autenticar una aplicación o cuaderno en los servicios de Hugging Face. Puedes gestionar tus tokens de acceso en tu configuración.

Los tokens de acceso permiten que las aplicaciones y los cuadernos realicen acciones específicas especificadas por el alcance de los roles mostrados a continuación:

• fine-grained: los tokens con este rol se pueden usar para proporcionar un acceso detallado a recursos específicos, como un modelo concreto o modelos de una organización específica. Este tipo de token es útil en entornos de producción, ya que puedes usar tu propio token sin compartir el acceso a todos tus recursos.

• read: los tokens con este rol solo se pueden usar para proporcionar acceso de lectura a repositorios que podías leer. Esto incluye repositorios públicos y privados que tú, o una organización de la que seas miembro, poseas. Usa este rol si solo necesitas leer contenido del Hugging Face Hub (por ejemplo, al descargar modelos privados o realizar inferencia).

• write: los tokens con este rol otorgan además acceso de escritura a los repositorios a los que tienes acceso de escritura. Usa este token si necesitas crear o enviar contenido a un repositorio (p. ej., al entrenar un modelo o modificar una tarjeta de modelo).

Si eres miembro de una organización con el rol de lectura/escritura/administración, tus tokens de acceso de usuario podrán leer/escribir los recursos según el permiso del token (lectura/escritura) y la membresía en la organización (lectura/escritura/administración).

Cómo gestionar los tokens de acceso de usuario?

Para crear un token de acceso, ve a tu configuración y haz clic en la pestaña Access Tokens. Haz clic en el botón New token para crear un nuevo User Access Token.

Selecciona un rol y un nombre para tu token y voilà: ¡estás listo para empezar!

Puedes eliminar y actualizar los tokens de acceso de usuario haciendo clic en el botón Manage.

Cómo usar tokens de acceso de usuario

Hay muchas formas de usar un User Access Token para acceder al Hugging Face Hub, lo que te brinda la flexibilidad que necesitas para crear aplicaciones increíbles sobre él.

Los tokens de acceso de usuario pueden ser:

• se usó en lugar de una contraseña para acceder al Hugging Face Hub con git o con autenticación básica.
• se pasa como bearer token al llamar a Inference Providers.
• utilizado en las bibliotecas de Python de Hugging Face, como transformers o datasets:

from transformers import AutoModel

access_token = "hf_..."

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

¡Intenta no filtrar tu token! Aunque siempre puedes rotarlo, mientras tanto cualquiera podrá leer o escribir en tus repositorios privados, lo cual es 💩. Consulta Revocación de un token filtrado si un token ha sido expuesto.

Buenas prácticas

Recomendamos que crees un token de acceso por cada aplicación o uso. Por ejemplo, podrías tener un token separado para:

• Un equipo local.
• Un cuaderno de Colab.
• Un servidor de inferencia personalizado excelente.

De esta manera, puedes invalidar un token sin afectar tus otros usos.

También recomendamos usar solo tokens de grano fino para su uso en producción. El impacto, en caso de fuga, se reducirá, y pueden compartirse dentro de su organización sin afectar su cuenta.

Por ejemplo, si su aplicación de producción necesita acceso de lectura a un modelo con restricciones, un miembro de su organización puede solicitar acceso al modelo y luego crear un token de granularidad fina con acceso de lectura a ese modelo. A continuación, este token puede usarse en su aplicación de producción sin otorgarle acceso a todos sus modelos privados.

Para pipelines de CI/CD

Si solo necesitas acceso desde un flujo de trabajo de CI/CD (GitHub Actions, GitLab CI, CircleCI, …), puedes evitar almacenar un token de acceso como un secreto de CI por completo. Consulta Trusted Publishers, que intercambia el token de identidad OpenID Connect (OIDC) de tu proveedor de CI por un token de Hub de vida corta al inicio de cada ejecución: ya sea con alcance de repositorio (para publicar modelos, conjuntos de datos, Spaces o kernels, o para obtenerlos en solo lectura) o con alcance de usuario (para leer repositorios con acceso restringido a los que tienes acceso y obtener los límites de tasa de tu cuenta).

Para organizaciones Enterprise

Si su organización necesita emitir tokens de forma programática para los miembros sin que cada usuario tenga que crear su propio token, consulte OAuth Token Exchange. Esta función del plan Enterprise es ideal para construir plataformas internas, pipelines de CI/CD o integraciones personalizadas que necesiten acceder a los recursos de Hugging Face en nombre de los miembros de la organización.

Revocar un token filtrado

Si uno de tus propios tokens se ha filtrado, elimínalo o actualízalo desde la pestaña Access Tokens de tu configuración.

Si has encontrado un token de acceso de Hugging Face de otra persona, puedes invalidarlo con el endpoint POST /api/credentials/revoke. No necesitas ningún derecho sobre la cuenta u organización que posee el token.

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

Puedes pasar varios valores de token en el array credentials en una sola llamada, lo cual es conveniente para los pipelines de detección de secretos que informan de los hallazgos por lotes.

Cada token enviado que coincide con uno existente se invalida de inmediato y deja de funcionar en todas partes, a diferencia de la revocación a nivel de organización, que solo corta el acceso del token a una única organización. El propietario del token recibe una notificación por correo electrónico y debe crear un nuevo token para restablecer el acceso.

El punto de acceso siempre responde con 202 Accepted, independientemente de si alguno de los tokens enviados existía o no, por lo que su respuesta no puede utilizarse para comprobar si un token es válido. Enviar el mismo token de nuevo es inofensivo: las llamadas repetidas no tienen efecto y el propietario solo se notifica una vez.

Para evitar filtrar los valores de los tokens en el historial de la shell o en los registros, páselos mediante variables de entorno o archivos, y evita pegar tokens en bruto directamente en las líneas de comando.

Tokens en organizaciones con políticas de gestión de tokens

Las organizaciones con planes Team y Enterprise pueden aplicar políticas de tokens que afectan el funcionamiento de tus tokens al acceder a los recursos de esa organización.

Cuando su token requiere aprobación (organizaciones de Team & Enterprise)

Cuando creas un token de grano fino limitado a una organización que requiere la aprobación de un administrador, el token pasa automáticamente al estado Pending. No puede acceder a los recursos de esa organización hasta que un administrador lo apruebe. Recibirás una notificación por correo electrónico cuando tu token sea aprobado o denegado.

Puedes verificar el estado desde la página de tu lista de tokens: un token pendiente muestra un icono de reloj de arena naranja junto a su insignia de permisos, y un token denegado o revocado muestra un icono de exclamación rojo. También aparece un banner de error rojo en la página de edición del token si este fue denegado o revocado.

Si eres administrador de la organización, los tokens de grano fino que crees con alcance limitado a esa organización se aprueban automáticamente: no se requiere una etapa de revisión.

Cuando se deniega tu token (organizaciones de Team & Enterprise)

Si se deniega tu token, recibirás una notificación por correo electrónico. El token permanece en tu cuenta y aún puede usarse para recursos fuera de la organización. Un token denegado puede aprobarse más adelante por un administrador, lo que restablece el acceso sin que tengas que crear un token nuevo.

Al intentar usar un token denegado contra los recursos de la organización, recibirá un error 403.

Cuando se revoca su token (organizaciones Enterprise)

La revocación es permanente. A diferencia de la denegación, un token revocado no puede restablecerse. Si su token ha sido revocado, debe eliminarlo y crear uno nuevo. Si la organización requiere la aprobación de un administrador, el nuevo token comenzará en un estado pendiente.

Al intentar usar un token revocado contra recursos de la organización, recibirá un error 403 con el mensaje: “Su token ha sido revocado por el administrador de la organización, ya no puede acceder a los recursos de la organización. Póngase en contacto con ellos para obtener más información.”

La revocación solo afecta a la organización que la realizó. El token sigue funcionando con normalidad para todos los demás recursos a los que está limitado.

Cuando su organización solo permite tokens de granularidad fina (organizaciones de equipo y empresa)

Si su organización ha establecido una política que exige tokens de grano fino, los tokens de lectura/escritura se rechazarán con un error 403 cuando se utilicen contra los recursos de esa organización.