Developer Resources

Add support for 1Password to your Mac app

If you’re a developer, you can use 1Password metadata in your own Mac app to search 1Password, open websites stored in the items, and more.

To access 1Password metadata, turn on this advanced preference in 1Password:

  1. Open and unlock 1Password.
  2. Choose 1Password > Preferences and click the Advanced icon.
  3. Turn on “Enable Spotlight and 3rd party app integrations”.

1Password will create metadata files and update them whenever changes are made. The metadata includes the following information about each item:

  • title
  • description
  • URLs
  • vault name
  • item category
  • account name
  • vault identifier
  • item identifier

Metadata only includes the information above. No passwords or custom fields are ever included in the metadata.

Locate the metadata files

An example of the folder structure for 1Password metadata files

1Password for Mac creates a separate metadata file for every item. The files are located in the following folder:


Inside that folder are subfolders. The name of each subfolder is a vault identifier, one for each vault.

Inside those subfolders are the metadata files. The name of each file includes both the vault identifier (vaultUUID) and the item identifier (UUID):


Each file contains key-value pairs in JSON format. An example of the contents of a 1Password metadata file:

	"accountName": "Smith Family",
	"categoryPluralName": "Logins",
	"categorySingularName": "Login",
	"categoryUUID": "001",
	"createdAt": 1527615745,
	"itemDescription": "Login from Private",
	"itemTitle": "Apple ID",
	"modifiedAt": 1527615745,
	"vaultUUID": "2qi2kzbzxrm5ijfire7wfbb23e",
	"uuid": "cxmvcuuzwrgfpni6r4j3fgtxb4",
	"vaultName": "Private",
	"websiteURLs": [
		"" ]

See also Appendix: Key-value pairs.


Use Quick Look to view a 1Password metadata file without opening it.

View an item

To open a 1Password item from your app, use the NSWorkspace -openURL:(NSURL *) (Objective-C) or open(URL)(Swift) method, with the file URL to the metadata file. You’ll see the contents of the item in the 1Password app.

If the item is a Login item, 1Password will open and fill the first URL in the item in the default browser. To show the contents of the item in the 1Password app instead, hold the Shift key. This behaviour is to maintain compatibility with Spotlight. For more control, see View or edit an item in 1Password.

Open a 1Password metadata file

To open a 1Password metadata file directly from your app:

  1. Obtain the vault identifier (vaultUUID), item identifier (UUID), and desired URL (websiteURLs) from the metadata file.

  2. Create a SHA256 hash of the URL.

  3. Construct a URL in the following format:


The URL will open through 1Password, where 1Password will validate the hash, then open and fill the URL in the default browser.

View or edit an item in 1Password

To view or edit items in 1Password, use these URL formats.

To view an item in the 1Password app:


To view an item in a detached window:


To edit an item in the 1Password app:


To edit an item in a detached window:


If you don’t specify a vault UUID, the currently selected vault will be used. For example:



Appendix: Key-value pairs

The following key-value pairs are used in 1Password metadata files:

the name of the account that contains the item (if applicable)
the category name in plural form
the category name in singular form
the category identifier
the item creation time (in Unix time)
a description of the type of item and the vault it belongs to in the format: categorySingularName from vaultName
the title of the item
the last modified time (in Unix time)
the vault identifier of the vault that contains the item
the item identifier, guaranteed to be unique within the same vault
the name of the vault that contains the item
an array of the URLs stored in the item (optional)

Appendix: Categories

The categoryUUID for each of the built-in categories:

categoryUUID Category
001 Login
002 Credit Card
003 Secure Note
004 Identity
005 Password
006 Document
100 Software License
101 Bank Account
102 Database
103 Driver License
104 Outdoor License
105 Membership
106 Passport
107 Reward Program
108 Social Security Number
109 Wireless Router
110 Server
111 Email Account