Appearance
API keys
Everything a person can do over HTTP, a program can do with a key — and nothing more.
A key belongs to one account in one workspace and acts as that account: what it writes is attributed to them, and what it may do is its scopes narrowed by their role, worked out on every request. Demote somebody and their keys lose the same access in the same instant.
Making one
bash
curl -X POST https://notes.example.com/api/keys \
-H 'content-type: application/json' \
-b "$YOUR_SESSION_COOKIE" \
-d '{"name": "Nightly export", "scopes": ["read"]}'json
{
"key": { "id": "…", "name": "Nightly export", "scopes": ["read"], "expiresAt": null },
"token": "nf_3f2b1c4d5e6f4a8b9c0d1e2f3a4b5c6d_Xq…"
}The token is shown once. Only a hash of it is stored, the same way sign-in links are kept — until it is revoked, that table is a list of live credentials, and a database leak should not hand them over. Lost it? Rotate the key; nothing else changes.
Every member can also make and revoke their own in Settings → Account. Making your own key needs no permission: it adds no power, it makes the power you already have reachable by a program. Seeing or revoking somebody else's needs the manage_api_keys capability.
Using one
bash
curl https://notes.example.com/api/pages -H "authorization: Bearer $NOTESFLOW_API_KEY"Every route under /api accepts a key, with two exceptions below. A key is read only when there is no session cookie, so a browser is never authenticated by a header it did not mean to send.
From the commands
pnpm export:git, pnpm mirror:git, pnpm merge:git and pnpm import:md all read NOTESFLOW_API_KEY:
bash
NOTESFLOW_API_KEY=nf_… pnpm export:git ./notes-exportBefore this they needed a session cookie copied out of a browser's developer tools, which expired and could not be revoked on its own. NOTESFLOW_COOKIE still works.
An export needs read; merge-back needs write as well. Import needs create_root_pages too when it lands at the top of the workspace, which it does unless you pass --parent <pageId>: making a page at the root is a capability of its own, and a key only has the capabilities it names. With --parent, read and write are enough — the import is then an edit to that page.
bash
curl -X POST …/api/keys -b "$COOKIE" -H 'content-type: application/json' \
-d '{"name": "Docs import", "scopes": ["read", "write", "create_root_pages"]}'Scopes
| Scope | What it allows |
|---|---|
read | Reading pages, blocks, comments, search, the timeline |
propose | Reading, and suggesting changes — a proposal, or a merge offered rather than applied |
write | Writing them |
| a capability name | That capability — manage_members, read_audit, manage_views, and the rest |
Scopes narrow; they never grant. A key holding read_audit whose owner may not read the audit log cannot read it either. A key with none of read, propose or write sees no pages at all.
propose — the scope to give an agent
A propose key can read a page and write a suggestion; it cannot change one. Its suggestions arrive as proposals, which somebody with write accepts block by block or turns down — so an automated editor tidying a workspace produces a queue of reviewable changes rather than edits nobody agreed to.
It caps at comment, and a cap is all it is: on a page its owner may only read, a propose key may only read there too.
bash
curl -X POST …/api/keys -b "$COOKIE" \
-d '{"name": "Tidying agent", "scopes": ["read", "propose"]}'Not overwriting somebody
A page read carries an etag — a short fingerprint of its title, its place in the tree, its properties and its journal date. Quote it back in If-Match when you change the page, and a version that has moved on since you read it is refused with 412 instead of overwritten:
bash
etag=$(curl -sD- -o/dev/null …/api/pages/$ID -H "authorization: Bearer $KEY" \
| tr -d '\r' | awk '/^etag:/{print $2}')
curl -X PATCH …/api/pages/$ID -H "authorization: Bearer $KEY" \
-H "if-match: $etag" -H 'content-type: application/json' \
-d '{"props": {"status": "done"}}'A successful PATCH answers with the new etag, so a run of edits needs no re-read between them. Send If-Match: * to mean "only if it still exists".
Sending none keeps the old behaviour — last write wins. Every caller written before this existed sends none, and refusing them to guard against a race most of them are not in would break far more than it protected.
Page text never needed this: POST /api/pages/<id>/merge is a three-way merge, so two people writing prose at once both keep their work. If-Match is for the things a merge cannot reconcile — a title, a parent, a property — and properties are a database view's row data, so losing one loses content rather than decoration.
A key in a URL
Exactly one route accepts a key in its address instead of a header: the timeline's Atom feed, because feed readers cannot send headers. There, and only there, ?key= works — and only for a key whose scopes are exactly ["read"]. Any other key is refused, since a URL is copied far more freely than a header. Request logs record paths without their query strings.
What a key cannot do
- Sign in, or sign anything else in.
/api/auth/*is refused — exceptGET /api/auth/me, which answers "who am I here", a question about the key itself. - Administer the deployment.
/api/platform/*is a person's job. - Make or revoke keys, or make service identities. A credential that can mint credentials cannot be revoked in one act.
- Open a collaboration socket. Live editing is a person with a cursor; the HTTP API covers reading and writing content.
Rotating, expiring, revoking
bash
curl -X POST …/api/keys/<id>/rotate -b "$COOKIE" # new secret, same key and scopes
curl -X DELETE …/api/keys/<id> -b "$COOKIE" # revoked, and revoked stays revokedPass expiresAt (an ISO date) when creating a key to have it stop on its own. An expired, revoked, mistyped or never-existed key all answer 401 in exactly the same way: anything finer would be a way to learn which keys are real.
Service identities
A key belonging to a person stops working when that person leaves. For work that should outlive anybody — a nightly export, a form that files into a journal — make an identity for the program itself:
bash
curl -X POST …/api/services -b "$COOKIE" \
-d '{"name": "Nightly export", "role": "member", "scopes": ["read", "write"]}'It is an ordinary account with a role, which is what lets the timeline and page history name it as the author of what it wrote. It has no mailbox — its address is in service.invalid, a domain reserved so that it can never receive mail — and no sign-in road accepts it.
Making one is appointing a member, so it takes manage_members. Removing one (DELETE /api/services/<id>) disables it and revokes its keys together; it is never deleted, because what it wrote stays in the log and the log needs an account to resolve its author to.
Limits
Each key may make 600 requests a minute by default (NOTESFLOW_API_RATE), answered with 429 and a retry-after header beyond that. Refused requests count too: a refusal still costs the server work, and a free probing loop is what a limit is for.
The count is per server process, like the sign-in limits — N processes permit N times the limit.
What is recorded
Creating, rotating and revoking a key, and creating or disabling a service identity, are written to the workspace's audit log. Each key records when it was last used, written at most once a minute and off the request's path, so a forgotten key can be found and retired.