Skip to main content
An API key authenticates every call you make. Keys belong to the workspace, not to you personally, so a key keeps working when the person who created it leaves.

​
Creating a key

Create keys from the dashboard. A key looks like this:
You see the full value once, at creation. We store only a hash, so we cannot show it to you again or recover it for you. If you lose it, create another and revoke the old one. A workspace can hold up to 25 active keys. Revoked keys do not count against that.

​
Using a key

Send it as the X-API-Key header:
The same key also authenticates MCP, as a bearer token, so an agent can connect without a separate credential. See integrations for the config each client expects.

​
Rotating a key

Rotation is create, migrate, revoke, in that order:
  1. Create the new key.
  2. Deploy it wherever the old one is used.
  3. Confirm traffic has moved. The dashboard shows when each key was last used.
  4. Revoke the old key.
Revocation takes effect immediately, so revoking before step 3 will break whatever is still holding the old key. Rotate on a schedule you can actually keep, and rotate immediately whenever someone with access leaves.

​
If a key leaks

Revoke it first, ask questions second. A revoked key cannot be used again, and revocation is instant. Then check usage in the dashboard for calls you do not recognise. If you find any, write to [email protected] with the key prefix and roughly when you think it leaked, and we will help you work out what was called. Keys committed to a public repository are found by scanners in minutes, so treat any key that has ever touched a commit as leaked, even if you removed it in a later commit. Git history keeps it.

​
Keeping keys out of your code

Read the key from the environment rather than pasting it into source:
For a client-side application, do not ship the key at all. Call your own backend, and let it hold the key.

​
Publishable keys

There is one exception, and it is a separate kind of key. A publishable key starts with hf_pk_ and is designed to sit in your page source, because it authenticates the Logo endpoint — and an <img> tag cannot send a header. A publishable key serves logos and nothing else. It cannot call /v1/web/scrape or any other endpoint; those return 401. That boundary is what makes it safe to publish, so treat the two kinds differently: You can lock a publishable key to your own domains, which refuses requests whose Referer/Origin does not match. That stops a key lifted from your HTML being casually reused elsewhere. It is not access control — Referer is set by the client — and it does not apply to images already sitting in the CDN cache, so treat it as friction rather than a boundary. A leaked publishable key is not the emergency a leaked secret key is: the worst case is someone else’s site consuming your logo allowance. Revoke it and issue a new one; already-cached images may keep serving for up to a day.