Skip to main content
System API keys and system webhooks reach only the notes inside folders shared with all workspace members. The same scope applies to requests that change a note, not just to reads. A note a member keeps in a private folder, a note in a folder shared with only some people, and a note that sits in no folder at all are all outside that scope. Account API keys and Account webhooks carry a user identity and follow that user’s actual access, so this system boundary does not apply to them. A note that was never filed into a folder is easy to miss. It has no share target yet, so it does not count as a note in a fully shared folder.

​
Which notes does each key type read?

To tell the key types apart and to create one, see Authentication.
Widening a scope does not widen this boundary. A scope decides which APIs a key may call; the boundary on this page decides which notes those APIs reach. A system API key that holds note:read still cannot read notes outside fully shared folders, and one that holds note:write still cannot change them. A key created by an admin behaves the same way.

​
How do notes outside the scope appear?

Notes outside the scope return 404, not 403. That keeps the response from revealing whether the note exists at all, so it looks the same as a deleted note. If a request that worked yesterday starts returning 404, first check whether the note moved out of a fully shared folder.
If your integration judges its own behavior by note count, it cannot tell a narrowed scope from a workspace that genuinely has no notes.

​
How far does the scope reach into folders?

A system API key can do three things to a folder: rename it, move it, and reorder it. Listing or fetching folders, deleting a folder, and adding or removing notes from a folder all require an account API key regardless of folder type, and return 401 for a system API key. Those three actions are limited to fully shared folders. Targeting a private folder, or one shared with only some people, returns 403, and the same condition applies to the parent folder you move something into. Reordering rejects the whole request with 403 if even one folder in the list is not fully shared, so send only fully shared folders. Moving a folder never changes how it is shared. The option to inherit sharing from the new parent (sharingTypeUpdateStrategy) has no effect for a system API key. When you ask which folders a note belongs to (GET /v1/external/notes/{guid}/folders), the response carries only fully shared folders. If the same note also sits in a member’s private folder, that folder is left out. No error is raised here, the list is simply shorter, so an integration that sorts by folder name may see different results than an account API key would. Searching notes with a folderId filter is limited the same way. Passing the ID of a private folder returns 404.

​
Which APIs are outside this scope?

Voice File Job APIs and the voice_file_job.* events (created, completed, failed, deleted) are outside this scope.

​
If you need notes in private folders

Create and use an account API key. See Authentication for how to create one. You can also move the notes your integration needs into a fully shared folder.

​
What happens to keys you already created?

System API keys created and system webhooks registered before this read scope took effect keep their previous behavior for now, and are being moved over in stages. A key you create today can therefore return fewer notes than an older key, which is expected. Once a key is moved over, it does not only return fewer notes: renaming, moving, and reordering folders can start returning 403. A request that succeeds today will be rejected after the change if the folder is not fully shared. Check which keys and webhooks are due for the change on the API Keys and Webhooks screens in Tiro Platform.