@1password/save-button

Save in 1Password Button API

Installation

NPM

npm install @1password/save-button --save-dev

Yarn

yarn add @1password/save-button -D

"Save in 1Password" button

The "Save in 1Password" button allows users to save an item to 1Password from a website. The data is provided by the site in a known format, so users can get information into 1Password safely, quickly and accurately, without filling out forms or relying on autosave.

Depending on the type of data you have, this could either be a traditional 1Password item (Login, Credit Card, Identity, etc) or an API key. For example, the 1Password Privacy.com integration integration uses this mechanism to save an API key to enable the integration.

How to save information with a "Save in 1Password" button

1. Import the onepassword-save-button component into your HTML file.

2. Add a onepassword-save-button button element to your page. The button is disabled by default.

3. Add the required attributes data-onepassword-type and value attributes to your onepassword-save-button element:

   • data-onepassword-type: The type of item to be saved. It must be one of these values:
     • credit-card
     • login
     • identity
   • value: A Base64-encoded JSON string containing a 1Password Save Request.

4. (Optional) Add an optional lang attribute, the locale code for desired localization. Currently we support the languages and locale codes below. If no lang attribute is provided, this package tries to determine the user's browser language using the NavigatorLanguage Web API. If no lang attribute is provided and the detected browser language is not in the supported list, the package will default to English.

   • German: "de"
   • English: "en"
   • Spanish: "es"
   • French: "fr"
   • Italian: "it"
   • Japanese: "ja"
   • Korean: "ko"
   • Portuguese: "pt"
   • Russian: "ru"
   • Chinese (Simplified): "zh-CN"
   • Chinese (Traditional): "zh-TW"

The 1Password extension will automatically check for the button on page load. When the button is found, its disabled attribute will be removed.

Single Page Apps

Subsequent checks, useful for single page apps, can be triggered by dispatching a CustomEvent on the document with type OPButtonAdded.

1Password Save Request

The Save Request contains the data to be saved, including field values and metadata.

SaveRequest

• title (string): The suggested title for the item to be saved
• fields (SaveRequestField[]): An array of fields to be saved to the item.
• notes (string): (optional) Notes which will be saved on the item. These can be formatted with Markdown.

SaveRequestField

• autocomplete (string): How the field should be filled. Allowed values are defined in the "Autofill" section of the HTML Living Standard.
• value (string): The value to be saved for the field. Should use the canonical format for the autocomplete type as given in the above spec.

Example

Page:

<script type="module">
  import "@1password/save-button/index.js";
</script>

...
<onepassword-save-button
  lang="en"
  data-onepassword-type="credit-card"
  value="ewoJInRpdGxlIjogIkFDTUUgQ3JlZGl0IENhcmQiLAoJImZpZWxkcyI6IFsKCQl7CgkJCSJhdXRvY29tcGxldGUiOiAiY2MtbmFtZSIsCgkJCSJ2YWx1ZSI6ICJXZW5keSBKLiBBcHBsZXNlZWQiCgkJfSwKCQl7CgkJCSJhdXRvY29tcGxldGUiOiAiY2MtbnVtYmVyIiwKCQkJInZhbHVlIjogIjQxMTExMTExMTExMTExMTEiCgkJfSwKCQl7CgkJCSJhdXRvY29tcGxldGUiOiAiY2MtZXhwIiwKCQkJInZhbHVlIjogIjIwMjUxMiIKCQl9LAoJCXsKCQkJImF1dG9jb21wbGV0ZSI6ICJjYy1jc2MiLAoJCQkidmFsdWUiOiAiMTIzIgoJCX0KCV0sCgkibm90ZXMiOiAiQWRkaXRpb25hbCBub3RlcyBjYW4gYmUgYWRkZWQgaW4gbWFya2Rvd24gb3IgcGxhaW50ZXh0LiIKfQ=="
>
</onepassword-save-button>

Save Request:

{
  "title": "ACME Credit Card",
  "fields": [
    {
      "autocomplete": "cc-name",
      "value": "Wendy J. Appleseed"
    },
    {
      "autocomplete": "cc-number",
      "value": "4111111111111111"
    },
    {
      "autocomplete": "cc-exp",
      "value": "202512"
    },
    {
      "autocomplete": "cc-csc",
      "value": "123"
    },
    {
      "autocomplete": "cc-type",
      "value": "visa"
    },
    {
      "autocomplete": "street-address",
      "value": "512 Main Street"
    },
    {
      "autocomplete": "address-level2",
      "value": "Cambridge"
    },
    {
      "autocomplete": "address-level1",
      "value": "MA"
    },
    {
      "autocomplete": "postal-code",
      "value": "12345"
    },
    {
      "autocomplete": "country",
      "value": "US"
    }
  ],
  "notes": "Notes can be markdown or plaintext!"
}

Security and Privacy

The "Save in 1Password" button is designed to respect the security and privacy of users:

• The transaction takes place locally between the page and the 1Password browser extension; no unencrypted data is sent over the network.
• User action is required to save items.
• 1Password shows a confirmation dialog after the button is clicked.
• Item URLs, if applicable, are determined solely by 1Password (i.e. a login item can only be filled on the domain on which it was saved).

Allowlist

Currently, 1Password implements an allowlist of domains which can use the "Save in 1Password" feature. Additionally, we have code which determines if any particular domain should use integration specific UI.