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, enable 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:

~/Library/Containers/com.agilebits.onepassword7/Data/Library/Caches/Metadata/1Password

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):

vaultIdentifier_itemIdentifier.onepassword-item-metadata

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 Personal",
	"itemTitle": "Apple ID",
	"modifiedAt": 1527615745,
	"vaultUUID": "2qi2kzbzxrm5ijfire7wfbb23e",
	"uuid": "cxmvcuuzwrgfpni6r4j3fgtxb4",
	"vaultName": "Personal",
	"websiteURLs": [
		"https://appleid.apple.com",
		"https://icloud.com",
		"https://itunes.com/" ]
}

See also Appendix: Key-value pairs.

Tip

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.

Open a URL

To open a URL 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:

    onepassword7://open_and_fill/vaultUUID/UUID/sha256_of_url
    

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

Appendix: Key-value pairs

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

accountName
the name of the account that contains the item (if applicable)
categoryPluralName
the category name in plural form
categorySingularName
the category name in singular form
categoryUUID
the category identifier
createdAt
the item creation time (in Unix time)
itemDescription
a description of the type of item and the vault it belongs to in the format: categorySingularName from vaultName
itemTitle
the title of the item
modifiedAt
the last modified time (in Unix time)
vaultUUID
the vault identifier of the vault that contains the item
uuid
the item identifier, guaranteed to be unique within the same vault
vaultName
the name of the vault that contains the item
websiteURLs
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
Published: