Hugging Face tokens: create, use, and secure an access token

A Hugging Face User Access Token lets an application authenticate to Hugging Face with permissions you choose. You may see it called a Hugging Face API key or an HF token in a tutorial. For Hub access, those instructions generally mean the credential you manage in your account settings.

Start with the task you need to perform: downloading a restricted model, uploading files, or calling an inference service. That choice determines the permissions your token needs. A token identifies your account; it cannot give you access your account does not have.

How to create a Hugging Face token

1. Sign in to your Hugging Face account and open Access Tokens settings. You can also navigate there from the settings sidebar.
2. Click New token. Enter a name that identifies its use, such as model-download-laptop.
3. Choose a role. For a production application, start with fine-grained permissions.
4. Select the resources and actions the application needs. A download task should not receive write permissions simply to make setup easier.
5. Create the token and save its value in a password manager or the application's secret store.
6. Test the specific operation you intend to use before adding the credential to a longer workflow.

Keep the token out of shared documents, screenshots, and source code. The examples below read credentials from a secure prompt or an environment variable rather than including a real token.

Choose a role for your Hugging Face user access token

Hugging Face documents three User Access Token roles:

• Fine-grained: limits access to selected resources and permissions. Use this for an application that only needs a particular model or set of repositories.
• Read: allows reading model and dataset repositories your account can read. It does not allow you to push content.
• Write: also allows changes to repositories where your account has write access. Use it when the workflow needs to upload models or datasets, or update repository content.

For example, a notebook that downloads model weights and a job that uploads a trained model have different requirements. Give them separate credentials so you can replace one without changing the other. For inference requests, check the additional permission described below.

Log in with the Hugging Face CLI

Install or update the Hub library in your Python environment, then start the CLI login:

python -m pip install --upgrade huggingface_hub
hf auth login
hf auth whoami

The current CLI login flow offers browser login or the option to paste an access token. To use the scoped token you just created, select Paste an access token and follow the prompt. Older installed versions may present the token prompt directly.

Browser login instead asks you to open a URL and approve a short code. It obtains a credential for that login flow, so do not assume it is the fine-grained token you created separately.

Use hf auth whoami to view the active username and check which account is being used on your local machine. If you also use Git over HTTPS, configure an appropriate Git credential helper before choosing to save a credential there. An access token can serve as the password for Git authentication; avoid embedding it in a repository URL.

hf auth logout removes saved local tokens, but it does not revoke a token on Hugging Face or clear an HF_TOKEN environment variable. Manage a compromised credential in your account settings.

Use a token in Python without hard-coding it

By default, Hub requests can use a saved login. For a local script or notebook where you want to choose a credential explicitly, a hidden prompt avoids leaving the token in the source file or cell output:

from getpass import getpass
from huggingface_hub import hf_hub_download

access_token = getpass("Hugging Face access token: ")
model_file = hf_hub_download(
    repo_id="YOUR_ACCOUNT/YOUR_MODEL",
    filename="config.json",
    token=access_token,
)

Replace the repository name and filename with a file you can access. This example downloads one file; it does not load a model or run inference. The hf_hub_download reference explains its repository, revision, and token arguments.

For a deployment, have the platform's secret store provide HF_TOKEN to the process. Then use the environment variable explicitly:

import os
from huggingface_hub import hf_hub_download

model_file = hf_hub_download(
    repo_id="YOUR_ACCOUNT/YOUR_MODEL",
    filename="config.json",
    token=os.environ["HF_TOKEN"],
)

This version fails if the environment variable is missing, which makes configuration errors visible. Never replace the environment lookup with a real credential in code you intend to share.

Which token takes precedence?

For Hub methods that accept it, an explicit token string passed through token= is used for that call. Hugging Face's request-header implementation handles that value before looking up a saved credential. Passing token=False tells these methods to make the request without a token.

When the library resolves credentials automatically, HF_TOKEN takes precedence over the token saved on disk. A stale environment variable can therefore explain why switching a locally saved token appears to have no effect. Hosted notebooks may also provide credentials through their own secret integration, so check that configuration too.

Set deployment environment variables before importing the library. To check whether HF_TOKEN exists without revealing it, print only a Boolean:

import os
print(bool(os.environ.get("HF_TOKEN")))

An environment variable keeps a credential out of the source file, but it does not prevent every leak. Avoid printing the environment, logging authorization headers, or enabling shell tracing around secret-handling commands.

Access private repositories and gated models

A valid token is only one part of access. For a private repository, your account must be allowed to read it and your token must cover that resource. For a gated model, you must also complete the model's access-request process.

Open the model page while signed in with the same account that owns the token. Review its terms and any requested information, including the username and email address shared with the model author, then request access. Some authors approve requests automatically; others review them manually. Creating another token does not bypass a pending or rejected request. Hugging Face's gated-model documentation describes the process and confirms that access is granted to individual users.

This distinction matters when following a model setup guide. For example, our FLUX.1 [dev] and ComfyUI guide covers downloading model files as part of a larger setup. Resolve repository access before investigating GPU memory or runtime errors.

Organization policies can add another requirement

Team and Enterprise organizations can restrict which tokens may access their resources. An organization may require fine-grained tokens or administrator approval. A pending or denied token can produce a 403 response even when you belong to the organization.

Check the token's status and ask an administrator to review it when appropriate. Under Hugging Face's organization token policies, denial can be reversed through approval. Organization-level revocation is permanent for that organization, but it does not revoke the token's access everywhere else. If a credential has leaked, removing access to one organization is not a complete response.

Use a token for Hugging Face Inference Providers

For Hugging Face Inference Providers, create a fine-grained token with Make calls to Inference Providers enabled. Repository download access and inference access are different requirements.

With HF_TOKEN supplied by your secret store, the Python client can read it as follows:

import os
from huggingface_hub import InferenceClient

client = InferenceClient(api_key=os.environ["HF_TOKEN"])

Creating this client does not itself generate a response. Choose a supported model and task, then follow the relevant API example. The first API call guide shows how to move from a model's code example to an authenticated request.

Successful authentication does not guarantee that a chosen model is available, that your account has the necessary access, or that a request falls within your available credits and limits. Read the returned error before changing token permissions.

If you are instead running a model on your own server, keep Hub download credentials separate from the credentials clients use to call your server. Our guide to LLM inference in production covers the broader deployment and access-control decisions.

Troubleshoot a token that is not working

The first troubleshooting step is to check the failing operation and complete error message before attempting another login or generating another credential:

• The wrong account is active: run hf auth whoami in the environment where the request fails. Check the process's HF_TOKEN configuration and any explicit token= argument.
• A private or gated download fails: verify the repository name, account access, token scope, and model approval. Being signed in on the website does not authenticate a separate server process.
• An organization resource returns 403: check fine-grained requirements and the token's approval status. Broader write permissions will not resolve an administrator approval requirement.
• Inference fails while downloads work: check the inference permission, model availability, and the service's returned error. A successful file download does not test inference access.
• A token stopped working after replacement: update every environment that used the old value, including notebook secrets, deployment settings, and Git credential helpers.

A status code alone is not enough to diagnose every failure. Keep the request ID and error text for support, but remove credentials and authorization headers before sharing logs.

Store, rotate, and revoke access tokens safely

Use a separate credential for each application or environment, restrict its permissions, and keep a record of where it is installed. That record should describe the credential's purpose and owner, without containing the secret itself.

For a planned rotation, create a replacement with the required permissions, update the application, verify its operation, and retire the old credential. Remove tokens for applications you no longer run. On shared machines, protect the account and files that hold locally saved credentials.

For supported CI workflows, also consider Hugging Face's Trusted Publishers. It exchanges a CI provider's OpenID Connect identity for a short-lived Hub token, which can avoid storing a long-lived User Access Token in that workflow. Check the supported provider and resource scope before adopting it.

What to do if a token leaks

1. Invalidate the exposed credential through the Access Tokens settings. Treat a suspected leak as exposure; do not wait for evidence of misuse.
2. Replace it in the applications that need continued access, using the narrowest suitable permissions.
3. Review the repositories and services it could reach, and check available activity records for unexpected use.
4. Remove the exposed value from code, logs, notebook output, and other locations. Coordinate repository-history cleanup with collaborators when needed.

Deleting a line from a repository does not invalidate the credential. GitHub's guidance on removing sensitive data puts revocation or rotation before history cleanup. Other people may already have copies of the original content.

Are access tokens the same as model tokens?

No. An access token is a credential. Model tokens are the units a language model processes when reading or generating content. A model's context window and per-token inference usage describe that second meaning. Creating an access token does not change a model's context window or grant unlimited inference usage.

Before putting a workflow into service, verify the intended account, test the exact operation, and confirm that the credential is stored outside the code. Those checks make later permission errors and token replacements easier to handle.