Hub documentation

Управление программным доступом пользователей

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

Управление программным доступом пользователей

В этом руководстве описано, как управлять ролями участников организации и членством в группах ресурсов через Hub API: изменение роли участника в организации и назначений в группах ресурсов, получение списка групп ресурсов, добавление пользователей в группы и пакетные рабочие процессы.

Содержание:

Изменение роли участника через API — Установите роль участника в организации и назначения в группы ресурсов (один участник на запрос).
API групп ресурсов — список групп ресурсов и добавление пользователей в них.
Настройка автоприсоединения через API — Включение или отключение автоприсоединения для группы ресурсов.
Приглашение внешних соавторов через API — приглашение пользователей извне организации в группу ресурсов.
Изменение типа учётной записи участника через API — Преобразование участника во внешнего соавтора или обратно.

Изменение роли участника через API

Вы можете изменить роль в организации (No Access / Read / Contributor / Write / Admin) и, при необходимости, роли в группах ресурсов с помощью Hub API. API обновляет одного участника за запрос. Чтобы изменить роли для нескольких участников, вызывайте API в цикле (примеры ниже).

Справочник OpenAPI: PUT /api/organizations/{name}/members/{username}/role

Предварительные требования

Ваша организация должна иметь тарифный план (например, Team или Enterprise). В противном случае конечная точка возвращает 402.
Вы должны быть аутентифицированы как член организации с правом Write (или Admin) на организацию.
Целевой пользователь уже должен быть участником организации.

Базовый URL и аутентификация

Базовый URL: https://huggingface.co
Authentication: Передайте токен в заголовке запроса:
```
Authorization: Bearer <your_access_token>
```
Создайте токен с ограниченным доступом, имеющий разрешение «Write access to organizations settings / member management» для вашей организации на https://huggingface.co/settings/tokens.

Эндпоинт для изменения роли участника

Запрос

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

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

Path parameters
- org_name: Идентификатор организации (например, my-org).
- username: username участника, роль которого вы меняете.
Body
- role (обязательный): роль участника на уровне организации. Одно из значений: "no_access", "read", "contributor", "write" или "admin".
- resourceGroups (необязательный): массив назначений групп ресурсов для этого пользователя. Каждый элемент:
  - id: идентификатор группы ресурсов (шестнадцатеричная строка из 24 символов; идентификаторы можно получить через API списка групп ресурсов).
  - role: Роль в этой группе ресурсов: "read", "contributor", "write", "admin" или "inherit".
- Если вы опустите resourceGroups или передадите [], пользователь будет удалён из всех групп ресурсов. Чтобы изменить только роль в организации и оставить группы ресурсов без изменений, передайте их текущие членства в группах ресурсов (тело запроса всегда устанавливает и роль в организации, и список групп ресурсов).

Пример (curl) – установить роль организации на «read», без групп ресурсов (удаляет все, в которых пользователь состоял ранее)

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"

Пример (curl) – установка роли организации и ролей группы ресурсов (заменяет текущие группы)

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"

Ответ об успешном выполнении: статус 200 OK; тело: { "success": true }.

Типичные ошибки

400 — Неверное тело запроса (например, неверная роль или идентификатор группы ресурсов id).
402 — Организация не имеет подписки.
403 — Запрещено (например, у вас нет прав Write в организации или группа ресурсов не входит в организацию).
404 — Организация или пользователь не найдены.

Обновление нескольких членов

API изменяет одного участника за запрос. Массовый эндпоинт отсутствует. Чтобы обновить многих участников, вызывайте эндпоинт по одному для каждого имени пользователя (например, из списка или CSV).

Пример: Bash – цикл по именам пользователей, одна и та же роль для всех

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

Пример: Python – цикл по именам пользователей

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}")

Для разных ролей для каждого пользователя пройдите по парам (username, role) (например, из CSV) и вызовите change_member_role для каждой.

API групп ресурсов

Следующие конечные точки позволяют получить список групп ресурсов и добавить в них пользователей. Чтобы изменить роль участника на уровне организации или его назначения в группы ресурсов, см. раздел Change member role via API выше.

Справочник OpenAPI: Группы ресурсов

Содержание — подходы к API:

Цель	Раздел
Добавление множества пользователей в одну группу ресурсов	Добавление пользователей в группу ресурсов
Добавьте одних и тех же пользователей в многие группы ресурсов	Массовое добавление с помощью цикла по API
Добавляйте разных пользователей в каждую группу	Массовое добавление с помощью цикла по API

Базовый URL и аутентификация

Базовый URL: https://huggingface.co
Authentication: Используйте один из следующих вариантов:
- Access token (recommended for scripts): Создайте токен с ограниченным доступом, имеющий разрешение «Write access to organizations settings / member management» в рамках вашей организации, по адресу https://huggingface.co/settings/tokens. Передайте его в заголовке запроса:
```
Authorization: Bearer <your_access_token>
```
- Сессионная cookie: Если запрос отправляется из браузера или инструмента, использующего ту же сессию, что и интерфейс Hub, cookie передаётся автоматически.

Список групп ресурсов

Получите все группы ресурсов, которыми вы можете управлять в организации. Используйте это для получения id каждой группы для вызовов add-users.

Запрос

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

Пример (curl)

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

Пример ответа (сокращённый)

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

Используйте id каждой группы ресурсов при добавлении пользователей.

Добавление пользователей в группу ресурсов

Добавьте одного или нескольких пользователей в одну группу ресурсов одним запросом. Вы можете отправить несколько пользователей в одном и том же запросе.

Запрос

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: Идентификатор организации (например, my-org).
- resource_group_id: id группы ресурсов (шестнадцатеричная строка из 24 символов из списка конечной точки).
Body
- users: Массив объектов. Каждый объект должен содержать:
  - user: имя пользователя Hugging Face username (обязательное поле).
  - role: одно из значений "read", "contributor", "write", "admin" или "inherit".

Пример (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"

Успех: статус 200 OK; тело ответа содержит обновленный объект группы ресурсов (включает новых пользователей в users).

Типичные ошибки:

400 — например, пользователь не найден, дубликаты имён пользователей или некорректное тело запроса.
403 — Запрещено (например, пользователь не состоит в организации или уже входит в группу ресурсов). В сообщении будет указано, что пользователи не входят в организацию или уже состоят в группе.

Добавление участников по электронной почте (обходной путь)

Эндпоинт add-users принимает только имена пользователей Hugging Face, а не адреса электронной почты. Если у вас есть список адресов электронной почты (например, адреса участников), сначала разрешите email → username, а затем вызовите API add-users.

Обратите внимание, что фильтрация по электронной почте работает только в том случае, если домен адреса электронной почты совпадает с одним из разрешённых доменов организации: домен электронной почты организации (Настройки → Аккаунт → Домен электронной почты организации) и/или разрешённые домены SSO организации (если настроен SSO).

Шаг 1 – Определение имени пользователя по адресу электронной почты

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

Ответ представляет собой массив участников; у каждого участника есть user (имя пользователя). Используйте user для вызова добавления пользователей.

Шаг 2 – Добавление в группу ресурсов

Используйте имя пользователя из шага 1 в обычном запросе на добавление пользователей:

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

Пример: одно письмо (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"

Пример: несколько писем в цикле (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}")

Если пользователь уже входит в группу ресурсов, вызов add возвращает 403; скрипт сообщает об этом как об ошибке, и при необходимости вы можете пропустить или игнорировать этот случай.

Ограничение: Фильтр по электронной почте применяется только в том случае, если для организации заданы домен электронной почты организации и/или домены, разрешённые для SSO, и домен адреса электронной почты совпадает с одним из них. В противном случае поиск по электронной почте через API участников невозможен; для сопоставления email → username потребуется другой источник данных (например, собственный каталог).

Массовое добавление с помощью цикла по API

Вы можете добавить множество пользователей в один ресурсный группой за один или несколько запросов (например, разбив список имён пользователей на части) или добавить пользователей в несколько ресурсных групп, перебирая группы в цикле и вызывая endpoint add-users для каждой.

Пример: Bash – одна группа, несколько пользователей в одном запросе

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

Пример: Bash – цикл по нескольким группам

# 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

Пример: Python – массовое добавление в одну или несколько групп

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)

Для длинного списка имён пользователей разбивайте их на части (например, по 50 на запрос) и вызывайте API по одному разу для каждой части, чтобы избежать больших размеров тела запроса или таймаутов.

Важные примечания

Только имена пользователей — API принимает имена пользователей Hugging Face, а не адреса электронной почты. Перед вызовом API вам потребуется сопоставление email → имя пользователя (например, из вашего каталога или списка участников организации).
Пользователи должны состоять в организации — каждый пользователь из запроса уже должен быть членом организации. В противном случае запрос вернёт 403 с сообщением о том, что некоторые пользователи не входят в организацию.
Идемпотентность — если пользователь уже входит в группу ресурсов, бэкенд может вернуть 403 для этого запроса. Ваш скрипт может перехватывать ошибки и продолжать работу или пропускать пользователей, уже находящихся в группе, если сначала получить список users группы.
Ограничения частоты запросов — Для больших пакетов данных рассмотрите возможность добавления короткой задержки между запросами (например, 0,5–1 секунда), чтобы не превышать лимиты частоты.
Область действия токена — Токен доступа должен иметь достаточные разрешения для организации (как правило, не менее «Write access to organizations settings / member management»). Создайте и безопасно храните токен; не добавляйте его в систему контроля версий.

Настройка авто-присоединения через API

Auto-join автоматически добавляет участников организации в Resource Group с указанной ролью. Вы можете включить или отключить эту функцию через API и при необходимости выбрать, включать ли всех участников организации или только участников с ролью Read+.

Включить автоматическое присоединение

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: Идентификатор организации (например, my-org).
- resource_group_id: идентификатор группы ресурсов (шестнадцатеричная строка из 24 символов; идентификаторы можно получить с помощью эндпоинта list resource groups).
Body
- role: Роль, назначаемая автоматически добавляемым участникам. Одно из значений: "read", "contributor", "write", "admin" или "inherit".
- scope (необязательный): какие участники организации должны добавляться автоматически. Используйте "all", чтобы включить всех участников организации. Используйте "read_plus", чтобы исключить участников с ролью no_access в организации. По умолчанию используется "all", если параметр не указан.

Включение автоприсоединения в существующей группе ресурсов немедленно добавляет текущих участников организации, соответствующих выбранному диапазону (backfill).

Отключить автоматическое присоединение

Отправьте тот же запрос с "enabled": false. Поле role не требуется при отключении:

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

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

Отключение автодобавления не удаляет участников, которые были добавлены ранее автоматически. Это лишь предотвращает автоматическое добавление новых участников организации. Существующие участники остаются в группе ресурсов.

Установка лимитов расходов через API

Лимиты расходов ограничивают ежемесячные вычислительные расходы, приписываемые группе ресурсов. Настройте их с помощью эндпоинта обновления:

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: Идентификатор организации (например, my-org).
- resource_group_id: идентификатор группы ресурсов (шестнадцатеричная строка из 24 символов; идентификаторы можно получить с помощью эндпоинта list resource groups).
Body
- spendLimits: Месячные лимиты в центах. В примере выше установлен общий лимит в 5000 долларов, из которых 1000 долларов на Spaces и 500 долларов на Jobs.
  - total: Ограничение на совокупные расходы группы по всем продуктам.
  - inferenceProviders, spaces, jobs, endpoints: лимиты по каждому продукту, применяемые поверх общего лимита. Действует более строгий из двух.

Обновляются только те ключи, которые вы отправляете, остальные сохраняют своё текущее значение. Отправьте null, чтобы снять ограничение:

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

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

Пример (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"

Ответом является обновлённая группа ресурсов, включая её spendLimits.

Приглашение внешних соавторов через API

Внешние приглашения позволяют администраторам групп ресурсов приглашать пользователей извне организации в группу ресурсов. Приглашённые присоединяются как внешние участники с ролью организации no_access. Они учитываются в количестве платных мест в вашей организации.

Включить внешние приглашения

Администраторы организации могут включить настройку с помощью:

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

{
  "allowExternalInvites": true
}

Body
- allowExternalInvites (необязательный): разрешает ли администраторам группы ресурсов приглашать пользователей извне организации.
- minRoleToCreate (необязательный): минимальная роль в организации, необходимая для создания групп ресурсов.

Опущенные поля остаются без изменений. Используйте GET /api/organizations/{org_name}/resource-groups/settings, чтобы прочитать текущие настройки.

Пригласить пользователя

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: Идентификатор организации (например, my-org).
- resource_group_id: идентификатор группы ресурсов (шестнадцатеричная строка из 24 символов; идентификаторы можно получить с помощью эндпоинта list resource groups).
Body
- username: Имя пользователя существующего пользователя Hugging Face, который ещё не является членом организации. Чтобы добавить участника организации, используйте вместо этого Добавление пользователей в группу ресурсов.
- role: Роль, которую получает приглашённый в группе ресурсов, "read" или "write".

Пользователь получает приглашение по электронной почте и доступ к группе ресурсов после того, как примет его.

Управление ожидающими приглашениями

Список: GET /api/organizations/{org_name}/resource-groups/{resource_group_id}/invitations
Повторная отправка: POST /api/organizations/{org_name}/resource-groups/{resource_group_id}/invitation/{invitation_id}/resend
Отозвать: DELETE /api/organizations/{org_name}/resource-groups/{resource_group_id}/invitation/{invitation_id}

Вы также можете ознакомиться с полной спецификацией OpenAPI

Типичные ошибки:

403 — Внешние приглашения не включены для организации.
409 — Пользователь уже является членом организации или уже имеет ожидающее приглашение в неё.

Изменение типа учётной записи участника через API

Сделайте участника организации внешним соавтором (без необходимости SSO) или верните его в статус участника. Требуется платный тариф и право Write (или Admin) на организацию. Недоступно в организациях с управляемыми пользователями, где участники создаются через SCIM.

Изменение типа аккаунта пользователя не меняет его роль. Чтобы изменить роль пользователя, см. Change member role via API.

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

{
  "accountType": "external"
}

Body
- accountType: "external", чтобы сделать участника внешним соавтором, или "member", чтобы вернуть его обратно.

Update on GitHub

←Расширенный контроль доступа (группы ресурсов) Сканирование на вредоносное ПО→