A folder key stops at that folder
A master key starts with nh_mk_. A read key starts with nh_rk_. A write key starts with nh_wk_. A view-link secret starts with nh_vs_. The rest is 22 base62 characters and a 6-character checksum. API keys and view-link secrets are stored as SHA-256 hashes. A copy of the database does not contain a usable key. It does contain the note text.
You can mint a read or write key limited to one folder, give it an expiry, and revoke it. The app calls these agent keys; the API calls them scoped keys. Revocation takes effect on the next request. A scoped key cannot mint keys. Scoped keys survive master rotation unless you set revokeScopedKeys. A folder key does not grant the rest of the workspace. A master key does, until revoked or rotated. Scope is case-sensitive: team/a is inside team, and team-extra is outside. move must keep both paths inside the scope.
Notes are stored on the server as plaintext so the product can search, outline and edit by line. Version 1 does not encrypt note bodies end to end.
Example#
Authentication is the header Authorization: Bearer and the whole key, on /mcp and on /api/v1. The wire contract does not print a create-key response. The secret is shown once. Noteheld cannot show it again.
A view link is https://itsme.tail24ad1e.ts.net/s/<id>#<secret>. The page sends that secret as a header, then removes it from the address bar. We store only a hash. Our logs are designed to drop that header. The server does see the header. A view link can read. It cannot edit. View links are part of Pro. The form starts at 7 days, and you can choose no expiry. A view link with no expiry keeps working until you revoke it. It is not a safer link.
When it fails#
Unknown, bad checksum, expired, and revoked share one HTTP 401 body, key_invalid. The body does not say which of the four it was. The human sentence is "That key didn't work. Check it and try again."
A path outside the folder is outside_scope. The human screen is the missing-note screen. Do not infer that the id exists. The API hint text for outside_scope is not printed in the wire contract.
A read key cannot mutate, including correct and links.create. The error code for that refusal is not printed in the wire contract.
Do this instead#
Mint a write key for one folder, with an expiry. If it leaks, revoke it. The next request fails. Notes do not change.
A leaked master key can also rotate the master key. That locks you out. Rotating the master key does not revoke scoped keys or view links unless you set revokeScopedKeys. That flag revokes both. If the old key leaked, set it. A passkey can sign you in and rotate the master key. If the master key, the recovery kit and the passkey are all gone, we cannot recover the workspace.
Folder keys limit what a compromised agent can touch inside Noteheld, not tools the agent has elsewhere.