Create one token per app or use, make production tokens fine-grained with the narrowest scope, keep them out of notebook cells and repos, and use short-lived credentials in CI where your provider supports it. If one leaks, revoke it first and investigate second.
What Hugging Face offers
The Hub documentation lists three token roles. Read tokens give read access to repositories you can read. Write tokens add write access. Fine-grained tokens give access to specific resources, such as one model in one organization, and the docs call them useful in production because you do not share access to everything you own.
The recommendations from the docs are specific. Make one token per app or usage, for example one for a local machine, one for a Colab notebook and one for an inference server, so you can invalidate one without affecting the others. Use only fine-grained tokens for production, since the impact of a leak is smaller.
Where tokens leak in ML work
- Notebook cells. A token pasted into a cell is saved with the notebook and may be shared or committed.
- Shell history and logs. The docs suggest passing tokens through environment variables or files and avoiding raw tokens in command lines.
- Docker images. A token baked into a build layer travels with the image.
- Shared accounts. One token used by five people has no owner.
- Over broad scope. A write token used only to download a model.
A routine that works
| Use | Token choice | Where it lives |
|---|---|---|
| Personal experiments | Read token, one per machine | Local secret store, not in code |
| Shared notebook platform | Fine-grained, read only on needed repos | Platform secret manager |
| Production inference | Fine-grained, read access to the single model | Runtime secret, rotated |
| Publishing from CI | Short-lived credential via OIDC if available | Issued per run |
| Training that pushes checkpoints | Write scoped to one repo | CI secret, with owner |
The Hub docs describe a Trusted Publishers option that exchanges a CI provider's OpenID Connect identity token for a short-lived Hub token at the start of each run, so you can avoid storing a token as a CI secret at all. Check the current documentation for what your setup supports.
When a token leaks
- Delete or refresh it in the Access Tokens settings. The docs say anyone can read or write your private repos until you do.
- Identify what that token could reach.
- Review recent activity in those repos for changes you did not make.
- Replace the token with a narrower one.
- Find how it leaked and remove that path.
The Hub also provides a revoke endpoint that lets someone who finds a leaked token invalidate it without owning the account. That is handy for secret scanning pipelines you run yourself.
Add a check to your review
Search code and notebooks for token prefixes and for token parameters before merging.
grep -rnE "hf_[A-Za-z0-9]{20,}|token=" . --include="*.py" --include="*.ipynb"
This is a rough filter. Use a dedicated tool in your own pipeline if you have one.
Where Safeguard fits
Safeguard focuses on software supply chain: SBOM and dependency scanning, reachability analysis, policy gates and compliance evidence automation. It does not replace a secret manager. Try a free scan at gold.safeguard.sh/scan.
Quick check
Is a read token safe to leave in a notebook?
Not ideal. It can still expose private models you can read. Keep it out of cells and use a secret store.
Why one token per app?
So a leak or a retirement of one app can be handled without breaking the others.
Sources
Last reviewed: 19 October 2026.
