Guide
API keys and scopes
The console signs you in with your email. Everything else, your product, your pipelines and your agents, authenticates with a key that carries exactly the permissions it needs.
Sending a key
Every endpoint except /health requires a bearer token:
curl https://api.hayfork.dev/me -H "Authorization: Bearer $HAYFORK_KEY"GET /me tells you which workspace the key belongs to, its scopes, your plan and this month's usage. It is the quickest way to check a key works.
Scopes
Higher scopes include the lower ones.
| Scope | Allows | Give it to |
|---|---|---|
search | POST /search and POST /retrieve; list and read collections, sources, documents and chunks. | Website search boxes, in-app search, agents, MCP servers. Read-only, so safe in customer-facing code. |
ingest | Everything in search, plus create and delete collections and sources, upload files, start crawls, reindex. | Backend services, CI pipelines, sync jobs. |
admin | Everything in ingest, plus list, create and revoke API keys. | Workspace owners, provisioning scripts. |
Creating a key
In the console, open Settings, name the key, tick its scopes and optionally set an expiry, then create it. The plaintext is shown once. Copy it into your secret store now; the server keeps only a SHA-256 hash and cannot show it again.
From the API, with an admin key:
curl https://api.hayfork.dev/api-keys \
-H "Authorization: Bearer $ADMIN_KEY" -H "Content-Type: application/json" \
-d '{"name": "Docs search widget", "scopes": ["search"], "expires_in_days": 90}'The response includes the key in a key field, once. GET /api-keys lists keys by id, name, scopes and expiry, and DELETE /api-keys/KEY_ID revokes one immediately.
Rules
- A key can only grant scopes its creator holds. An
ingestkey cannot mint anadminkey. - Expiry is optional and ranges from 1 to 3,650 days.
- The last active
adminkey of a workspace cannot be revoked, so you cannot lock yourself out. - Revocation is immediate. Requests with a revoked or expired key get
401.
What errors mean
| Status | Meaning |
|---|---|
401 | No key, or a revoked or expired one. |
403 | Valid key without the required scope. The message names the scope. Also returned for ingest calls before your email is verified. |
404 | The resource does not exist in your workspace. Resources in other workspaces look identical, so ids cannot be probed. |
429 | A plan limit: sources, documents or searches this month. The message says which and how much room is left. |
search key can be shipped in a website widget: it cannot change anything and cannot see other workspaces. Its searches still count towards your monthly quota, so give it its own key and an expiry, and rotate it if you see traffic you do not recognise.