POST /v1/keys), shown once, and revoked in one call. The wire details are in Authentication; this page is about choosing the right key.
Shape
ni_live_<key id>_<secret>. The key id is the part you see in the console list and use to revoke; the secret is stored hashed and never shown again. A key minted with env: "test" reads ni_test_... and behaves identically; the prefix is for your own bookkeeping.
Account-wide or bound to one site
A key with nosite is account-wide: it sees every site on the account. A key created with site set to a site id is bound: it can read and change that one site, its facts and its views, and nothing else. It cannot list the account’s sites, and it cannot create or delete a site.
Bind a key whenever the program only needs one site. A nightly job that pushes a store’s codes to the facts sheet gets a bound key with facts:write; if it leaks, the blast radius is one sheet on one site.
Role
viewer keys can only make GET requests; any write answers 403 read_only. admin keys can write within their scopes. Default is viewer.
Scopes
sites:read, sites:write, facts:read, facts:write. A key with no scopes listed has all four; a key with any scope listed has only those. The views (store, reasons, moments) need sites:read. Creating a site needs sites:write and an account-wide key. Nothing on the key can mint or revoke keys; that is a person’s job, so a leaked key can never make itself more keys.
Expiry and limits
expires_at is optional and must be in the future; an expired key answers 401 and stays in the list until revoked. An account holds at most 25 live keys. last_used_at on the list tells you which keys are dead weight.
Rate limit
600 requests a minute per key. The views are the heavy calls; poll the store view once a minute at most, and the moments list withbefore for paging rather than re-reading from the top.