Authentication
Create an API key, choose its scopes and expiry, and authenticate requests.
The hostdocs API authenticates with a developer API key — an opaque token you create in the dashboard (issued and verified by Clerk). Keys are workspace-scoped: a key acts only within the account (personal or organization) it was created in.
Create a key
- Open the dashboard → API keys (admins only).
- Click Create key, give it a name, choose a scope and an expiry, and create it.
- Copy the token immediately — it is shown only once. We store only a hash and can't show it again. If you lose it, delete the key and create a new one.
Use a key
Send the token as a Bearer credential:
curl https://api.hostdocs.io/api/v1/pages \
-H "Authorization: Bearer $HOSTDOCS_KEY"Scoping headers
| Header | Purpose |
|---|---|
x-hostdocs-account-id | Target a specific workspace. Defaults to the key's workspace. |
x-hostdocs-site-id | Target a specific site. Defaults to the workspace's default site. |
Scopes
| Scope | Grants |
|---|---|
read | GET requests (list/read pages, sites, collections, records). |
write | Mutations (create / update / delete). A write key also reads. |
A request that exceeds its scope gets 403.
Expiry & revocation
- Keys can expire after 7 / 30 / 60 / 90 days, 1 year, or never.
- Revoke a key to disable it immediately, or delete it to remove it entirely.
- A revoked or expired key returns
401.
Key management endpoints are intentionally not part of the API — keys are managed only in the dashboard, and a key can never manage other keys.