Hub documentation

プログラムによるユーザーアクセス制御の管理

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

プログラムによるユーザーアクセス制御の管理

このガイドでは、Hub API を使用して組織メンバーのロールおよびリソースグループのメンバーシップを管理する方法を説明します。具体的には、メンバーの組織ロールおよびリソースグループの割り当ての変更、リソースグループの一覧表示、グループへのユーザーの追加、およびバッチワークフローについてです。

目次:


APIでメンバーのロールを変更する

Hub API を使用して、メンバーの組織ロール(No Access / Read / Contributor / Write / Admin)を変更し、必要に応じてリソースグループ内のロールも変更できます。この API はリクエストごとに 1 人のメンバーのみを更新します。複数のメンバーのロールを変更するには、ループ内で 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>
    「組織設定への書き込みアクセス / メンバー管理」権限を組織にスコープしたファイングレインドトークンを 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: 変更対象のメンバーの Hugging Face username。
  • Body
    • role(必須):メンバーの組織レベルのロール。以下のいずれか:"no_access"、"read"、"contributor"、"write"、または"admin"。
    • resourceGroups ((省略可能): このユーザーのリソースグループ割り当ての配列。各項目:
      • id: リソースグループの ID(24 文字の 16 進文字列。リソースグループ一覧 APIから ID を取得します)。
      • 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はリクエストごとに1人のメンバーを変更します。一括処理用のエンドポイントは存在しません。多数のメンバーを更新するには、ユーザー名ごとに1回ずつエンドポイントを呼び出してください(リストや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

以下のエンドポイントを使用すると、リソースグループを一覧表示し、ユーザーを追加できます。既存のメンバーの組織レベルのロールやリソースグループの割り当てを変更するには、上記のAPIによるメンバーロールの変更を参照してください。

OpenAPI リファレンス: リソースグループ

目次 — APIアプローチ:

目標セクション
リソースグループに1つのユーザーを追加リソースグループにユーザーを追加する
同じユーザーを多数のリソースグループに追加しますAPIをループして一括追加
グループごとに異なるユーザーを追加APIをループして一括追加

ベースURLと認証

  • ベースURL: https://huggingface.co
  • Authentication: 次のいずれかを使用します:
    • Access token (recommended for scripts): 「組織設定への書き込みアクセス / メンバー管理」権限を組織にスコープしたファイングレイントークンを https://huggingface.co/settings/tokens. で作成します。リクエストヘッダーで送信します:
      Authorization: Bearer <your_access_token>
    • セッション Cookie: Hub UI と同じセッションを共有するブラウザやツールから呼び出す場合、Cookie は自動的に送信されます。

リソースグループのリスト表示

組織内で管理できるすべてのリソースグループを取得します。この結果を使用して、add-users 呼び出しで各グループの id を取得します。

リクエスト

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を使用します。

リソースグループにユーザーを追加する

1つのリクエストで、単一のリソースグループに1人以上のユーザーを追加します。同じリクエストで複数のユーザーを送信できます。

リクエスト

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文字の16進数文字列)。
  • 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 を解決してから、add-users API を呼び出せます。

メールフィルタリングは、メールのドメインが組織の許可ドメイン(Organization email domain(Settings → Account → Organization email domain)および/または組織のSSO allowed domains(SSOが設定されている場合))のいずれかと一致する場合にのみ機能することに注意してください。

ステップ 1 – メールアドレスからユーザー名を解決する

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

Response はメンバーの配列です。各メンバーには 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" }] }

例: 1通のメール (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}")

ユーザーがすでにリソースグループに存在する場合、追加呼び出しは403を返します。スクリプトはこれを失敗として報告しますが、必要に応じてそのケースをスキップまたは無視できます。

制限事項: メールフィルターは、組織に組織のメールドメインおよび/またはSSO許可ドメインが設定されており、かつメールのドメインがそれらのいずれかと一致する場合にのみ適用されます。それ以外の場合は、メンバーAPIを介してメールで検索することはできません。メールからユーザー名への対応付けには、別の情報源(例: 独自のディレクトリ)が必要です。

APIをループして一括追加

1つのリクエスト、または少数のリクエスト(例: ユーザー名の一覧をチャンクに分割する)で、1つのリソースグループに多数のユーザーを追加できます。また、グループをループして各グループに対してadd-usersエンドポイントを呼び出すことで、複数のリソースグループにユーザーを追加することもできます。

例: Bash – 1つのリクエストで1つのグループ、複数のユーザー

#!/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 – 1つまたは複数のグループにまとめて追加する

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を1回呼び出すことで、大きなリクエストボディやタイムアウトを回避してください。

重要な注意事項

  1. ユーザー名のみ — この API は Hugging Face のユーザー名を受け付け、メールアドレスは受け付けません。API を呼び出す前に、メールアドレスからユーザー名へのマッピング(ディレクトリや組織メンバーリストなどから取得)が必要です。
  2. ユーザーは組織に属している必要があります — リクエスト内のすべてのユーザーは、すでに組織のメンバーである必要があります。そうでない場合、リクエストは一部のユーザーが組織に属していないことを示すメッセージとともに403を返します。
  3. 冪等性 — ユーザーがすでにリソースグループに存在する場合、バックエンドは当該リクエストに対して403を返す可能性があります。スクリプトでエラーをキャッチして処理を続行するか、まずグループのusersリストを取得して、すでにグループに属しているユーザーをスキップすることもできます。
  4. レート制限 — 大規模なバッチ処理を行う場合は、レート制限に抵触しないよう、リクエスト間に短い遅延(例:0.5〜1秒)を挿入することを検討してください。
  5. トークンスコープ — アクセストークンは、組織に対して十分な権限(通常は少なくとも「組織設定への書き込みアクセス / メンバー管理」)を持つ必要があります。トークンを安全に作成して保存し、バージョン管理にコミットしないでください。

API を使用して自動参加を設定する

Auto-joinは、指定されたロールで組織メンバーをリソースグループに自動的に追加します。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
  • Body
    • role: 自動的に追加されるメンバーに割り当てるロール。"read"、"contributor"、"write"、"admin"、または"inherit"のいずれかです。
    • scope(オプション):自動的に追加する組織メンバーの範囲を指定します。すべての組織メンバーを含めるには "all" を使用します。no_access 組織ロールを持つメンバーを除外するには "read_plus" を使用します。省略した場合、デフォルトで "all" が使用されます。

既存の Resource Group で auto-join を有効にすると、選択したスコープに一致する現在の組織メンバーが即座に追加されます(バックフィル)。

自動参加の無効化

"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
  • Body
    • spendLimits: 月次制限 (セント単位). 上記の例では、総額 5,000 米ドルの制限を設定し、そのうち Spaces に 1,000 米ドル、Jobs に 500 米ドルを割り当てています。
      • total: 全製品にわたるグループの合計支出の上限。
      • inferenceProviders、spaces、jobs、endpoints: 製品ごとの制限。合計制限に上乗せして適用されます。2つの制限のうち、より厳しい方が優先されます。

送信したキーのみが更新され、その他のキーは現在の値を維持します。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組織ロールを持つ外部コラボレーターとして参加します。これらのユーザーは、組織の有料シート数にカウントされます。

外部からの招待を有効にする

Org管理者は、以下の設定を有効にできます:

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

{
  "allowExternalInvites": true
}
  • Body
    • allowExternalInvites(オプション):リソースグループの管理者が、組織外からユーザーを招待できるかどうかを指定します。
    • minRoleToCreate(オプション):Resource Groups を作成するために必要な組織の最小ロール。

省略されたフィールドは変更されません。現在の設定を読み取るには、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
  • Body
    • username: 組織のメンバーではない既存の Hugging Face ユーザーのユーザー名。組織のメンバーを追加するには、代わりに リソースグループにユーザーを追加する を使用してください。
    • role: 招待対象者がリソースグループで取得するロール。"read"または"write"。

ユーザーが招待を承認すると、メールによる招待と Resource Group へのアクセス権が与えられます。

保留中の招待を管理する

  • 一覧: 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 経由でメンバーがプロビジョニングされる、マネージドユーザーが有効な組織では利用できません。

ユーザーのアカウントタイプを変更しても、そのユーザーのロールは変更されません。ユーザーのロールを変更するには、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