Skip to main content
Every request to the API carries a project API key as a bearer token: Authorization: Bearer nohead_pk_…. A key belongs to one project and can do only what its scopes allow. Everything it changes is attributed to it in history and the activity log, so give each site, server, CI job and agent a key of its own.

​
Create a key

On the project’s API keys page, choose New API key, give it a name and choose its scopes. A key works until it is revoked, unless you choose when it Expires: in 30 days, 90 days or a year. An expired key stops working, as a revoked one does, and the API keys page shows it as Expired. Store the key in your app’s environment or secret manager, as NOHEAD_API_KEY. Developers, admins and owners can create keys, and a key never gets a scope its creator’s role doesn’t have (not_grantable). A project has at most 25 keys that aren’t revoked or expired.
The key is shown only once. If you lose it, create a new one and revoke the old one.
Signing in the CLI with nohead login creates a key too, once you approve it in the web app: it is named after the machine, such as “CLI on my-laptop”, and listed with the others. Revoking it signs only that machine’s CLI out. Approving another sign-in from that machine for the same project revokes it and creates a new one. Published records only is on by default. A published-only key, for your live site or app, sees published records only: no unpublished or deleted records and no history. It can take only the read scopes below, and it is rate-limited per client IP address, since it may ship inside an app people run, such as a mobile app. Its token starts nohead_pk_; every other key’s starts nohead_sk_. Turn it off for a key that writes, or that reads drafts for a preview.

​
Scopes

A request without the scope it needs is refused with 403, and the message names the scope. GET /v1/me shows a key’s project, scopes and whether it is published-only. Webhook payloads carry content, unpublished records included, so treat the webhook scopes like records:read on everything.

​
Keep keys safe

  • Give each key the fewest scopes that work: a site reads with records:read, plus assets:read to embed images.
  • Call the API from your servers and your site’s build, not from browser code: the API accepts browser requests only from the Nohead web app. For search in the browser, use a search token.
  • Keep keys that aren’t published-only on servers: never in a mobile app or anything else people can download.

​
Rename and revoke

The API keys page shows when each key was Last used, to the minute. Rename a key or revoke it from its menu.
Revoke key stops a key at once, and can’t be undone. To replace a key, create the new one, switch your app to it, then revoke the old one.
Keys keep working when the person who made them leaves the organization or changes role, so nothing breaks unannounced. The organization’s Members page lists them under Access to review, with the invitations those people sent, to revoke them in one go.