# Hugging Face API key: how to create a token and fix errors

> Your HF token still works after chat models on Inference Providers moved to OpenRouter's routing on November 16, but your own provider keys no longer do for language models.

URL: https://claudegpt.si/news/hugging-face-api-key  
Published: 2026-11-18T14:59:47.269Z  
Author: ClaudeGPT Si Newsroom  
Section: Guides  
Topics: Hugging Face, API keys, How to, Developer tools, OpenRouter  
Publisher: ClaudeGPT Si

## Key takeaways

- A Hugging Face API key is a User Access Token, created under Settings > Access Tokens, in fine-grained, read or write form.
- Since November 16, 2026, chat models on Inference Providers run through OpenRouter, and existing Hugging Face tokens and code keep working.
- Custom provider keys no longer work for language models on Inference Providers, though image and video provider keys still do.

A Hugging Face API key is a User Access Token, a string that starts with `hf_`, and you create it in your account under [Settings > Access Tokens](https://huggingface.co/settings/tokens) by clicking **New token**. Pick a fine-grained token with only the permissions you need, copy it once, and pass it to the `hf` command line tool, the Python library or the Inference Providers API as `HF_TOKEN`.

Below: which token type to pick, how to use it, where to keep it, what the November 16, 2026 move to OpenRouter's routing changed, and how to fix a token that stops working. Every step comes from [Hugging Face's token docs](https://huggingface.co/docs/hub/security-tokens), the [Inference Providers docs](https://huggingface.co/docs/inference-providers/index) and the [`hf` CLI guide](https://huggingface.co/docs/huggingface_hub/guides/cli).

## What you need first

- A free Hugging Face account.
- Python with pip, if you want the `hf` command and the Python library.
- Credits, if you plan to call models through Inference Providers. Per the [pricing page](https://huggingface.co/docs/inference-providers/pricing), as of November 18, 2026 free accounts get no monthly credits and have to buy them, PRO users get $2.00 a month, and Team and Enterprise organizations get $2.00 per seat.

## Which token type to pick

Hugging Face offers three roles when you create a token:

| Token type | What it can do | Use it for |
| --- | --- | --- |
| Fine-grained | Only the permissions and resources you tick, such as one model, one organization, or "Make calls to Inference Providers" | Production apps, inference calls, gated models |
| Read | Read every repository you can read, public or private | Downloading models and datasets on your own machine |
| Write | Everything read does, plus push to repositories you can write to | Uploading models, editing model cards |

Hugging Face recommends fine-grained tokens for production, because a leaked one exposes less. The Inference Providers docs ask for a fine-grained token with the **Make calls to Inference Providers** permission. Two details trip people up: to request access to a gated model through the API you need a fine-grained token with **Request access to gated repos**, because read tokens can't send access requests, and some Team and Enterprise organizations reject read and write tokens entirely.

The docs also suggest one token per machine or app, so you can kill one without breaking the others.

## How to get a Hugging Face API key

1. Log in at huggingface.co and open [Settings > Access Tokens](https://huggingface.co/settings/tokens).
2. Click **New token**.
3. Give it a name that says where it will live, such as "laptop" or "prod-inference".
4. Choose the role: fine-grained, read or write. For fine-grained, tick the permissions you need. For chat models through Inference Providers, tick **Make calls to Inference Providers**.
5. Create the token and copy it. It starts with `hf_`.

To change, refresh or delete a token later, use the **Manage** button next to it on the same page. Refreshing gives you a new value, and you have to replace the old one everywhere it is used.

## Log in with the hf CLI

Install the library, which ships the `hf` command:

```bash
pip install -U huggingface_hub
hf auth login
```

By default `hf auth login` opens a browser flow: it prints a URL and a short code, you approve the request, and the CLI saves a token for you. To use the token you created instead, choose "Paste an access token", or pass it from an environment variable so it never lands in your shell history:

```bash
hf auth login --token $HF_TOKEN
hf auth whoami
```

`hf auth whoami` prints your username and organizations. Other commands under `hf auth`: `list` shows the tokens saved on the machine, `switch` changes the active one, `token` prints it, and `logout` deletes the saved tokens.

These commands were run on November 18, 2026 with `huggingface_hub` 2.4.0, installed with pip: `hf version`, `hf --help`, `hf auth --help`, `hf auth login --help` and `hf auth whoami` with no token and with a made-up one. No real token was used.

The old `huggingface-cli` command no longer exists. The [v1.0 migration guide](https://huggingface.co/docs/huggingface_hub/concepts/migration) says it was removed and replaced by `hf`. On 2.4.0, `huggingface-cli` isn't installed at all, so `huggingface-cli login` from an old tutorial becomes `hf auth login`.

## Use the token in Python

Once you are logged in, the library sends the saved token on every request. You can also set `HF_TOKEN`, or pass the token to a single call:

```python
from huggingface_hub import login, whoami

login()          # prompts for login, like hf auth login
print(whoami())  # shows which account the token belongs to
```

Libraries such as `transformers` and `datasets` accept a `token` argument too, for example `AutoModel.from_pretrained("private/model", token=access_token)`. Hugging Face discourages hardcoding the value. Read it from an environment variable or a secrets store instead.

## Use the token with Inference Providers

Inference Providers sends your request to a company that serves the model and bills you at that provider's price, with no markup, according to Hugging Face. The token goes in as a bearer token. With the `huggingface_hub` client:

```python
from huggingface_hub import InferenceClient

client = InferenceClient()  # uses HF_TOKEN or your saved login
completion = client.chat.completions.create(
    model="deepseek-ai/DeepSeek-V4.1-Flash",
    messages=[{"role": "user", "content": "How many 'G's in 'huggingface'?"}],
)
print(completion.choices[0].message)
```

With OpenAI's Python client, change the base URL and pass your Hugging Face token as the API key:

```python
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://router.huggingface.co/v1",
    api_key=os.environ["HF_TOKEN"],
)
```

Or with curl:

```bash
curl https://router.huggingface.co/v1/chat/completions \
  -H "Authorization: Bearer $HF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model": "deepseek-ai/DeepSeek-V4.1-Flash:fastest",
       "messages": [{"role": "user", "content": "Hello"}]}'
```

Add `:fastest` to the model id for the highest throughput, `:cheapest` for the lowest price, or a provider name such as `:novita` to use only that provider. To bill a Team or Enterprise organization instead of yourself, send the header `X-HF-Bill-To: <org-name>`, or pass `bill_to="<org-name>"` to `InferenceClient`.

## What the OpenRouter switch changes for your token

On November 16, 2026, [OpenRouter announced](https://openrouter.ai/blog/announcements/hugging-face-inference-providers/) that "chat models on Hugging Face Inference Providers now run through OpenRouter", and [Hugging Face's own post](https://huggingface.co/blog/openrouter) said it was replacing its custom router with OpenRouter's for language models. For someone holding an HF token, this is what the two posts say:

- **Your token and code keep working.** OpenRouter says "your existing Hugging Face token and code keep working". You still call `router.huggingface.co` with your HF token, and OpenRouter says you don't have to set anything up.
- **Failed requests get retried.** Before, Inference Providers picked one provider and returned its error if it failed. Now a failed try is retried on another provider within the same call.
- **Billing stays on Hugging Face.** You pay the provider's price on your Hugging Face bill, with no markup added, per Hugging Face.
- **Your own provider keys no longer work for language models.** Hugging Face calls this a breaking change: language-model requests are billed to your Hugging Face account or organization, so you can no longer use your own API key for a provider with these models. You can still choose a provider with a `model:provider` suffix, or turn providers off in your [Inference Providers settings](https://huggingface.co/settings/inference-providers). Custom keys for image and video providers keep working.
- **Image, video and audio are unchanged.** They still run directly through Inference Providers, with the same token and API.

OpenRouter says 160 models from 38 labs are available this way. Hugging Face has said its next step is letting you connect an OpenRouter account to Hugging Face, with no date given.

## How to store your token safely

- Keep it out of code. Use the `HF_TOKEN` environment variable, a secret in a Hugging Face Space, or a Colab secret named `HF_TOKEN`, which the quickstart says logs you in automatically.
- Know where the CLI keeps it. `hf auth login` writes it to `~/.cache/huggingface/token` (under `HF_HOME`), and named tokens to `~/.cache/huggingface/stored_tokens`.
- Prefer fine-grained tokens with the fewest permissions, one per app or machine.
- In CI, you may not need a stored token at all. Hugging Face's [Trusted Publishers](https://huggingface.co/docs/hub/security-tokens) exchanges a GitHub Actions, GitLab CI or CircleCI identity token for a short-lived Hub token on each run.
- If a token leaks, delete or refresh it in Access Tokens right away. Until you do, anyone holding it can use it with whatever access it has.

## Hugging Face token not working: common errors and fixes

**"Invalid user token. The token from HF_TOKEN environment variable is invalid."** This is what `hf auth whoami` printed in the test with a made-up value. The CLI adds "Note that HF_TOKEN takes precedence over `hf auth login`." An old or mistyped `HF_TOKEN` overrides the good token you saved with `hf auth login`. Fix the variable or unset it. `hf auth logout` won't help here, because it doesn't touch `HF_TOKEN`.

**401 from the router, "Invalid username or password."** Sending a made-up token to `router.huggingface.co/v1/chat/completions` returned exactly this. Check that the header reads `Authorization: Bearer hf_...`, that you copied the whole token, and that you didn't refresh it on the website since. A request with no token at all also returns 401.

**The token worked for months, then stopped.** Tokens unused for a year expire automatically. Hugging Face emails you 30 days before, and an expired token shows an **Invalidated** badge in your settings. Refresh it to get a new value.

**403 on an organization's models.** The token docs list several causes for Team and Enterprise organizations: the org only accepts fine-grained tokens, your fine-grained token is still pending admin approval, or an admin denied or revoked it. A revoked token can't be restored; create a new one.

**403 or "access denied" on a gated model.** Request access on the model page in your browser first. With automatic approval you get access at once; with manual approval the authors have to accept you. Then use a token from the same account.

**A fine-grained token can download but not call models.** It is missing the **Make calls to Inference Providers** permission. Edit the token's permissions or create a new one.

**Inference calls fail on a free account.** Free accounts get no monthly credits, so buy credits or move to PRO. For an organization, add `X-HF-Bill-To` so the request draws on the org's credits, and check that the org hasn't disabled the provider you named: requests billed to it ignore your personal provider settings.

**`huggingface-cli: command not found`.** The command was removed in `huggingface_hub` v1.0. Use `hf auth login` and the other `hf` commands.

**Your provider key is ignored.** Since November 16, 2026, language models through Inference Providers are billed to your Hugging Face account, and custom provider keys no longer apply to them.

## Where to go next

Run `hf env` to see the token path and whether a token is saved. Then try a model in the [Inference Playground](https://huggingface.co/playground) before you wire it into code. For other providers' keys, see [how to get a Mistral API key](https://claudegpt.si/news/mistral-how-to-get-api-key) and [how to get a Claude API key](https://claudegpt.si/news/claude-how-to-get-api-key).

## Frequently asked questions

### Is a Hugging Face API token free?

Any account can create tokens in Settings > Access Tokens. Calling models through Inference Providers costs money: as of November 18, 2026 free accounts get no monthly credits and must buy them, while PRO users get $2.00 a month.

### How do I set the Hugging Face token as an environment variable?

Set HF_TOKEN to your token value. The huggingface_hub library and the hf CLI read it automatically, and it takes priority over a token saved with hf auth login.

### How do I use a Hugging Face token in Google Colab?

Add a Colab secret named HF_TOKEN. Hugging Face's quickstart says the library then authenticates you automatically.

### Why is huggingface-cli login not working?

The huggingface-cli command was removed in huggingface_hub v1.0. Use hf auth login instead.

## Sources

- [User access tokens](https://huggingface.co/docs/hub/security-tokens), Hugging Face
- [Inference Providers](https://huggingface.co/docs/inference-providers/index), Hugging Face
- [Inference Providers pricing and billing](https://huggingface.co/docs/inference-providers/pricing), Hugging Face
- [Command Line Interface (CLI)](https://huggingface.co/docs/huggingface_hub/guides/cli), Hugging Face
- [huggingface_hub quickstart](https://huggingface.co/docs/huggingface_hub/quick-start), Hugging Face
- [Migrating to huggingface_hub v1.0](https://huggingface.co/docs/huggingface_hub/concepts/migration), Hugging Face
- [Gated models](https://huggingface.co/docs/hub/models-gated), Hugging Face
- [Hugging Face and OpenRouter join forces to make open-weight models easy to run](https://huggingface.co/blog/openrouter), Hugging Face
- [OpenRouter Now Powers Inference on Hugging Face](https://openrouter.ai/blog/announcements/hugging-face-inference-providers/), OpenRouter
