Hugging Face

Connect Hugging Face Hub models to Safeguard. The access the user access token needs, which token types work, and step-by-step setup.

What it does

The Hugging Face card connects Safeguard to models on the Hugging Face Hub. Safeguard lists your models (or the ones you add by URL) and scans each selected model's files for security issues, such as unsafe serialization formats and embedded code, and records it in your AI inventory. Find the card under Integrations on the Project/Product tab.

Public vs private

	Public	Private
What you enter	A model URL, such as `https://huggingface.co/<owner>/<model>`	A Name and a Hugging Face user access token
Credential needed	None	A user access token with read access
What you can select	The public models you add by URL	Your models and the models of organizations you belong to, plus any you add by URL, including private and gated models the token can read

Supported auth methods

Method	Use it when	Notes
User access token, fine-grained	Recommended	Limit it to the models or organizations Safeguard should read
User access token, read	Simple setup	Reads every repository you can read
None	Public models	Nothing to create

Permissions required

Safeguard only reads. It never pushes commits, edits model cards, opens discussions or changes settings.

Fine-grained token

Permission (Hugging Face token settings)	Required?	What Safeguard uses it for
Read access to the repositories to scan (your namespace, a selected organization, or selected repositories)	Required	Checking the token (`/api/whoami-v2`), listing models (`/api/models`), reading refs and revisions, and downloading model files for the scan
Read access to public gated repos you can access	Optional	Scanning gated models you have been granted access to
Any write, discussion, inference, webhook or billing permission	Not used	Leave them off

Read token

Token role	Required?	What Safeguard uses it for
`read`	Required	The same calls as above, across every repository you and your organizations own

Least privilege: a fine-grained token with read access to only the models or organization you want scanned.

Token types

Token type	Works?	Notes
Fine-grained user access token, read only	Yes (recommended)	Hugging Face recommends fine-grained tokens for production use
`read` user access token	Yes
`write` user access token	Works, not recommended	Safeguard never writes
Token scoped to an organization that requires approval	Only after approval	It stays Pending until an organization administrator approves it
Read or write token in an organization that only allows fine-grained tokens	No	The organization rejects it with a `403`

Expiry: Hugging Face user access tokens do not expire on their own. Rotate the token (Hugging Face calls it refresh) at least every 90 days.

What we never need: write access, inference or billing permissions, organization admin rights, or access to datasets and Spaces.

Step-by-step setup

Create the credential in Hugging Face

Sign in to Hugging Face and open Settings > Access Tokens (https://huggingface.co/settings/tokens).
Click New token.
Choose Fine-grained, give it a name (for example Safeguard), and grant read access to the repositories, or the organization, to scan. Add read access to gated repositories only if you need them.
Create the token and copy it (it starts with hf_).

Or with the Hugging Face CLI

Hugging Face has no CLI command that creates a token. To check the token before you paste it into Safeguard:

hf auth login --token "$HF_TOKEN"
hf auth whoami

Connect it in Safeguard

Open Integrations and choose the Project/Product tab.
Click Connect on the Hugging Face card.
For public models, choose Public, enter a Name, paste a model URL, click Add, then Next.
For private models, choose Private, enter a Name and paste the token into Access Token, then verify it.
Click Next, select the models and revisions to scan, review, and connect.

Webhooks and triggers

This integration has no webhooks. Each selected model is scanned when you connect it; to rescan new revisions, set a schedule under Integrations > Scheduled or rescan by hand from the project.

What we read and store

Read: your account name, model names, refs and revisions, and the files of the models you select for scanning.
Stored: the connection's settings, the scan results and AI inventory entry of each scanned model, and the token, which is encrypted at rest and never shown again after you save it.
Not stored: model weights. Files are read for the scan and not kept.
No customer data from this integration is sent to third-party LLMs.

Troubleshooting

Message you see	Cause	Fix
`HuggingFace API token required`	The token field is empty	Paste the `hf_...` token
`Invalid API token`	Hugging Face rejected the token (deleted, refreshed, or mistyped)	Create or refresh the token and paste it again
`Model is private. Authentication required.`	A private model was added on the Public tab	Use the Private tab with a token
A gated or organization model fails with `403`	The token lacks read access to that repository, is pending approval, or the organization requires fine-grained tokens	Grant read access in the token's settings, wait for approval, or use a fine-grained token

Rotation and disconnect

Rotate: refresh the token under Settings > Access Tokens > Manage, find the connection under Project Configurations on the Project/Product tab, choose Update, paste the new token and save.
Disconnect: choose Delete from the connection's menu under Project Configurations and confirm Delete configuration, then delete the token in Hugging Face.

Vendor references

User access tokens, checked 2026-10-16.
Hub API endpoints, checked 2026-10-16.

Hugging Face

On this page