Get a Hugging Face token

Who this is for: anyone who wants Hugging Face Inference Providers through SpiderGate on their own Hugging Face account.

What this does: walks you through creating a fine-grained hf_ token with the Inference Providers permission and adding it to your SpiderGate vault.

Before you begin

A Hugging Face account.
Credit for Inference Providers. Hugging Face's pricing table gives free users no monthly credit: "Free users can use Inference Providers by purchasing credits, or by upgrading to PRO". PRO is $9 a month and includes $2 of inference credit monthly.
About 3 minutes.

Limits and terms to know first

Note: SpiderGate's picker still lists Hugging Face under free keys and describes "a small monthly credit". Hugging Face's own pricing page no longer gives free accounts one.

Hugging Face says it "does not store any user data for training purposes" when routing requests, and keeps logs for up to 30 days. Each partner provider has its own data policy.

Warning: Hugging Face's terms say you may not disclose your password to any third party, and its token guide recommends "one access token per app or usage". Make a token just for SpiderGate and keep it to your own brand.

Steps

Step 1 — Create the token

Open the new-token page with the right permission preselected. It creates a fine-grained token with Make calls to Inference Providers. Name it, create it, and copy it. Tokens start with hf_.

Step 2 — Add the key in SpiderGate

Open Gate → Vault (/dashboard/gate/vault) and click Add Provider. Type HuggingFace in Search providers... and pick it from the Free keys group.

Fill in the dialog:

Access Token — paste the hf_ token
Label — a name you will recognise later, for example the account it came from.

Under Routing, turn Share with SpiderIQ key pool off. It is on by default, and while it is on, other brands can draw on this key's free quota. Your provider's terms tie the key to your account (see the warnings above), so keep it to your brand.

Click Add key. The button reads Saving... while SpiderGate checks the key.

Verify it worked

When you click Add key, SpiderGate sends one request to Hugging Face with the key before it stores anything: it reads your account at https://huggingface.co/api/whoami-v2.

If Hugging Face accepts the key, the dialog closes and the key appears in your vault list.

If it does not, the dialog stays open and shows:

The huggingface key did not pass its check: <reason>. Nothing was saved.

The reason is SpiderGate's own wording, never Hugging Face's error text. The usual ones are Invalid API key (401 Unauthorized), Access denied (403 Forbidden) and The account behind this key has no credit left (402).

To see the key serve a request, give it a slot in one of your own routing aliases and send a request to that alias. The trace shows which provider answered.

The check proves the token is valid. It does not prove you have inference credit; a request with no credit fails later, at Hugging Face.

Troubleshoot

The key saves, but requests fail with a 402. You have no Inference Providers credit. Buy credits or upgrade to PRO on Hugging Face.

Requests fail with a 403. Hugging Face uses 403 for a token it has denied or revoked. Check the token's permission includes Inference Providers, or create a new one with the link in Step 1.

Too many keys checked for this workspace; try again in …s. SpiderGate runs at most 20 key checks per brand in any 10 minutes. Wait the number of seconds it gives, then click Add key again.

Request timed out (15s) or Could not reach … to check the key. Try again later. The provider did not answer in time. Nothing was saved. Try again in a minute.

The provider is rate-limiting us (429). Try again in a minute. The provider throttled the check itself. Wait a minute and retry.