Authentication¶

zotio is keyless for the common case and only needs a Zotero Web API key when a write can't go through the local desktop connector.

Reads — no key¶

Reads go to your Zotero desktop app at localhost:23119. No API key is required while Zotero is running. Enable the local API once:

Zotero → Settings → Advanced → "Allow other applications to communicate with Zotero."

Connector creates¶

Creating new items in a personal library can run without a key through the local desktop connector (the channel the browser "Save to Zotero" button uses). The commands whose connector route needs only a running Zotero desktop are items create, the import commands (import doi, import url, import file, import pmid, import arxiv, import isbn), and import apply --via connector. items new always needs a Web API key, because it fetches the /items/new template from the Web API, which the local API does not serve. attachments add needs a key on every route, including --via connector, because the route finishes with a Web API write that moves the attachment to its parent.

Editing writes — key required¶

Editing writes route to the Zotero Web API and need a key:

• items update / delete / move, items enrich
• tags mutations, collections create/update/move/delete
• vault push / pull / resolve, most of import apply

Configure it once:

printf %s "$ZOTERO_API_KEY" | zotio auth set-token --stdin     # or export ZOTERO_API_KEY=<key>

Generate a key at https://www.zotero.org/settings/keys. The first Web API write prints a one-time stderr notice naming the target. A key is also required to read group libraries or to read live from the Web API while the desktop app is closed; reads from an already synced local mirror (--data-source local) need no key.

Check writability¶

zotio doctor      # reports a writes: line — available or read-only