Scopes & permissions

Scopes cap what a key may attempt. Your workspace permissions decide what it can actually touch.

Scopes#

A key has one or two scopes, chosen when it is created.

Scopes
NameTypeDescription
readrequiredscopeEvery GET. Every key has it.
writeoptionalscopePOST, PATCH, DELETE, and notes. Turn on "Allow writes" when creating the key.

A read-only key that tries to write gets a 403:

json
{
  "error": {
    "code": "write_scope_required",
    "message": "This key is read-only. Create a key with write access to make changes."
  }
}

Workspace permissions#

A key never grants more than its owner has. Private modules, record sharing, admin rights, and pages hidden under Settings all carry over, because every request runs as you against the same row-level rules the app uses.

  • Records you cannot see are simply absent from lists and answer 404 not_found on direct reads.
  • Updates and deletes you are not allowed to make also answer 404 not_found; a note on a record you can see but not edit answers 403 forbidden.
  • A resource whose page is turned off for the workspace answers 404 module_hidden.
  • If the owner is removed from the workspace, every request answers 403 membership_revoked.

Attribution#

Every create, update, delete, and note is logged on the record's activity timeline as you, marked source: apiwith the key's prefix, so teammates can tell an API change from one made in the app.