A token in a public Space is a token you have given away

Why you need a token at all

Most of the Hub is readable without an account. You will still need a token for four things: private repositories, gated models, uploading anything, and any hosted inference you are billed for. A token is a string beginning hf_ that stands in for you. Anything holding it *is* you, as far as the Hub is concerned.

Make one that can do as little as possible

Access tokens live under your account settings. There are three kinds, and the choice matters more than the two seconds it takes.

• Fine-grained — you tick exactly which permissions it has, and can scope it to named repositories or a single organisation. This should be your default.
• Read — can read everything you can read. Convenient, broad.
• Write — can create, modify and delete your repositories. A leaked write token is not an inconvenience.

Give each token a name that says where it lives — laptop-read, render-space, ci-upload — because in six months you will want to revoke one of them without breaking the others, and an untitled list of five tokens gives you no way to choose.

Where it lives on your machine

hf auth login

This prompts for the token and writes it to a file under your Hugging Face home directory, typically ~/.cache/huggingface/token. Every library on that machine can read that file. That is the trade for never typing it again, and it is usually the right trade on your own laptop and the wrong one on a shared server.

In code, never write the token as a literal. Read it from the environment:

import os
from huggingface_hub import login

login(token=os.environ["HF_TOKEN"])

Most of the libraries pick up an HF_TOKEN environment variable on their own, so often you set the variable and write no authentication code at all.

Gated repositories

Some repositories — Llama, Gemma, a number of speech models and datasets — sit behind a gate. The page shows the licence and a button. Sometimes access is granted instantly. Sometimes there is a short form asking for your name, affiliation and country, and a wait of hours or days for a human. Sometimes you are refused.

That form is a condition of the licence, not a formality, and the name you give is meant to be your real one.

The symptoms are worth memorising, because they look alike and mean different things:

• 401 — there is no valid token in the request at all.
• 403, or a GatedRepoError — the token is valid but that *account* has not been granted access to that repository.

The second one catches people out constantly. You accepted the terms in a browser while logged in as yourself; the code is running with a token belonging to a service account, a colleague, or a Space. Access is per account, and accepting the terms once does not propagate.

The rule, stated once

Anywhere a token is visible to someone else, it is theirs. A public Space's files are public. A notebook pushed to GitHub is public. A screenshot of your terminal posted in a support thread is public, and the token is legible in it. Automated scanners crawl for the hf_ pattern within minutes of publication.

Hugging Face and GitHub both scan for leaked tokens and will revoke them, which is a safety net rather than a plan — it fires after publication, not before. If you think a token might have been seen, revoke and reissue. That takes thirty seconds and requires no judgement, whereas reasoning about whether anyone actually saw it requires perfect information you do not have.

In a Space, the token goes in Settings under secrets, with the name HF_TOKEN, and never in app.py.

One organisational point

A token is a person, not a service. When someone leaves a team, their tokens keep working until somebody revokes them, and any pipeline built on a departed colleague's token dies the day you do. For anything shared, create an organisation, add a dedicated account or a fine-grained token owned by the organisation, and scope it to the repositories it needs.

Do this now

Open your access tokens page. If there is a write token you cannot account for, revoke it. Then create one fine-grained read token, named after the machine you are sitting at, and log in with that.