Hugging Face User Management API Guide

Auth method: Bearer token (User Access Token passed in Authorization header)

Setup steps

1. Log in to huggingface.co and navigate to Settings > Access Tokens.
2. Click 'New token', choose a token type (read, write, or fine-grained), and assign desired scopes.
3. Copy the generated token; it is shown only once.
4. Pass the token in API requests via the header: Authorization: Bearer .

Required scopes

Get authenticated user (whoami)

• Method: GET
• URL: https://huggingface.co/api/whoami-v2
• Watch out for: Returns data for the token owner only; cannot retrieve arbitrary users' emails without SCIM or org-admin context.

Request example

GET /api/whoami-v2
Authorization: Bearer <token>

Response example

{
  "name": "jdoe",
  "fullname": "Jane Doe",
  "email": "jane@example.com",
  "type": "user",
  "isPro": false,
  "orgs": [{"name": "my-org", "role": "admin"}]
}

List organization members

• Method: GET
• URL: https://huggingface.co/api/organizations/{org}/members
• Watch out for: Requires a token with read-org scope and the caller must be a member of the organization.

Request example

GET /api/organizations/my-org/members
Authorization: Bearer <token>

Response example

[
  {"user": "jdoe", "role": "admin"},
  {"user": "asmith", "role": "write"}
]

Add member to organization

• Method: POST
• URL: https://huggingface.co/api/organizations/{org}/members/{username}
• Watch out for: Caller must be an org admin. The invited user must already have a Hugging Face account.

Request example

POST /api/organizations/my-org/members/asmith
Authorization: Bearer <token>
Content-Type: application/json
{"role": "write"}

Response example

{
  "user": "asmith",
  "role": "write"
}

Remove member from organization

• Method: DELETE
• URL: https://huggingface.co/api/organizations/{org}/members/{username}
• Watch out for: Removing the last admin is blocked. Org owner cannot be removed via API.

Request example

DELETE /api/organizations/my-org/members/asmith
Authorization: Bearer <token>

Response example

HTTP 204 No Content

Update member role in organization

• Method: PATCH
• URL: https://huggingface.co/api/organizations/{org}/members/{username}
• Watch out for: Valid roles are 'admin', 'write', 'contributor', 'read'. Invalid role values return HTTP 400.

Request example

PATCH /api/organizations/my-org/members/asmith
Authorization: Bearer <token>
Content-Type: application/json
{"role": "admin"}

Response example

{
  "user": "asmith",
  "role": "admin"
}

Get organization details

• Method: GET
• URL: https://huggingface.co/api/organizations/{org}
• Watch out for: Some fields (e.g., isEnterprise) only appear for Enterprise Hub organizations.

Request example

GET /api/organizations/my-org
Authorization: Bearer <token>

Response example

{
  "name": "my-org",
  "fullname": "My Organization",
  "type": "org",
  "isEnterprise": true
}

List pending organization invitations

• Method: GET
• URL: https://huggingface.co/api/organizations/{org}/pending-members
• Watch out for: Only accessible to org admins. Not explicitly documented in all API reference versions; behavior may change.

Request example

GET /api/organizations/my-org/pending-members
Authorization: Bearer <token>

Response example

[
  {"user": "newuser", "role": "write", "status": "pending"}
]

SCIM: List users (Enterprise only)

• Method: GET
• URL: https://huggingface.co/api/organizations/{org}/scim/v2/Users
• Watch out for: Requires Enterprise Hub plan and SSO enabled. SCIM token is generated separately from user access tokens in org settings.

Request example

GET /api/organizations/my-org/scim/v2/Users?startIndex=1&count=20
Authorization: Bearer <scim-token>

Response example

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "totalResults": 5,
  "Resources": [{"id": "abc123", "userName": "jdoe"}]
}

• Rate limits: Hugging Face does not publish explicit per-endpoint rate limit numbers in its public API docs. Inference API endpoints have documented rate limits that vary by plan; Hub REST API limits are not explicitly documented.
• Rate-limit headers: No
• Retry-After header: No
• Rate-limit notes: Official docs do not specify rate-limit response headers for the Hub REST API. HTTP 429 may be returned when limits are exceeded. Inference API rate limits are documented separately at huggingface.co/docs/api-inference.
• Pagination method: offset
• Default page size: 30
• Max page size: 100
• Pagination pointer: limit / offset

• Webhooks available: No
• Webhook notes: Hugging Face Hub does not offer a general-purpose outbound webhook system for user or org events as of the current documentation.
• Alternative event strategy: Poll the Hub REST API (e.g., GET /api/organizations/{org}/members) to detect membership changes. Repository-level webhooks are available for model/dataset/Space events but do not cover user-management events.

• SCIM available: Yes

• SCIM version: 2.0

• Plan required: Enterprise Hub (Enterprise or Enterprise Plus tier, $50+/user/mo); SSO must be enabled as a prerequisite.

• Endpoint: https://huggingface.co/api/organizations/{org}/scim/v2

• Supported operations: GET /Users – list provisioned users, GET /Users/{id} – get a single user, POST /Users – provision a new user, PUT /Users/{id} – replace user attributes, PATCH /Users/{id} – update user attributes (activate/deactivate), DELETE /Users/{id} – deprovision user, GET /Groups – list groups (maps to org teams), POST /Groups – create group, PATCH /Groups/{id} – update group membership, DELETE /Groups/{id} – delete group

Limitations:

• SCIM is only available on Enterprise Hub plans with SSO configured.
• SCIM token is a dedicated org-level token generated in Organization Settings > SCIM, separate from user access tokens.
• User provisioning via SCIM creates Hub accounts only if the email does not already exist; existing accounts are linked.
• Not all SCIM attribute mappings are documented; custom attributes are not supported.
• IdP-specific connector setup (e.g., Okta SCIM app) must be configured on the IdP side; Hugging Face does not publish a certified Okta integration in the Okta Integration Network as of current docs.

Three primary automation scenarios are supported.

First, SCIM-based provisioning (Enterprise Hub only): configure your IdP with the org-scoped SCIM base URL (/api/organizations/{org}/scim/v2) and a dedicated SCIM token generated in org settings - distinct from user access tokens.

The IdP then drives POST /Users on hire and DELETE /Users/{id} or PATCH active=false on offboard.

Second, direct REST provisioning for non-SCIM orgs: use manage-org-scoped tokens to POST and PATCH membership;

the target user must already have a Hugging Face account, as there is no API path to create a net-new account outside SCIM.

Third, offboarding audit: after DELETE /api/organizations/{org}/members/{username}, call GET /api/organizations/{org}/members to confirm removal - the user's personal access tokens remain valid and there is no admin API endpoint to revoke another user's tokens.

Provision a new employee into an Enterprise Hub org via SCIM

1. Ensure Enterprise Hub plan is active and SSO is configured for the org.
2. Generate a SCIM token in Organization Settings > SCIM.
3. Configure your IdP (e.g., Okta) with the SCIM base URL: https://huggingface.co/api/organizations/{org}/scim/v2 and the SCIM token as the Bearer credential.
4. Assign the user to the Hugging Face app in your IdP; the IdP sends POST /Users to create the account.
5. Verify membership via GET /api/organizations/{org}/members using an org-admin access token.

Watch out for: If the user's email already exists on Hugging Face, SCIM links the existing account rather than creating a new one. Ensure email addresses match between IdP and any pre-existing HF accounts.

Programmatically add and assign a role to an existing user in an org

1. Generate a user access token with manage-org scope as an org admin.
2. Call POST /api/organizations/{org}/members/{username} with body {"role": "write"} to add the user.
3. Optionally call PATCH /api/organizations/{org}/members/{username} with {"role": "admin"} to elevate the role.
4. Confirm with GET /api/organizations/{org}/members and filter for the username.

Watch out for: The target user must already have a Hugging Face account. There is no API to create a net-new HF account outside of SCIM provisioning.

Offboard a departing employee from an Enterprise Hub org

1. Via SCIM (preferred for Enterprise): Unassign the user from the HF app in your IdP; the IdP sends DELETE /Users/{id} or PATCH to set active=false, removing org access.
2. Via REST API (non-SCIM): Call DELETE /api/organizations/{org}/members/{username} with an org-admin token.
3. Audit remaining access by calling GET /api/organizations/{org}/members to confirm removal.
4. Revoke any personal access tokens the user may have created - this must be done by the user or via IdP session termination; there is no admin API to revoke another user's tokens.

Watch out for: Removing a user from the org does not invalidate their existing Hugging Face access tokens. If the user had tokens with org-repo access, those tokens retain access until the repos' visibility or permissions are updated, or the user revokes the tokens themselves.

The identity graph for Hugging Face org membership has two disconnected layers that create reconciliation risk. Org membership is managed via the Hub REST or SCIM API, but personal access tokens and gated-repository approvals live at the individual account level and are invisible to org admins.

Removing a user from the org via DELETE or SCIM deprovision does not cascade to token invalidation or gated-repo access revocation - those states persist until the user self-revokes or repo permissions are restructured.

Additionally, SCIM is org-scoped rather than a global tenant endpoint, SSO must be active before SCIM is meaningful, and some membership endpoints are not enumerated in the main Hub API reference. Prefer fine-grained tokens with least-privilege scopes to limit blast radius from any unrevoked credential.