How to Create a Hugging Face API Token | Complete Guide

🔑 How to Create a Hugging Face API Token

Learn how to create and manage Hugging Face API tokens to access thousands of open-source AI models, datasets, and spaces on the Hugging Face Hub.

---

🔹 What is a Hugging Face API Token?

A Hugging Face API token (also called Access Token) allows you to:

• Access and download models from Hugging Face Hub
• Use the Inference API for model predictions
• Upload and manage your own models and datasets
• Authenticate with Hugging Face services
• Access private or gated models and datasets

---

🔹 Prerequisites

Before creating an API token, you need:

1. Hugging Face Account → Sign up at https://huggingface.co/join
2. Email Verification → Verify your email address
3. Internet Connection → For API access

---

🔹 Step-by-Step: Creating a Hugging Face API Token

Step 1: Sign in to Hugging Face

1. Go to Hugging Face
2. Click “Sign in” in the top-right corner
3. Log in with your credentials

Step 2: Navigate to Access Tokens

1. Click on your profile picture (top-right corner)
2. Select “Settings” from the dropdown menu
3. Click on “Access Tokens” in the left sidebar

Or go directly to: https://huggingface.co/settings/tokens

Step 3: Create a New Token

1. Click “New token” button

2. Fill in the token details:

   • Name: Give it a descriptive name (e.g., “My Python App”, “Production API”)
   • Role: Choose the permission level:
     • Read → Only read access (recommended for most uses)
     • Write → Allows uploading models and datasets
     • Admin → Full access (use with caution)

3. Click “Generate a token”

Step 4: Copy Your Token

⚠️ IMPORTANT: Save your token immediately!

1. Copy the token that appears
2. Store it securely in a password manager or environment variable
3. You can view it again later, but it’s best to save it now

Example token format:

hf_AbCdEfGhIjKlMnOpQrStUvWxYz1234567890

---

🔹 Token Permission Levels

Read Token:

• ✅ Download public models and datasets
• ✅ Access Inference API
• ✅ Use private models you have access to
• ❌ Cannot upload or modify resources

Write Token:

• ✅ All Read permissions
• ✅ Upload models and datasets
• ✅ Create and manage repositories
• ✅ Push changes to your repos

Admin Token:

• ✅ All Write permissions
• ✅ Delete repositories
• ✅ Manage organization settings
• ⚠️ Use with extreme caution

---

🔹 Managing Your Tokens

View Existing Tokens:

1. Go to Access Tokens
2. You’ll see all your tokens with:
   • Name
   • Role (Read/Write/Admin)
   • Created date
   • Last used timestamp
   • Actions (Rename, Revoke)

Rename a Token:

1. Click the pencil icon next to the token
2. Enter a new name
3. Click “Save”

Revoke/Delete a Token:

1. Click the trash icon next to the token
2. Confirm the deletion

⚠️ Warning: Revoking a token immediately stops all applications using it.

---

🔹 API Token Security Best Practices

✅ DO:

• Use Read tokens by default (only use Write when necessary)
• Store tokens in environment variables or secrets managers
• Use different tokens for different projects
• Revoke tokens you no longer need
• Use .env files for local development
• Rotate tokens periodically

❌ DON’T:

• Hardcode tokens in source code
• Commit tokens to Git repositories
• Share tokens publicly
• Use Admin tokens unless absolutely necessary
• Reuse the same token across all projects

---

🔹 Using Your Hugging Face Token

Method 1: Environment Variable (Recommended)

Linux/macOS:

export HF_TOKEN="hf_your-token-here"
# or
export HUGGING_FACE_HUB_TOKEN="hf_your-token-here"

Windows CMD:

set HF_TOKEN="hf_your-token-here"

Windows PowerShell:

$env:HF_TOKEN="hf_your-token-here"

Method 2: .env File

Create a .env file:

HF_TOKEN=hf_your-token-here

Load it in Python:

from dotenv import load_dotenv
import os

load_dotenv()
token = os.getenv("HF_TOKEN")

Method 3: Hugging Face CLI Login

huggingface-cli login

This will prompt you to enter your token and save it locally.

---

🔹 Testing Your Token

Python Example - Using Transformers:

from transformers import pipeline
import os

# Set your token
token = os.getenv("HF_TOKEN")

# Use a model with authentication
classifier = pipeline(
    "sentiment-analysis",
    model="distilbert-base-uncased-finetuned-sst-2-english",
    use_auth_token=token
)

result = classifier("I love Hugging Face!")
print(result)

Python Example - Using Inference API:

import requests
import os

API_URL = "https://api-inference.huggingface.co/models/gpt2"
headers = {"Authorization": f"Bearer {os.getenv('HF_TOKEN')}"}

def query(payload):
    response = requests.post(API_URL, headers=headers, json=payload)
    return response.json()

output = query({"inputs": "The answer to the universe is"})
print(output)

Python Example - Downloading Models:

from huggingface_hub import hf_hub_download
import os

token = os.getenv("HF_TOKEN")

# Download a specific file from a model
file_path = hf_hub_download(
    repo_id="bert-base-uncased",
    filename="config.json",
    use_auth_token=token
)

print(f"Downloaded to: {file_path}")

cURL Example:

curl https://api-inference.huggingface.co/models/gpt2 \
  -H "Authorization: Bearer $HF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"inputs": "Hello, Hugging Face!"}'

---

🔹 Using Tokens with Hugging Face Libraries

Install Required Libraries:

# Core library
pip install huggingface_hub

# For model inference
pip install transformers torch

# For datasets
pip install datasets

Authenticate in Code:

Option 1: Pass token directly

from huggingface_hub import HfApi

api = HfApi(token="hf_your-token-here")

Option 2: Use environment variable

from huggingface_hub import HfApi
import os

api = HfApi(token=os.getenv("HF_TOKEN"))

Option 3: Use CLI login (token stored automatically)

from huggingface_hub import HfApi

api = HfApi()  # Automatically uses saved token

---

🔹 Accessing Private and Gated Models

Private Models:

If you have access to a private model:

from transformers import AutoModel
import os

model = AutoModel.from_pretrained(
    "username/private-model",
    use_auth_token=os.getenv("HF_TOKEN")
)

Gated Models:

Some models require explicit access approval:

1. Visit the model page (e.g., LLaMA models)
2. Click “Request access”
3. Fill out the form and wait for approval
4. Once approved, use your token to access:

from transformers import AutoTokenizer
import os

tokenizer = AutoTokenizer.from_pretrained(
    "meta-llama/Llama-2-7b-hf",
    use_auth_token=os.getenv("HF_TOKEN")
)

---

🔹 Using the Inference API

Hugging Face provides a free Inference API with rate limits:

Free Tier Limits:

• Requests per day: Limited (varies by model)
• Rate limiting: May experience delays under heavy load

Pro Tier (Hugging Face Pro):

• Higher rate limits
• Priority access
• Faster inference

Check pricing: https://huggingface.co/pricing

---

🔹 Common Issues and Troubleshooting

Issue 1: “Invalid token” Error

Solution:

• Verify the token is copied correctly
• Ensure the token hasn’t been revoked
• Check for extra spaces or newlines

Issue 2: “Access Denied” (401/403 Error)

Solution:

• Token may not have required permissions
• Model may be private or gated
• Request access to gated models if needed

Issue 3: Rate Limit Exceeded

Solution:

• You’ve hit the free tier limit
• Wait for the limit to reset
• Consider upgrading to Hugging Face Pro

Issue 4: Token Not Found

Solution:

• Ensure environment variable is set correctly
• Run huggingface-cli login to save token locally
• Check .env file is being loaded

---

🔹 Uploading Models and Datasets

With a Write token, you can upload your own content:

Upload a Model:

from huggingface_hub import HfApi
import os

api = HfApi(token=os.getenv("HF_TOKEN"))

api.upload_file(
    path_or_fileobj="path/to/model.bin",
    path_in_repo="model.bin",
    repo_id="username/my-model",
    repo_type="model"
)

Create a Repository:

from huggingface_hub import create_repo
import os

create_repo(
    repo_id="username/my-new-model",
    token=os.getenv("HF_TOKEN"),
    private=False
)

---

🔹 Organization Tokens

If you’re part of an organization:

1. Go to Organization Settings
2. Select your organization
3. Navigate to “Access Tokens”
4. Create organization-level tokens

---

🔹 CLI Commands

Login:

huggingface-cli login

Whoami (check current user):

huggingface-cli whoami

Logout:

huggingface-cli logout

Upload a model:

huggingface-cli upload username/model-name ./model_folder

---

🔹 Additional Resources

• Official Documentation: https://huggingface.co/docs
• Hub Documentation: https://huggingface.co/docs/hub
• Transformers Library: https://huggingface.co/docs/transformers
• Inference API Docs: https://huggingface.co/docs/api-inference
• Community Forum: https://discuss.huggingface.co
• Model Hub: https://huggingface.co/models
• Datasets Hub: https://huggingface.co/datasets

---

🚀 Conclusion

You now know how to: ✅ Create and manage Hugging Face API tokens
✅ Use different permission levels appropriately
✅ Authenticate with Hugging Face services
✅ Access models, datasets, and APIs
✅ Upload your own content
✅ Troubleshoot common issues

Start building with the world’s largest AI community! 🤗