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.

​
Your default key

Every workspace starts with one secret key, made for you once you verify your email. It sits at the top of the API Keys page, and anyone in the workspace can reveal and copy it at any time. The dashboard playground uses it too, so you can try every endpoint without setting anything up. An admin can rotate it from the same page. Rotating gives you a new value straight away and the old one stops working at once, so update wherever it is used right after.

​
Creating more keys

Create more keys from the dashboard when you want one per app or per environment, so you can revoke one without touching the others. A key looks like this:
You see an extra key’s 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

For any key other than the default, 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.

​
Setting an expiry

When you create a key you can choose when it stops working: never, or after 30 days, 90 days or a year. The API Keys page shows when each key expires, and marks it Expired once it has. A call with an expired key is refused with a 401 that says when the key expired. Create a new key to replace it; an expired key cannot be renewed. An expiry is useful for a key you hand to a contractor, a trial or a one-off script, so it cleans itself up if nobody remembers to revoke it.

​
Locking a secret key to IP addresses

You can limit a secret key to the addresses your servers call from. Add them when you create the key, or later with Edit IPs on the API Keys page. Each entry is a single address such as 203.0.113.7 or a range such as 198.51.100.0/24, and IPv6 works the same way. A key holds up to 50 entries. A call from any other address is refused with a 403 that names the address it came from, so you can see what to add. This applies to MCP as well as to the REST endpoints. A key with no addresses works from anywhere, which is the default. This is what makes a leaked secret key useless to whoever found it, so it is worth setting on any key that only ever runs from fixed servers. Leave it empty for keys used from laptops, serverless functions or anywhere else whose address changes.

​
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 logo images, 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, because the browser sets Referer, 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. At worst, someone else’s site uses up your logo allowance. Revoke it and issue a new one; already-cached images may keep serving for up to a day.