Hub documentation
Gestión programática del control de acceso de usuario
Gestión programática del control de acceso de usuario
Esta guía describe cómo gestionar los roles de los miembros de una organización y la pertenencia a grupos de recursos a través de la API de Hub: cambiar el rol de organización y las asignaciones de grupos de recursos de un miembro, listar grupos de recursos, agregar usuarios a grupos y flujos de trabajo por lotes.
Tabla de contenidos:
- Cambiar el rol de un miembro mediante la API — Establece el rol de organización de un miembro y sus asignaciones de grupos de recursos (un miembro por solicitud).
- API de grupos de recursos — Lista grupos de recursos y agrega usuarios a ellos.
- Configurar la incorporación automática mediante la API — Habilita o deshabilita la incorporación automática en un grupo de recursos.
- Invitar colaboradores externos mediante la API — Invita a usuarios de fuera de la organización a un grupo de recursos.
- Cambiar el tipo de cuenta de un miembro mediante la API — Convierte a un miembro en colaborador externo, o viceversa.
Cambiar el rol de un miembro a través de la API
Puede cambiar el rol de organización de un miembro (No Access / Read / Contributor / Write / Admin) y, opcionalmente, sus roles en los grupos de recursos mediante la API de Hub. La API actualiza un miembro por solicitud. Para cambiar los roles de varios miembros, llame a la API en un bucle (los ejemplos están a continuación).
Referencia de OpenAPI: PUT /api/organizations/{name}/members/{username}/role
Prerrequisitos
- Su organización debe tener un plan de suscripción (p. ej., Team o Enterprise). De lo contrario, el punto de acceso devuelve 402.
- Debes estar autenticado como miembro de la organización con permiso Write (o Admin) en la organización.
- El usuario objetivo ya debe ser miembro de la organización.
URL base y autenticación
- URL base:
https://huggingface.co - Authentication: Envía tu token en la cabecera de la solicitud: Crea un token de grano fino con el permiso «Write access to organizations settings / member management» limitado a tu organización en https://huggingface.co/settings/tokens.
Authorization: Bearer <your_access_token>
Punto de acceso para cambiar el rol de un miembro
Solicitud
PUT /api/organizations/{org_name}/members/{username}/role
Authorization: Bearer <your_access_token>
Content-Type: application/json
{
"role": "read",
"resourceGroups": []
}- Path parameters
org_name: identificador de la organización (p. ej.,my-org).username: username de Hugging Face del miembro cuyo rol estás cambiando.
- Body
role(obligatorio): el rol a nivel de organización del miembro. Uno de:"no_access","read","contributor","write"o"admin".resourceGroups(opcional: un array de asignaciones de grupos de recursos para este usuario. Cada elemento:id: ID del grupo de recursos (cadena hexadecimal de 24 caracteres; obtén los IDs de la API de lista de grupos de recursos).role: Rol en ese grupo de recursos:"read","contributor","write","admin"o"inherit".
- Si omites
resourceGroupso pasas[], el usuario se elimina de todos los grupos de recursos. Para cambiar solo el rol de la organización y dejar los grupos de recursos sin cambios, pasa sus membresías actuales en los grupos de recursos (el cuerpo siempre establece tanto el rol de la organización como la lista de grupos de recursos).
Ejemplo (curl): establecer el rol de la organización en “read”, sin grupos de recursos (elimina cualquier grupo en el que el usuario estuviera previamente)
curl -s -X PUT \
-H "Authorization: Bearer $HF_TOKEN" \
-H "Content-Type: application/json" \
-d '{"role":"read","resourceGroups":[]}' \
"https://huggingface.co/api/organizations/my-org/members/member1/role"Ejemplo (curl): establecer el rol de la organización y los roles de los grupos de recursos (anula los grupos actuales)
curl -s -X PUT \
-H "Authorization: Bearer $HF_TOKEN" \
-H "Content-Type: application/json" \
-d '{"role":"write","resourceGroups":[{"id":"507f1f77bcf86cd799439011","role":"read"}]}' \
"https://huggingface.co/api/organizations/my-org/members/member2/role"Respuesta de éxito: estado 200 OK; cuerpo: { "success": true }.
Errores típicos
400— Cuerpo no válido (p. ej., rol o grupo de recursosidno válido).402— La organización no tiene un plan de suscripción.403— No permitido (p. ej., no tienes permisos de escritura en la organización, o un grupo de recursos no está en la organización).404— No se encontró la organización o el usuario.
Actualización de varios miembros
La API modifica un miembro por solicitud. No existe un punto de acceso por lotes. Para actualizar muchos miembros, llama al punto de acceso una vez por nombre de usuario (por ejemplo, desde una lista o un CSV).
Ejemplo: Bash – iterar sobre nombres de usuario, mismo rol para todos
ORG_NAME="my-org"
ROLE="read"
for username in member1 member2 member3 member4; do
echo "Setting $username to $ROLE ..."
curl -s -w "\n%{http_code}" -X PUT \
-H "Authorization: Bearer $HF_TOKEN" \
-H "Content-Type: application/json" \
-d "{\"role\":\"$ROLE\",\"resourceGroups\":[]}" \
"https://huggingface.co/api/organizations/$ORG_NAME/members/$username/role"
echo ""
doneEjemplo: Python – iterar sobre nombres de usuario
import os
import requests
BASE_URL = "https://huggingface.co"
HF_TOKEN = os.environ.get("HF_TOKEN", "")
def change_member_role(org_name: str, username: str, role: str, resource_groups: list | None = None):
payload = {"role": role, "resourceGroups": resource_groups or []}
r = requests.put(
f"{BASE_URL}/api/organizations/{org_name}/members/{username}/role",
headers={"Authorization": f"Bearer {HF_TOKEN}", "Content-Type": "application/json"},
json=payload,
)
if r.status_code != 200:
raise RuntimeError(f"{r.status_code}: {r.text}")
return r.json()
org_name = "my-org"
role = "read"
for username in ["member1", "member2", "member3", "member4"]:
print(f"Setting {username} to {role} ... ", end="")
try:
change_member_role(org_name, username, role)
print("OK")
except Exception as e:
print(f"Failed: {e}")Para asignar roles diferentes a cada usuario, itere sobre las parejas (username, role) (por ejemplo, desde un CSV) y llame a change_member_role para cada una.
API de grupos de recursos
Los siguientes puntos finales permiten listar grupos de recursos y agregar usuarios a ellos. Para cambiar el rol a nivel de organización de un miembro existente o sus asignaciones de grupo de recursos, consulte Cambiar el rol de un miembro mediante la API anterior.
Referencia de OpenAPI: Grupos de recursos
Tabla de contenido — Enfoques de la API:
| Objetivo | Sección |
|---|---|
| Agregar muchos usuarios a un grupo de recursos | Añadir usuarios a un grupo de recursos |
| Agrega los mismos usuarios a muchos grupos de recursos | Añadir en lote mediante un bucle sobre la API |
| Agrega distintos usuarios por grupo | Añadir en lote mediante un bucle sobre la API |
URL base y autenticación
- URL base:
https://huggingface.co - Authentication: Usa una de las siguientes opciones:
- Access token (recommended for scripts): Crea un token de grano fino con el permiso «Write access to organizations settings / member management» limitado a tu organización en https://huggingface.co/settings/tokens. Envíalo en la cabecera de la solicitud:
Authorization: Bearer <your_access_token> - Cookie de sesión: Si la llamada se realiza desde un navegador o herramienta que comparte la misma sesión que la interfaz de usuario del Hub, la cookie se envía automáticamente.
- Access token (recommended for scripts): Crea un token de grano fino con el permiso «Write access to organizations settings / member management» limitado a tu organización en https://huggingface.co/settings/tokens. Envíalo en la cabecera de la solicitud:
Listar grupos de recursos
Obtenga todos los grupos de recursos que puede gestionar para la organización. Utilice esto para obtener el id de cada grupo para las llamadas add-users.
Solicitud
GET /api/organizations/{org_name}/resource-groups
Authorization: Bearer <your_access_token>Ejemplo (curl)
curl -s -H "Authorization: Bearer $HF_TOKEN" \
"https://huggingface.co/api/organizations/my-org/resource-groups"Ejemplo de respuesta (recortada)
[
{
"id": "507f1f77bcf86cd799439011",
"name": "Cohort 2024",
"description": "Members in this group",
"users": [...],
"repos": [...]
}
]Use el id de cada grupo de recursos al agregar usuarios.
Agregar usuarios a un grupo de recursos
Añade uno o más usuarios a un grupo de recursos individual en una sola solicitud. Puedes enviar varios usuarios en la misma solicitud.
Solicitud
POST /api/organizations/{org_name}/resource-groups/{resource_group_id}/users
Authorization: Bearer <your_access_token>
Content-Type: application/json
{
"users": [
{ "user": "member1", "role": "read" },
{ "user": "member2", "role": "read" },
{ "user": "member3", "role": "write" }
]
}- Path parameters
org_name: identificador de la organización (p. ej.,my-org).resource_group_id: eliddel grupo de recursos (cadena hexadecimal de 24 caracteres del punto de extremo de lista).
- Body
users: Matriz de objetos. Cada objeto debe tener:user: nombre de usuario de Hugging Face username (obligatorio).role: Uno de"read","contributor","write","admin"o"inherit".
Ejemplo (curl)
curl -s -X POST \
-H "Authorization: Bearer $HF_TOKEN" \
-H "Content-Type: application/json" \
-d '{"users":[{"user":"member1","role":"read"},{"user":"member2","role":"read"}]}' \
"https://huggingface.co/api/organizations/my-org/resource-groups/507f1f77bcf86cd799439011/users"Éxito: estado 200 OK; el cuerpo es el objeto de grupo de recursos actualizado (incluye a los nuevos usuarios en users).
Errores típicos:
400— p. ej., usuario no encontrado, nombres de usuario duplicados o cuerpo no válido.403— No permitido (p. ej., no está en la organización o ya está en el grupo de recursos). El mensaje indicará si los usuarios no están en la organización o ya están en el grupo.
Agregar miembros por correo electrónico (solución alternativa)
El endpoint add-users solo acepta nombres de usuario de Hugging Face, no correos electrónicos. Si tienes una lista de correos electrónicos (p. ej., correos de los miembros), primero puedes resolver correo → nombre de usuario y luego llamar a la API add-users.
Tenga en cuenta que el filtrado de correo electrónico solo funciona cuando el dominio del correo coincide con uno de los dominios permitidos de la organización: el dominio de correo de la organización (Configuración → Cuenta → Dominio de correo de la organización) y/o los dominios permitidos de SSO de la organización (si SSO está configurado).
Paso 1 – Resolver el correo electrónico al nombre de usuario
GET /api/organizations/{org_name}/members?email={email}&limit=1
Authorization: Bearer <your_access_token>La respuesta es un array de miembros; cada miembro tiene user (nombre de usuario). Use user para la llamada de add-users.
Paso 2 – Agregar al grupo de recursos
Use el nombre de usuario del paso 1 en una solicitud normal de add-users:
POST /api/organizations/{org_name}/resource-groups/{resource_group_id}/users
Content-Type: application/json
Body: { "users": [{ "user": "<username from step 1>", "role": "read" }] }Ejemplo: un correo electrónico (bash)
ORG_NAME="my-org"
RG_ID="507f1f77bcf86cd799439011"
EMAIL="member@org.com"
# Step 1: look up member by email (domain must match org's Organization email domain or SSO allowed domains)
MEMBERS=$(curl -s -H "Authorization: Bearer $HF_TOKEN" \
"https://huggingface.co/api/organizations/$ORG_NAME/members?email=$EMAIL&limit=1")
USERNAME=$(echo "$MEMBERS" | jq -r '(.[0] // {} | .user // "")')
if [ -z "$USERNAME" ]; then
echo "No member found for $EMAIL"
exit 1
fi
# Step 2: add to resource group
curl -s -X POST -H "Authorization: Bearer $HF_TOKEN" -H "Content-Type: application/json" \
-d "{\"users\":[{\"user\":\"$USERNAME\",\"role\":\"read\"}]}" \
"https://huggingface.co/api/organizations/$ORG_NAME/resource-groups/$RG_ID/users"Ejemplo: varios correos electrónicos en un bucle (Python)
import os
import requests
BASE = "https://huggingface.co"
ORG = "my-org"
RG_ID = "507f1f77bcf86cd799439011"
ROLE = "read"
headers = {"Authorization": f"Bearer {os.environ['HF_TOKEN']}", "Content-Type": "application/json"}
emails = ["member1@org.com", "member2@org.com"]
for email in emails:
# Step 1: resolve email → username (email domain must match org's Organization email domain or SSO allowed domains)
r = requests.get(f"{BASE}/api/organizations/{ORG}/members", params={"email": email, "limit": 1}, headers=headers)
r.raise_for_status()
members = r.json()
if not members:
print(f"No member found for {email}")
continue
username = members[0]["user"]
# Step 2: add that user to the resource group
add_r = requests.post(
f"{BASE}/api/organizations/{ORG}/resource-groups/{RG_ID}/users",
headers=headers,
json={"users": [{"user": username, "role": ROLE}]},
)
if add_r.status_code == 200:
print(f"Added {username} ({email})")
else:
print(f"Failed {email}: {add_r.status_code} {add_r.text}")Si un usuario ya está en el grupo de recursos, la llamada de adición devuelve 403; el script lo reporta como un error y puedes omitir o ignorar ese caso si lo prefieres.
Limitación: El filtro de correo electrónico solo se aplica cuando la organización tiene configurado un dominio de correo de la organización y/o dominios permitidos para SSO, y el dominio del correo coincide con uno de ellos. De lo contrario, no se puede buscar por correo a través de la API de miembros; se necesitaría otra fuente para el mapeo de correo → nombre de usuario (p. ej., su propio directorio).
Agregar en lote mediante un bucle sobre la API
Puedes agregar muchos usuarios a un grupo de recursos en una o pocas solicitudes (por ejemplo, dividiendo tu lista de nombres de usuario en lotes), o agregar usuarios a varios grupos de recursos iterando sobre los grupos y llamando al punto de finalización add-users para cada uno.
Ejemplo: Bash – un grupo, varios usuarios en una sola solicitud
#!/bin/bash
# Add a list of users to a single resource group.
# Usage: ./add-users-to-rg.sh <org_name> <resource_group_id> <role>
ORG_NAME="${1:-my-org}"
RG_ID="${2:-507f1f77bcf86cd799439011}"
ROLE="${3:-read}"
USERS="member1 member2 member3 member4"
USERS_JSON=$(echo "$USERS" | tr ' ' '\n' | while read u; do
[ -n "$u" ] && echo "{\"user\":\"$u\",\"role\":\"$ROLE\"}"
done | paste -sd ',' -)
curl -s -w "\nHTTP_STATUS:%{http_code}" -X POST \
-H "Authorization: Bearer $HF_TOKEN" \
-H "Content-Type: application/json" \
-d "{\"users\":[$USERS_JSON]}" \
"https://huggingface.co/api/organizations/$ORG_NAME/resource-groups/$RG_ID/users"Ejemplo: Bash – iterar sobre varios grupos
# Get group IDs and add users to each
curl -s -H "Authorization: Bearer $HF_TOKEN" \
"https://huggingface.co/api/organizations/my-org/resource-groups" \
| jq -r '.[].id' \
| while read -r RG_ID; do
[ -z "$RG_ID" ] && continue
echo "Adding users to resource group $RG_ID ..."
curl -s -X POST -H "Authorization: Bearer $HF_TOKEN" -H "Content-Type: application/json" \
-d "{\"users\":[$USERS_JSON]}" \
"https://huggingface.co/api/organizations/my-org/resource-groups/$RG_ID/users"
doneEjemplo: Python – añadir en lote a uno o varios grupos
import os
import requests
BASE_URL = "https://huggingface.co"
HF_TOKEN = os.environ.get("HF_TOKEN", "")
def list_resource_groups(org_name: str):
r = requests.get(
f"{BASE_URL}/api/organizations/{org_name}/resource-groups",
headers={"Authorization": f"Bearer {HF_TOKEN}"},
)
r.raise_for_status()
return r.json()
def add_users_to_resource_group(org_name: str, resource_group_id: str, users_with_roles: list):
"""users_with_roles: list of {"user": "username", "role": "read"|"write"|"contributor"|"admin"}"""
r = requests.post(
f"{BASE_URL}/api/organizations/{org_name}/resource-groups/{resource_group_id}/users",
headers={"Authorization": f"Bearer {HF_TOKEN}", "Content-Type": "application/json"},
json={"users": users_with_roles},
)
if r.status_code != 200:
raise RuntimeError(f"Add users failed {r.status_code}: {r.text}")
return r.json()
# Example: same users added to every resource group
org_name = "my-org"
role = "read"
usernames = ["member1", "member2", "member3"]
users_with_roles = [{"user": u, "role": role} for u in usernames]
for rg in list_resource_groups(org_name):
add_users_to_resource_group(org_name, rg["id"], users_with_roles)Para una lista larga de nombres de usuario, divídala en lotes (p. ej., 50 por solicitud) y llame a la API una vez por lote para evitar cuerpos de solicitud grandes o tiempos de espera agotados.
Notas importantes
- Solo nombres de usuario — La API acepta nombres de usuario de Hugging Face, no correos electrónicos. Necesitas un mapeo de correo electrónico → nombre de usuario (por ejemplo, desde tu directorio o la lista de miembros de la organización) antes de llamar a la API.
- Los usuarios deben estar en la organización — Cada usuario en la solicitud ya debe ser miembro de la organización. De lo contrario, la solicitud devuelve
403con un mensaje que indica que algunos usuarios no están en la organización. - Idempotencia — Si un usuario ya está en el grupo de recursos, el backend puede devolver
403para esa solicitud. Tu script puede capturar los errores y continuar, o omitir los usuarios que ya están en el grupo si primero obtienes la lista deusersdel grupo. - Límites de tasa — Para lotes grandes, considere añadir una breve pausa entre las solicitudes (p. ej., 0,5–1 segundo) para evitar alcanzar los límites de tasa.
- Alcance del token — El token de acceso debe tener permisos suficientes para la organización (típicamente, al menos “Write access to organizations settings / member management”). Crea y almacena el token de forma segura; no lo commitees al control de versiones.
Configurar la incorporación automática a través de la API
Auto-join añade automáticamente a los miembros de la organización a un Resource Group con un rol especificado. Puedes activarlo o desactivarlo a través de la API y, opcionalmente, elegir si incluir a todos los miembros de la organización o solo a los miembros con permiso de Read+.
Activar la incorporación automática
POST /api/organizations/{org_name}/resource-groups/{resource_group_id}/settings
Authorization: Bearer <your_access_token>
Content-Type: application/json
{
"autoJoin": {
"enabled": true,
"role": "read",
"scope": "read_plus"
}
}- Path parameters
org_name: identificador de la organización (p. ej.,my-org).resource_group_id: El ID del grupo de recursos (cadena hexadecimal de 24 caracteres; obtenga los IDs desde el endpoint list resource groups).
- Body
role: El rol que se asignará a los miembros añadidos automáticamente. Uno de"read","contributor","write","admin"o"inherit".scope(opcional): qué miembros de la organización se deben añadir automáticamente. Use"all"para incluir a todos los miembros de la organización. Use"read_plus"para excluir a los miembros con el rol de organizaciónno_access. Si se omite, el valor predeterminado es"all".
Activar auto-join en un Resource Group existente agrega inmediatamente a los miembros actuales de la organización que coincidan con el alcance seleccionado (backfill).
Desactivar la unión automática
Envía la misma solicitud con "enabled": false. El campo role no es obligatorio al desactivar:
POST /api/organizations/{org_name}/resource-groups/{resource_group_id}/settings
Authorization: Bearer <your_access_token>
Content-Type: application/json
{
"autoJoin": {
"enabled": false
}
}Desactivar la incorporación automática no elimina a los miembros que fueron incorporados automáticamente con anterioridad. Solo impide que los nuevos miembros de la organización se añadan automáticamente. Los miembros existentes permanecen en el grupo de recursos.
Establecer límites de gasto a través de la API
Los límites de gasto establecen un tope para el gasto mensual de cómputo atribuido a un grupo de recursos. Configúrelos con el punto de actualización:
PATCH /api/organizations/{org_name}/resource-groups/{resource_group_id}
Authorization: Bearer <your_access_token>
Content-Type: application/json
{
"spendLimits": {
"total": 500000,
"spaces": 100000,
"jobs": 50000
}
}- Path parameters
org_name: identificador de la organización (p. ej.,my-org).resource_group_id: El ID del grupo de recursos (cadena hexadecimal de 24 caracteres; obtenga los IDs desde el endpoint list resource groups).
- Body
spendLimits: Límites mensuales en centavos. El ejemplo anterior establece un límite total de $5.000, con $1.000 para Spaces y $500 para Jobs.total: Límite del gasto combinado del grupo en todos los productos.inferenceProviders,spaces,jobs,endpoints: límites por producto, aplicados sobre el total. Se aplica el más estricto de los dos.
Solo se actualizan las claves que envías; las demás conservan su valor actual. Envía null para eliminar un límite:
PATCH /api/organizations/{org_name}/resource-groups/{resource_group_id}
Authorization: Bearer <your_access_token>
Content-Type: application/json
{
"spendLimits": {
"jobs": null
}
}Ejemplo (curl)
curl -s -X PATCH \
-H "Authorization: Bearer $HF_TOKEN" \
-H "Content-Type: application/json" \
-d '{"spendLimits": {"total": 500000}}' \
"https://huggingface.co/api/organizations/my-org/resource-groups/507f1f77bcf86cd799439011"La respuesta es el grupo de recursos actualizado, que incluye sus spendLimits.
Invitar colaboradores externos a través de la API
Las invitaciones externas permiten a los administradores de grupos de recursos invitar a usuarios externos a la organización a un grupo de recursos. Los invitados se unen como colaboradores externos con el rol de organización no_access. Se contabilizan en el número de asientos de pago de su organización.
Habilitar invitaciones externas
Los administradores de la organización pueden habilitar la configuración con:
POST /api/organizations/{org_name}/resource-groups/settings
Authorization: Bearer <your_access_token>
Content-Type: application/json
{
"allowExternalInvites": true
}- Body
allowExternalInvites(opcional): Si los administradores del grupo de recursos pueden invitar a usuarios de fuera de la organización.minRoleToCreate(opcional): Rol mínimo de la organización necesario para crear grupos de recursos.
Los campos omitidos se mantienen sin cambios. Use GET /api/organizations/{org_name}/resource-groups/settings para leer la configuración actual.
Invitar a un usuario
POST /api/organizations/{org_name}/resource-groups/{resource_group_id}/invite
Authorization: Bearer <your_access_token>
Content-Type: application/json
{
"username": "partner-user",
"role": "read"
}- Path parameters
org_name: identificador de la organización (p. ej.,my-org).resource_group_id: El ID del grupo de recursos (cadena hexadecimal de 24 caracteres; obtenga los IDs desde el endpoint list resource groups).
- Body
username: Nombre de usuario de un usuario existente de Hugging Face que aún no es miembro de la organización. Para agregar un miembro de la organización, use Agregar usuarios a un grupo de recursos en su lugar.role: Rol que obtiene el invitado en el grupo de recursos,"read"o"write".
El usuario recibe una invitación por correo electrónico y acceso al Resource Group después de aceptarla.
Gestionar invitaciones pendientes
- Lista:
GET /api/organizations/{org_name}/resource-groups/{resource_group_id}/invitations - Reenviar:
POST /api/organizations/{org_name}/resource-groups/{resource_group_id}/invitation/{invitation_id}/resend - Revocar:
DELETE /api/organizations/{org_name}/resource-groups/{resource_group_id}/invitation/{invitation_id}
También puedes consultar la especificación completa de OpenAPI
Errores típicos:
403— Las invitaciones externas no están habilitadas para la organización.409— El usuario ya es miembro de la organización o ya tiene una invitación pendiente a la misma.
Cambiar el tipo de cuenta de miembro a través de la API
Convierte a un miembro de la organización en un colaborador externo (no requiere SSO) o revierte su estado a miembro. Requiere un plan de pago y permiso Write (o Admin) en la organización. No está disponible en organizaciones con usuarios gestionados, donde los miembros se provisionan a través de SCIM.
Cambiar el tipo de cuenta de un usuario no modifica su rol. Consulte Cambiar el rol de un miembro mediante la API para cambiar el rol de un usuario.
PUT /api/organizations/{org_name}/members/{username}/account-type
Authorization: Bearer <your_access_token>
Content-Type: application/json
{
"accountType": "external"
}- Body
accountType:"external"para convertir al miembro en un colaborador externo, o"member"para revertir la conversión.