For production and CI, use fine-grained Hugging Face tokens scoped to the specific repositories needed, create one token per app or use, and avoid storing a long-lived token as a CI secret where Trusted Publishers can replace it. A leaked broad token exposes everything its owner can reach.
The three token roles
The Hub documentation lists three roles. A fine-grained token gives access to specific resources, such as particular models or models in a given organization. A read token can read repositories you could read, including private ones. A write token additionally grants write access to repositories you can write to.
Read and write tokens inherit your whole account's reach. Fine-grained tokens do not.
What the docs recommend
- Create one token per app or usage, for example one for a local machine, one for a notebook, one for an inference server. That way you can invalidate one without disturbing the others.
- Use only fine-grained tokens for production. If one leaks, the impact is smaller, and it can be shared within an organization without exposing a personal account.
- The example given: a production app that needs read access to a gated model can use a fine-grained token with read access to just that model.
CI and CD
The docs point to Trusted Publishers for pipelines such as GitHub Actions, GitLab CI and CircleCI. It exchanges your CI provider's OIDC identity token for a short-lived Hub token at the start of each run, scoped either to a repository to publish or to a user to read gated repositories. The result is that there is no long-lived token sitting in your CI secret store.
I did not read the Trusted Publishers page itself, so check it for setup steps and limits before relying on it.
Where tokens go wrong
- A write token pasted into a notebook that is then shared.
- One token reused across laptops, CI and servers, so rotating it breaks everything and nobody wants to rotate.
- Tokens in code or logs. Keep them in environment variables or a secrets manager, not in source.
- Tokens that outlive the project that needed them.
A short checklist
- List every place a Hub token is used.
- Replace read and write tokens in production with fine-grained ones.
- Split shared tokens so each use has its own.
- Move CI to short-lived credentials where possible.
- Put a review date on every remaining long-lived token.
If one does leak, see the leaked token response checklist.
Quick check
Why not one token for everything?
Because a leak or a rotation then affects everything at once. One token per use limits both the blast radius and the disruption.
Can a fine-grained token be limited to one model?
The docs describe fine-grained tokens as giving access to specific resources, such as a specific model or models in an organization.
Sources
Last reviewed: 19 October 2026.
