Hub documentation

Gerenciamento Programático do Controle de Acesso do Usuário

Hub

API docs

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

Gerenciamento Programático do Controle de Acesso do Usuário

Este guia descreve como gerenciar os papéis dos membros da organização e a participação em grupos de recursos via Hub API: alterando o papel da organização de um membro e as atribuições de grupos de recursos, listando grupos de recursos, adicionando usuários a grupos e fluxos de trabalho em lote.

Sumário:

Alterar o papel de um membro via API — Defina o papel da organização e as atribuições de grupos de recursos de um membro (um membro por solicitação).
API de Grupos de Recursos — Lista grupos de recursos e adiciona usuários a eles.
Configurar o auto-join via API — Ative ou desative o auto-join em um Resource Group.
Convidar colaboradores externos via API — Convida usuários de fora da organização para um Resource Group.
Alterar o tipo de conta de membro via API — Converta um membro em colaborador externo, ou vice-versa.

Alterar o papel do membro via API

Você pode alterar o papel na organização de um membro (No Access / Read / Contributor / Write / Admin) e, opcionalmente, seus papéis em grupos de recursos usando a API do Hub. A API atualiza um membro por solicitação. Para alterar os papéis de vários membros, chame a API em um loop (exemplos abaixo).

Referência OpenAPI: PUT /api/organizations/{name}/members/{username}/role

Pré-requisitos

Sua organização deve ter um plano de assinatura (por exemplo, Team ou Enterprise). Caso contrário, o endpoint retorna 402.
Você deve estar autenticado como membro da organização com permissão de Write (ou Admin) na organização.
O usuário de destino já deve ser um membro da organização.

URL base e autenticação

URL base: https://huggingface.co
Authentication: Envie seu token no cabeçalho da solicitação:
```
Authorization: Bearer <your_access_token>
```
Crie um token de acesso granular com a permissão “Acesso de escrita às configurações da organização / gerenciamento de membros” limitado à sua organização em https://huggingface.co/settings/tokens.

Endpoint para alterar o papel do membro

Requisição

PUT /api/organizations/{org_name}/members/{username}/role
Authorization: Bearer <your_access_token>
Content-Type: application/json

{
  "role": "read",
  "resourceGroups": []
}

Path parameters
- org_name: Slug da organização (ex.: my-org).
- username: username do Hugging Face do membro cujo papel você está alterando.
Body
- role (obrigatório): o papel do membro no nível da organização. Um dos seguintes: "no_access", "read", "contributor", "write" ou "admin".
- resourceGroups (opcional): Matriz de atribuições de grupos de recursos para este usuário. Cada item:
  - id: ID do grupo de recursos (string hexadecimal de 24 caracteres; obtenha os IDs na API de lista de grupos de recursos).
  - role: Função naquele grupo de recursos: "read", "contributor", "write", "admin" ou "inherit".
- Se você omitir resourceGroups ou passar [], o usuário será removido de todos os grupos de recursos. Para alterar apenas o papel na organização e manter os grupos de recursos inalterados, passe as atualizações de membros dos grupos de recursos atuais (o corpo sempre define tanto o papel na organização quanto a lista de grupos de recursos).

Exemplo (curl) – definir o papel da organização como “read”, sem grupos de recursos (remove qualquer grupo em que o usuário estava anteriormente)

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"

Exemplo (curl) – definir papel da organização e papéis do grupo de recursos (sobrescreve quaisquer grupos atuais)

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"

Resposta de sucesso: Status 200 OK; corpo: { "success": true }.

Erros típicos

400 — Corpo inválido (por exemplo, papel ou grupo de recursos id inválido).
402 — A organização não possui um plano de assinatura.
403 — Não permitido (por exemplo, você não tem permissão de Write na organização, ou um grupo de recursos não está na organização).
404 — Organização ou usuário não encontrado.

Atualizando vários membros

A API altera um membro por solicitação. Não há um endpoint em lote. Para atualizar muitos membros, chame o endpoint uma vez por nome de usuário (por exemplo, a partir de uma lista ou CSV).

Exemplo: Bash – iteração sobre nomes de usuário, mesma função 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 ""
done

Exemplo: Python – iteração sobre nomes de usuário

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 diferentes papéis por usuário, itere sobre os pares (username, role) (por exemplo, de um CSV) e chame change_member_role para cada um.

API de Grupos de Recursos

Os seguintes endpoints permitem listar grupos de recursos e adicionar usuários a eles. Para alterar o papel de nível de organização de um membro existente ou suas atribuições de grupo de recursos, consulte Alterar papel do membro via API acima.

Referência OpenAPI: Grupos de recursos

Sumário — Abordagens de API:

Objetivo	Seção
Adicionar muitos usuários a um grupo de recursos	Adicionar usuários a um grupo de recursos
Adicione os mesmos usuários a muitos grupos de recursos	Adição em lote por meio de um loop sobre a API
Adicionar usuários diferentes por grupo	Adição em lote por meio de um loop sobre a API

URL base e autenticação

URL base: https://huggingface.co
Authentication: Use uma das opções:
- Access token (recommended for scripts): Crie um token de acesso granular com a permissão “Write access to organizations settings / member management” escopada para sua organização em https://huggingface.co/settings/tokens. Envie-o no cabeçalho da requisição:
```
Authorization: Bearer <your_access_token>
```
- Cookie de sessão: Se a chamada for feita a partir de um navegador ou ferramenta que compartilha a mesma sessão que a interface do Hub, o cookie é enviado automaticamente.

Listar grupos de recursos

Obtenha todos os grupos de recursos que você pode gerenciar para a organização. Use isso para obter o id de cada grupo para as chamadas add-users.

Requisição

GET /api/organizations/{org_name}/resource-groups
Authorization: Bearer <your_access_token>

Exemplo (curl)

curl -s -H "Authorization: Bearer $HF_TOKEN" \
  "https://huggingface.co/api/organizations/my-org/resource-groups"

Exemplo de resposta (reduzido)

[
  {
    "id": "507f1f77bcf86cd799439011",
    "name": "Cohort 2024",
    "description": "Members in this group",
    "users": [...],
    "repos": [...]
  }
]

Use o id de cada grupo de recursos ao adicionar usuários.

Adicionar usuários a um grupo de recursos

Adicione um ou mais usuários a um único grupo de recursos em uma única solicitação. Você pode enviar vários usuários na mesma solicitação.

Requisição

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: Slug da organização (ex.: my-org).
- resource_group_id: o id do grupo de recursos (string hexadecimal de 24 caracteres do endpoint de listagem).
Body
- users: Array de objetos. Cada objeto deve ter:
  - user: nome de usuário do Hugging Face username (obrigatório).
  - role: Um dos valores "read", "contributor", "write", "admin" ou "inherit".

Exemplo (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"

Sucesso: Status 200 OK; o corpo é o objeto de grupo de recursos atualizado (inclui os novos usuários em users).

Erros típicos:

400 — por exemplo, usuário não encontrado, nomes de usuário duplicados ou corpo inválido.
403 — Não permitido (por exemplo, não está na organização ou já está no grupo de recursos). A mensagem indicará se os usuários não estão na organização ou já estão no grupo.

Adicionando membros por e-mail (solução alternativa)

O endpoint add-users aceita apenas nomes de usuário do Hugging Face, não e-mails. Se você tiver uma lista de e-mails (por exemplo, e-mails de membros), você pode primeiro resolver e-mail → nome de usuário e, em seguida, chamar a API add-users.

Observe que a filtragem de e-mails somente funciona quando o domínio do e-mail corresponde a um dos domínios permitidos da organização: o Domínio de e-mail da organização (Configurações → Conta → Domínio de e-mail da organização) e/ou os Domínios permitidos para SSO da organização (se o SSO estiver configurado).

Etapa 1 – Resolver o e-mail para o nome de usuário

GET /api/organizations/{org_name}/members?email={email}&limit=1
Authorization: Bearer <your_access_token>

A resposta é um array de membros; cada membro tem user (nome de usuário). Use user para a chamada de adição de usuários.

Etapa 2 – Adicionar ao grupo de recursos

Use o nome de usuário da etapa 1 em uma solicitação normal de adição de usuários:

POST /api/organizations/{org_name}/resource-groups/{resource_group_id}/users
Content-Type: application/json
Body: { "users": [{ "user": "<username from step 1>", "role": "read" }] }

Exemplo: um e-mail (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"

Exemplo: vários e-mails em um loop (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}")

Se um usuário já estiver no grupo de recursos, a chamada de adição retorna 403; o script relata isso como uma falha e você pode ignorar ou pular esse caso, se preferir.

Limitação: O filtro de e-mail só é aplicado quando a organização possui um Domínio de e-mail da organização e/ou Domínios permitidos para SSO configurados, e o domínio do e-mail corresponde a um deles. Caso contrário, não é possível buscar por e-mail via a API de membros; será necessário outra fonte para e-mail → nome de usuário (por exemplo, seu próprio diretório).

Adicionar em lote fazendo loop pela API

Você pode adicionar muitos usuários a um grupo de recursos em uma ou poucas solicitações (por exemplo, dividindo sua lista de nomes de usuário em lotes) ou adicionar usuários a vários grupos de recursos iterando sobre os grupos e chamando o endpoint add-users para cada um.

Exemplo: Bash – um grupo, múltiplos usuários em uma única solicitação

#!/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"

Exemplo: Bash – iteração sobre múltiplos 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"
    done

Exemplo: Python – adicionar em lote a um ou vários 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 uma longa lista de nomes de usuário, divida-a em blocos (por exemplo, 50 por solicitação) e chame a API uma vez por bloco para evitar corpos de solicitação grandes ou timeouts.

Observações importantes

Apenas nomes de usuário — A API aceita nomes de usuário do Hugging Face, não e-mails. Você precisa de um mapeamento de e-mail → nome de usuário (por exemplo, do seu diretório ou da lista de membros da organização) antes de chamar a API.
Os usuários devem estar na organização — Cada usuário na solicitação já deve ser membro da organização. Caso contrário, a solicitação retorna 403 com uma mensagem indicando que alguns usuários não estão na organização.
Idempotência — Se um usuário já estiver no grupo de recursos, o backend pode retornar 403 para essa solicitação. Seu script pode capturar erros e continuar, ou pular usuários que já estão no grupo se você primeiro buscar a lista de users do grupo.
Limites de taxa — Para lotes grandes, considere adicionar uma breve pausa entre as solicitações (por exemplo, 0,5–1 segundo) para evitar atingir os limites de taxa.
Escopo do token — O token de acesso deve ter permissões suficientes para a organização (tipicamente, pelo menos “Acesso de escrita às configurações da organização / gerenciamento de membros”). Crie e armazene o token com segurança; não o versione em um controle de versão.

Configure o auto-join via API

Auto-join adiciona automaticamente membros da organização a um Resource Group em um papel especificado. Você pode ativá-lo ou desativá-lo via API e, opcionalmente, escolher se deseja incluir todos os membros da organização ou apenas os membros com permissão de Read+.

Ativar auto-join

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: Slug da organização (ex.: my-org).
- resource_group_id: O ID do Resource Group (string hexadecimal de 24 caracteres; obtenha os IDs no endpoint list resource groups).
Body
- role: A função a ser atribuída aos membros adicionados automaticamente. Uma de "read", "contributor", "write", "admin" ou "inherit".
- scope (opcional): Quais membros da organização adicionar automaticamente. Use "all" para incluir todos os membros da organização. Use "read_plus" para excluir membros com o papel de organização no_access. O padrão é "all" quando omitido.

Ativar o auto-join em um Resource Group existente adiciona imediatamente os membros atuais da organização que correspondem ao escopo selecionado (backfill).

Desativar o auto-join

Envie a mesma solicitação com "enabled": false. O campo role não é obrigatório ao desativar:

POST /api/organizations/{org_name}/resource-groups/{resource_group_id}/settings
Authorization: Bearer <your_access_token>
Content-Type: application/json

{
  "autoJoin": {
    "enabled": false
  }
}

Desativar o auto-join não remove os membros que foram adicionados automaticamente anteriormente. Ele apenas impede que novos membros da organização sejam adicionados automaticamente. Os membros existentes permanecem no Resource Group.

Defina limites de gastos via API

Limites de gastos limitam o gasto mensal de computação atribuído a um Resource Group. Defina-os com o endpoint de atualização:

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: Slug da organização (ex.: my-org).
- resource_group_id: O ID do Resource Group (string hexadecimal de 24 caracteres; obtenha os IDs no endpoint list resource groups).
Body
- spendLimits: Limites mensais em centavos. O exemplo acima define um limite total de US$ 5.000, com US$ 1.000 para Spaces e US$ 500 para Jobs.
  - total: Limite para o gasto combinado do grupo em todos os produtos.
  - inferenceProviders, spaces, jobs, endpoints: Limites por produto, aplicados por cima do total. O mais restritivo dos dois prevalece.

Apenas as chaves que você envia são atualizadas; as demais mantêm seu valor atual. Envie null para remover um limite:

PATCH /api/organizations/{org_name}/resource-groups/{resource_group_id}
Authorization: Bearer <your_access_token>
Content-Type: application/json

{
  "spendLimits": {
    "jobs": null
  }
}

Exemplo (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"

A resposta é o grupo de recursos atualizado, incluindo seus spendLimits.

Convide colaboradores externos via API

Convites externos permitem que administradores de grupos de recursos convidem usuários de fora da organização para um Grupo de Recursos. Os convidados se juntam como colaboradores externos com o papel de organização no_access. Eles contam para o número de assentos pagos na sua organização.

Ativar convites externos

Administradores de organização podem ativar a configuração com:

POST /api/organizations/{org_name}/resource-groups/settings
Authorization: Bearer <your_access_token>
Content-Type: application/json

{
  "allowExternalInvites": true
}

Body
- allowExternalInvites (opcional): Se os administradores do grupo de recursos podem convidar usuários de fora da organização.
- minRoleToCreate (opcional): papel mínimo da organização necessário para criar Resource Groups.

Os campos omitidos permanecem inalterados. Use GET /api/organizations/{org_name}/resource-groups/settings para ler as configurações atuais.

Convidar um usuário

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: Slug da organização (ex.: my-org).
- resource_group_id: O ID do Resource Group (string hexadecimal de 24 caracteres; obtenha os IDs no endpoint list resource groups).
Body
- username: Nome de usuário de um usuário existente do Hugging Face que ainda não é membro da organização. Para adicionar um membro da organização, use Adicionar usuários a um grupo de recursos em vez disso.
- role: Função que o convidado recebe no Resource Group, "read" ou "write".

O usuário recebe um convite por e-mail e acesso ao Resource Group após aceitá-lo.

Gerenciar convites pendentes

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
Revogar: DELETE /api/organizations/{org_name}/resource-groups/{resource_group_id}/invitation/{invitation_id}

Você também pode consultar a especificação OpenAPI completa

Erros típicos:

403 — Convites externos não estão habilitados para a organização.
409 — O usuário já é membro da organização ou já possui um convite pendente para ela.

Alterar o tipo de conta de membro via API

Transforme um membro da organização em um colaborador externo (sem necessidade de SSO) ou converta-o de volta em membro. Exige um plano pago e permissão de Write (ou Admin) na organização. Não disponível em organizações com usuários gerenciados, onde os membros são provisionados por meio do SCIM.

Alterar o tipo de conta de um usuário não altera sua função. Consulte Alterar a função de um membro via API para alterar a função de um usuário.

PUT /api/organizations/{org_name}/members/{username}/account-type
Authorization: Bearer <your_access_token>
Content-Type: application/json

{
  "accountType": "external"
}

Body
- accountType: "external" para converter o membro em colaborador externo, ou "member" para convertê-lo de volta.

Update on GitHub

←Controle de Acesso Avançado (Grupos de Recursos) Verificação de Malware→