Pre-requisites

Better BibTeX & pinned citekeys

The extension's functionality is centered on the use of citekeys as a system to organize references. Citekeys are short, meaningful identifiers for library items ; within Roam, they're excellent as page titles because they're unique, concise, and meaningful. In Zotero, Better BibTeX is an amazing citekey manager ; it lets you define your own naming patterns, can ensure all of your citekeys are unique within your library - and a lot more !

Better BibTeX has another very important feature, which is necessary for the extension to work : it can pin citekeys to your items automatically. This is the only way for citekeys to be reachable by the Zotero Web API.

🛠️ Setup Checklist

• Install the Better BibTeX plugin for Zotero.

• Set the autoPinDelay parameter to 1, or anything greater than 0. This will determine how soon citekeys should be pinned, in seconds. (Note : this is a hidden parameter. To modify it, you'll need to go to Preferences > Advanced > Config Editor. You can search for "autoPinDelay", then double-click to change the value)

• Make sure to pin your existing citekeys. To do so, select all items in view (either with the mouse or the Ctrl-A keyboard shortcut), do a right-click, then navigate to Better BibTeX > Pin BibTeX key.

Zotero API credentials

The extension relies on the Zotero Web API (v3) to obtain data, which requires authentication. Zotero needs to make sure you're really you, so that it knows it can send over your data. This is implemented by an API key, and also your user ID if it's your own library you want to load. (Note: your user ID is different from your username ⚠️)

1. Log into your Zotero account in your browser, and navigate to Settings > Feeds/API (zotero.org/settings/keys).

2. You'll see a line of text at the top of the page, saying "Your userID for use in API calls is XXXXXXX". The XXXXXXX (typically a 6- or 7-digit expression) is your user ID ; make a copy of it somewhere; you'll be using it later.

3. Next, you need to set an API key. You can use a pre-existing one, if you like, or create a new one.

   1. Make sure to give the appropriate permissions to the API key you'll be using with the extension. If you want to be able to import your notes, check the box "Allow notes access". If you want to be able to import data from group libraries, select "Read Only" or "Read/Write".

   2. Once you save the key settings, the value of the API key will be displayed on the screen. This is the only time it will be available directly, for security purposes, so store its value now !

A configuration example. Here I'm creating a key that I can use to access my items and my notes.

Choosing the right permissions for your API key is very important. To import notes into Roam, check "Allow notes access". To add new items to Zotero, check "Allow write access". If you want to use 1 or more group libraries, be especially mindful of the settings available under "Group Permissions".