Rotate Hugging Face Access Tokens & Audit Permissions

This guide walks you through rotating Hugging Face access tokens and auditing their permissions, so you can revoke compromised credentials, enforce least-privilege access, and keep your model repositories and datasets secure. You’ll learn how to list active tokens, identify which have write or admin scopes, generate new ones, and update your workflows—all from the Hugging Face web interface and CLI.

What You’ll Need

• A Hugging Face account with write or admin access to the tokens you want to rotate (you can only manage your own tokens).
• Access to the Hugging Face token settings page (you must be logged in).
• If you use the CLI, the huggingface_hub library installed (pip install huggingface_hub).
• A list of where each token is used (e.g., CI pipelines, local scripts, third-party services) so you can update them after rotation.

Step-by-Step

1. Log in to Hugging Face and go to Settings → Access Tokens (or directly to https://huggingface.co/settings/tokens). This page lists all tokens associated with your account, including their name, creation date, last used date, and the permission scope (read, write, or admin).
2. Audit each token’s permissions by clicking on the token name. You’ll see a dropdown with three options: Read (can only download public or gated models/datasets), Write (can upload, modify, and delete content in your repositories), and Admin (can manage access to your orgs and delete repos). For each token, ask: does this token need write or admin access? If not, change it to read-only or delete it.
3. Identify tokens that are no longer in use. Look at the “Last used” column. If a token hasn’t been used in 30+ days and you don’t recognize its name, it’s likely stale. Delete it by clicking the trash icon next to it.
4. Rotate a token (create a new one). Click Create new token, give it a descriptive name (e.g., prod-ci-2025-04), choose the permission scope (read, write, or admin) based on the minimum needed, and click Create token. Copy the token value immediately—it is shown only once.
5. Update your workflows with the new token. Replace the old token in your environment variables, CI secrets, or local config files. For example, in a GitHub Actions workflow, update the HF_TOKEN secret. In the CLI, run huggingface-cli login --token NEW_TOKEN.
6. Revoke the old token. Once you’ve confirmed the new token works (e.g., by running a test upload or download), go back to the tokens page and click the trash icon next to the old token. This immediately invalidates it.
7. Verify the rotation. Try using the new token in a simple command like huggingface-cli whoami (or huggingface_hub.whoami() in Python). If it works, and the old token fails, you’re done.

Common Mistakes

• Forgetting to update all services. If you rotate a token but miss a CI pipeline or a colleague’s script, that service will break. Always keep a list of token usages.
• Creating a new token with the same permissions as the old one. If you’re rotating because of a leak, you should also reduce permissions to the minimum required.
• Deleting a token that is still in use. This causes immediate 401 errors. Always rotate first, then delete.
• Not checking org tokens. If you’re an admin of an organization, you might have org-level tokens that also need auditing. Those are listed under the org’s settings, not your personal settings.
• Storing tokens in plain text. Avoid putting tokens in code or shell history. Use environment variables or a secret manager.

Tips

• Use short-lived tokens. Hugging Face doesn’t offer expiration dates, but you can set a reminder to rotate tokens every 90 days.
• Name tokens by purpose and date. This makes audits easier. For example, ci-upload-2025-04 tells you exactly what it’s for.
• Use read tokens for public repos. If you only need to download models, a read token is enough and reduces risk if it leaks.
• Enable two-factor authentication (2FA). This adds a layer of security to your account, making token theft less impactful.
• Audit quarterly. Set a calendar reminder to review your tokens every three months.

Troubleshooting

• 401 Unauthorized after rotation. This usually means the old token is still being used somewhere. Check your environment variables, CI secrets, and any scripts that reference the token. Also, ensure you copied the new token correctly (it’s case-sensitive).
• Can’t delete a token. You can only delete tokens that belong to you. If you’re trying to delete an org token, you need to be an org admin and go to the org’s settings.
• Token shows as “never used” but you know it’s active. Some services cache tokens. Try using it manually to verify.
• New token doesn’t have the expected permissions. Double-check the scope you selected when creating it. If you need write access to a specific repo, ensure you have write access to that repo in your account settings.
• Forgot to copy the token value. Tokens are only shown once. You’ll need to delete the token and create a new one.

Frequently Asked Questions

Can I see what a token has been used for?

No, Hugging Face only shows the last used date, not the specific actions. However, you can check the audit logs for your repositories (under the repo’s Settings → Audit Log) to see actions like uploads, but they don’t link to specific tokens.

What’s the difference between read, write, and admin tokens?

Read tokens can only download public or gated models/datasets. Write tokens can upload, modify, and delete content in your repositories. Admin tokens can also manage access to your orgs and delete repositories. Choose the least privilege needed.

Can I set an expiration date on a token?

No, Hugging Face tokens don’t expire by default. You have to rotate them manually. Some third-party tools like GitHub Actions can store tokens as secrets with expiration, but the token itself remains valid until revoked.

What happens to my CI/CD pipelines if I rotate a token?

They will fail with authentication errors until you update the token in your CI configuration. That’s why it’s crucial to update all usages before revoking the old token.

Is it safe to share a token with a teammate?

No, tokens are tied to your account and grant all your permissions. Instead, create a separate token for each service or person, so you can revoke them individually.

How do I rotate an org token?

Go to the org’s settings (e.g., https://huggingface.co/organizations/YOUR_ORG/settings/tokens), create a new token, update your workflows, then delete the old one. Only org admins can do this.

Related

• Cloud on Ramp? What It Means & How to Use It
• Backup Email: Keep Online Accounts Secure
• Copilot Reminders & Calendar Events: How-To