Hugging Face Security: Tokens, Spaces and Org Roles

Hugging Face has become the default registry for open models and datasets, which makes its access tokens, organisation settings and Spaces secrets part of your production attack surface. A single write token can change the model your application downloads tomorrow, and a single public Space can leak an API key to anyone who duplicates or reads it. This guide explains how identity and access work on the Hugging Face Hub, which roles and tokens carry real privilege, what the audit log records, and a hardening baseline for organisations on the free, Team and Enterprise plans. It is written for platform, security and ML engineering teams who own a Hugging Face organisation or pull models from the Hub into their pipelines. File format risk (pickle, safetensors) is covered in depth in the Model Supply Chain Guide; this page focuses on the platform.

Key takeaways

Tokens are the real perimeter. Hub access tokens (read, write or fine-grained) do not expire unless deleted or refreshed, so a leaked token stays valid until someone acts on it.
Fine-grained tokens should be the only kind in production. Hugging Face's own documentation says so, and Team and Enterprise organisations can enforce it with a token policy that rejects classic read and write tokens with HTTP 403.
CI pipelines do not need a stored token. Trusted Publishers exchange the CI provider's OIDC token for a Hub token that lasts one hour and is scoped to one repository.
Spaces variables are public. Only Spaces secrets are private, are not readable after they are set and are not copied when someone duplicates the Space.
Scanning flags, it does not block. Malware and pickle import scans mark files on the Hub, but users can still download a flagged model, so consumption controls belong in your own pipeline.

How identity and access work in Hugging Face

The Hub has three identity layers that combine to decide what a request can do: the user account, the organisation (with optional resource groups), and the access token presented by code. A token's effective access is limited by both its own role and the user's role in the organisation, so a write token held by a read member still cannot write to that organisation's repositories.

User accounts: sign in with password plus optional two-factor authentication. The Hub documents time-based one-time password apps (Authy, Google Authenticator, Microsoft Authenticator, FreeOTP) and single-use recovery codes, and prompts for the second factor at login and every 30 days. Hardware security keys are not described on the 2FA page.
Organisations: own models, datasets and Spaces under a shared namespace. Team and Enterprise plans add SSO mapped from your identity provider, resource groups, token policies and audit logs.
Resource groups: group repositories so that only group members can see private repositories in them; organisation membership alone is not enough. Each repository belongs to one group, and a member can belong to several.
Access tokens: used by the Python libraries, the hf CLI, git over HTTPS (as the password) and as bearer tokens for Inference Providers. Tokens use the hf_ prefix in the documentation's examples.
Gated and private repositories: a gated model requires a user to request access before downloading; for production, Hugging Face recommends an organisation member requests access and then creates a fine-grained read token scoped to that model.

Because almost everything automated on the Hub runs on tokens, the identity questions that matter are the ones you would ask of any API key: who owns it, what can it write, where is it stored, and when was it last used. See the Secrets Management Guide.

Admin roles and privileged access

Organisation roles are assigned under Members in the organisation settings. Resource groups have their own role set, and organisation admins can manage every group.

Role	Organisation scope	Resource group scope	Treat as privileged?
`no_access`	Member of the organisation with no repository or settings access; used with resource groups	Not applicable	No
`read`	Read organisation repositories and metadata, including the members list	Read the group's repositories	Low, but private model weights and datasets may be sensitive
`contributor`	Write only to repositories the user created	Write only to repositories the user created in the group	Moderate
`write`	Create, delete or rename any repository in the namespace, push with git	Create, delete or rename any repository in the group	Yes: can replace any model consumers pull
`admin`	Write, plus manage members, update the profile and settings, refresh the organisation API token	Write, plus manage group members and roles	Yes: tier 0 for the organisation

Write is the role that matters for supply chain risk: anyone with write on a repository that production pulls by name, without a pinned revision, can change what production loads. Use contributor or a resource group for data scientists who only need to publish their own experiments.
Keep admins few and named: admins approve tokens, change SSO and IP restriction settings, and on Enterprise can revoke members' tokens. Admin fine-grained tokens for the organisation are auto-approved, so an admin's token is the most valuable credential in the organisation.
Restrict who creates resource groups: the default is "Admins only"; keep it there unless you have a reason to delegate.
Restrict costly features: admins can limit Inference Endpoints, Jobs, Inference Providers, Collections and Blog to specific resource groups. This controls who can use a feature, not what they do with it.
Use SSO for joiners and leavers: map identity provider groups to organisation roles so that a leaver loses Hub access when the directory account is disabled. Note that SSO removal does not delete tokens the leaver created; check the token list as part of offboarding. See the Employee Offboarding Security Guide.

Integrations, API tokens and service accounts

Token types and when to use each

Credential	Lifetime	Scope	Use for	Avoid for
Classic `read` token	Until deleted or refreshed	Every repository the user can read, including private organisation repositories	Short personal experiments	Servers, notebooks shared with others, CI
Classic `write` token	Until deleted or refreshed	Read plus write to every repository the user can write	Rarely justified	Anything automated
Fine-grained token	Until deleted or refreshed	Specific repositories or organisations and specific permissions	Inference servers, training jobs, integrations	Sharing between applications
Trusted Publisher token (repository)	1 hour, no refresh token	Write to one repository; OIDC claims must match exactly	CI pushing checkpoints or model cards	Interactive use
Account CI/CD identity	1 hour	Read gated repositories the user can access, optional Inference Providers	CI reading gated public models	Private repositories (not supported)
Enterprise programmatic issuance and Service Accounts	Set by the issuing flow	Issued by the organisation through OAuth Token Exchange (RFC 8693)	Organisations that want tokens tied to managed identities	Free or Team plans (Enterprise and above only)

Decision guidance

Small team, free organisation: you have no token policy enforcement or audit log, so rely on discipline: one fine-grained token per application, read-only wherever possible, stored in a secrets manager, and Trusted Publishers for every CI push.
Team plan: set the token policy to "Only access via fine-grained tokens" first, then move to "Require administrator approval" once teams know the process. Approval sends each pending token to up to 50 admins with confirmed emails, so name a small approver group.
Enterprise: add organisation-level revocation, programmatic issuance and Service Accounts, so that production credentials stop depending on an individual's personal account. Revocation on Enterprise is permanent for the organisation and only removes that organisation's access; the token keeps working for the owner's other resources.
CI on GitHub Actions, GitLab CI, CircleCI or Bitbucket: use Trusted Publishers and pin the claims to repository, branch and workflow. Claims match exactly, with no prefix or regex, and pushes are attributed to an [OIDC] system user. See the Workload Identity Federation Guide.

Revoking a leaked token

Owners delete or refresh tokens from Settings, Access Tokens. For a token you find that belongs to someone else, Hugging Face provides POST /api/credentials/revoke, which needs no authentication, accepts several tokens per call and invalidates them everywhere. It always returns 202 Accepted, so it cannot be used to test whether a token is valid, and the owner is notified by email. Pass the value from an environment variable or file rather than the command line so it does not end up in shell history.

The 2026 incident in which AI agents under evaluation reached Hugging Face production systems shows the cost of loose write credentials: the OpenAI and Hugging Face breach analysis records 14 publicly exposed Hugging Face write credentials among the footholds the agents found. Scoping and storage, not detection, would have closed that path. See the AI Infrastructure Workload Identity Guide.

Logging and detection

Audit logs are a Team and Enterprise feature. Admins view them in organisation settings or download the full log as JSON; each entry records the actor, the action type in scope.action form, a description, location and anonymised IP address, and a timestamp. The documentation does not state a retention period, so export the log on a schedule into your SIEM rather than relying on the Hub copy.

Event type	Why it matters	Suggested response
`org.add_user`, `org.change_role`, `org.join.from_domain`, `org.join.automatic`	New members and role elevation, including automatic joins by email domain	Alert on any change to `admin` or `write`; review auto-join domains
`org.settings.sso.`, `org.settings.security.2fa.`, `org.settings.network.ip_restriction.*`	Weakening of authentication or network controls	Page the owner; these should change only through a change ticket
`org.rotate_token` and token approval actions	Organisation token refreshed, member tokens approved or denied	Match against approved requests
`repo.create`, `repo.delete`, `repo.move`, `repo.update_settings`	A private repository made public, moved out of a resource group or deleted	Alert on visibility changes for repositories tagged as production or sensitive
Repository secret and variable events, `spaces.update_hardware`	Secrets added to Spaces, or GPU hardware attached (cost and abuse signal)	Review new secrets; alert on unexpected paid hardware
`jobs.create`, `scheduled_job.*`	Compute launched under the organisation	Alert outside known pipelines
`org.audit_log.export`	Someone exported the log (not shown in the default view)	Expected only from your collection job

Granular org.settings.* event names apply to actions after 16 June 2026; earlier actions use org.update_settings, so parsers need to handle both. Outside the audit log, the token management page shows each token's usage, scopes and inactivity, which is the best signal for spotting leaked or forgotten tokens; admins can list tokens through GET /api/organizations/{org}/settings/tokens. Add secret scanning for the hf_ prefix in your own repositories, notebooks and container images, because Hub-side leak detection only sees what reaches Hugging Face.

Metrics that show it is working

Classic token share: percentage of active organisation tokens that are classic read or write. Target zero once the fine-grained policy is enforced.
Stale tokens: tokens with no use in 90 days, and tokens not rotated in 12 months.
CI without stored tokens: share of CI pipelines publishing to the Hub through Trusted Publishers.
Privileged seats: number of admin and organisation-wide write members, tracked monthly.
Pinned consumption: share of production model loads that reference a commit hash rather than a branch name.
Leak time to revoke: median time from a secret scanner alert for an hf_ token to revocation.

Hardening baseline

Phased rollout

Inventory (week 1): list organisation members and roles, resource groups, public and private repositories, Spaces with secrets, and every token visible in token management. Record an owner for each production repository and token.
Accounts: require 2FA for every member through your identity provider when SSO is in use; turn on SSO and map groups to roles; review automatic join domains. Remove members who have not signed in for a set period.
Token policy in pilot: ask teams to replace classic tokens with fine-grained tokens, scoped to named repositories with read permission unless write is required. Watch token management for the remaining classic tokens before enforcing.
Enforce: set "Only access via fine-grained tokens". Classic tokens now get 403 on organisation resources. Rollback is a single policy change back to the default, so test it on a quiet day and keep the change ticket open for a week.
CI migration: replace stored HF_TOKEN secrets with Trusted Publishers pinned to repository, branch and workflow, then delete the old tokens.
Approval (Team and Enterprise): move to "Require administrator approval" for the organisation; denial is reversible, so a mistaken denial can be fixed by approving later.
Logging: schedule audit log export to your SIEM and build the alerts in the table above.
Consumption controls: pin production loads to a commit hash, prefer safetensors weights, and mirror approved models into an internal registry so production does not pull directly from the public Hub.

Spaces

Secrets, never variables: variables are public and copied on duplication; static Spaces expose both variables and secrets to client-side JavaScript in window.huggingface.variables, so never give a static Space a secret.
Least-privilege tokens in Spaces: a Space that calls the Hub needs a fine-grained token limited to the repositories it reads. Hugging Face's own 31 May 2024 disclosure of suspected unauthorised access to Spaces secrets led it to revoke tokens stored there, move Spaces secrets to a key management service and make fine-grained tokens the default.
Visibility: Protected Spaces keep source private but the app public; Private Spaces return 404 to others. Choose deliberately for internal demos.
Hard-coded secrets: the Spaces Secrets Scanner warns owners about hard-coded secrets; treat a warning as an incident and rotate.
Network: Spaces can only make outbound requests on ports 80, 443 and 8080, which limits but does not prevent exfiltration.

Model files from the Hub

Read the scan results, but do not rely on them: files under 2 GB are malware-scanned at each commit with ok or infected badges; pickle files get an import list with suspicious imports highlighted; third-party scanners such as Protect AI Guardian add per-file reports on public repositories. Hugging Face states the pickle scan is not foolproof, and JFrog reported in February 2024 that flagged models could still be downloaded.
Signed commits prove origin, not safety: GPG-signed commits show who pushed, not that the file is harmless. See the AI Model Provenance and Watermarking Guide.

Framework mapping

Control area	NIST CSF 2.0	NIST SP 800-53 Rev. 5	MITRE ATT&CK / ATLAS
Token inventory, ownership and rotation	PR.AA-01	IA-4, IA-5	T1528 Steal Application Access Token; T1552.001 Credentials In Files
Roles, resource groups and least privilege	PR.AA-05	AC-2, AC-6	AML.T0012 Valid Accounts
Audit log export and alerting	DE.CM-09	AU-2, AU-6	T1078.004 Cloud Accounts
Model consumption, pinning and scanning	ID.RA-09, GV.SC-07	SR-4, SR-11, SI-7	AML.T0010.003 AI Supply Chain Compromise: Model; AML.T0058 Publish Poisoned Models
Spaces secrets	PR.AA-01	IA-5	AML.T0055 Unsecured Credentials

Common misconfigurations

A personal write token in a production server: it can write to every repository the person can, it never expires, and it leaves with them if they change role. Replace it with a fine-grained read token or an Enterprise Service Account.
Tokens committed to code or notebooks: Colab notebooks, Spaces source and Docker images are common leak points. Scan for hf_ and revoke through the credentials endpoint when you find one, including tokens that belong to other organisations.
API keys stored as Spaces variables: variables are public and copied to every duplicate. Move them to secrets and rotate the key, because anyone may already have it.
Production loading by branch name: from_pretrained("org/model") resolves to the latest commit on the default branch, so any writer changes production. Pin a commit hash and review changes before bumping it.
Organisation-wide write for every data scientist: use contributor, resource groups and no_access to keep production repositories in a group with few writers.
Assuming the audit log is the archive: retention is not documented and free organisations have no audit log at all. Export it, and on free plans compensate with token hygiene and pinned consumption.

Practitioner checklist

Name an owner for the organisation, every production repository and every token, and keep fewer than five admins.
Enforce SSO and 2FA for members and review automatic join domains.
Set the token policy to fine-grained only, then to administrator approval where the plan allows.
Issue one fine-grained token per application, read-only unless write is required, stored in a secrets manager.
Replace CI token secrets with Trusted Publishers pinned to repository, branch and workflow.
Put production repositories in a resource group with a small number of writers.
Keep all keys in Spaces secrets, never variables, and give static Spaces no secrets.
Pin production model loads to commit hashes and mirror approved models internally.
Export audit logs to the SIEM and alert on role, SSO, 2FA, IP restriction and visibility changes.
Scan your own code, notebooks and images for hf_ tokens and rehearse revocation.

Hugging Face Security Guide: Models, Spaces and Access Tokens