@1password/save-button

Save in 1Password Button API

When you add the Save in 1Password button to your website, visitors can easily save their sign-in details, credit cards, or addresses to their 1Password account with a click. If you set up an integration with 1Password, the button can also be used to save API keys.

The Save in 1Password button on your site communicates directly with 1Password in the browser, so no unencrypted information leaves the customer's browser.

Step 1: Add the button to your site

To add the button to your site, you'll need to install the Save in 1Password button, build a save request, and import the button into your file with the required attributes and values. The button is disabled by default. When the page loads, 1Password will check for the button and make it available to the user. Item URLs, if applicable, are determined by 1Password, so a login item can only be filled for the domain on which it was saved.

The button element specifies the type of item to create and the information it'll contain. The information is a Base64-encoded save request in JSON format.

1.1 Install the button

To get started, install the Save in 1Password button using your preferred package manager:

npm

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

Yarn

yarn add @1password/save-button -D

Then import the package into your HTML file. For example:

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

1.2 Build a save request

The save request needs these values:

Field	Type	Description
title	string	The suggested title for the item to be saved.
fields	array	Each object in the array has these properties: autocomplete (string): The type of field to fill. value (string): The value to be filled in the field. Use the autocomplete field name and values defined in the "Autofill" section of the HTML Living Standard.
notes (optional)	string	Notes to save with the item. These can be formatted with Markdown.

For example:

const saveRequest = {
  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:
    "Plain text. You can use [Markdown](https://support.1password.com/markdown/) too.",
};

To encode the example above to a Base64 string in JSON format, use the built-in encodeOPSaveRequest function:

const encodedSaveRequest = encodeOPSaveRequest(saveRequest);

Then copy and paste the resulting Base64-encoded string as the value attribute of the Save in 1Password button. For example:

"eyJ0aXRsZSI6IkFDTUUgQ3JlZGl0IENhcmQiLCJmaWVsZHMiOlt7ImF1dG9jb21wbGV0ZSI6ImNjLW5hbWUiLCJ2YWx1ZSI6IldlbmR5IEouIEFwcGxlc2VlZCJ9LHsiYXV0b2NvbXBsZXRlIjoiY2MtbnVtYmVyIiwidmFsdWUiOiI0MTExMTExMTExMTExMTExIn0seyJhdXRvY29tcGxldGUiOiJjYy1leHAiLCJ2YWx1ZSI6IjIwMjUxMiJ9LHsiYXV0b2NvbXBsZXRlIjoiY2MtY3NjIiwidmFsdWUiOiIxMjMifSx7ImF1dG9jb21wbGV0ZSI6ImNjLXR5cGUiLCJ2YWx1ZSI6InZpc2EifSx7ImF1dG9jb21wbGV0ZSI6InN0cmVldC1hZGRyZXNzIiwidmFsdWUiOiI1MTIgTWFpbiBTdHJlZXQifSx7ImF1dG9jb21wbGV0ZSI6ImFkZHJlc3MtbGV2ZWwyIiwidmFsdWUiOiJDYW1icmlkZ2UifSx7ImF1dG9jb21wbGV0ZSI6ImFkZHJlc3MtbGV2ZWwxIiwidmFsdWUiOiJNQSJ9LHsiYXV0b2NvbXBsZXRlIjoicG9zdGFsLWNvZGUiLCJ2YWx1ZSI6IjEyMzQ1In0seyJhdXRvY29tcGxldGUiOiJjb3VudHJ5IiwidmFsdWUiOiJVUyJ9XSwibm90ZXMiOiJQbGFpbiB0ZXh0LiBZb3UgY2FuIHVzZSBbTWFya2Rvd25dKGh0dHBzOi8vc3VwcG9ydC4xcGFzc3dvcmQuY29tL21hcmtkb3duLykgdG9vLiJ9";

Or update the Base64-encoded value of the button:

document
  .querySelector("onepassword-save-button")
  .shadowRoot.querySelector("button[data-onepassword-save-button]")
  .setAttribute("value", encodedSaveRequest);

1.3 Add the button to your page

Add the Save in 1Password button to your page with the two required attributes: data-onepassword-type and value.

You can also add optional attributes to change the button language, color, theme, or padding: lang, class, data-theme, or padding.

Attribute	Value
data-onepassword-type	The type of item the button will create: credit-card, api-key, or login
value	The Base64-encoded save request.
lang (optional)	The language code for one of the supported languages. If no language attribute is provided, the package will determine the browser language using the NavigatorLanguage Web API. If the browser language isn’t supported, the package will default to English.
class (optional)	The color of the button: black or white If no class attribute is provided, the button color will default to blue.
data-theme (optional)	The optimized button theme for a website with a light or dark background: light or dark If no theme is provided the package will default to the light theme.
padding (optional)	Controls the padding of the button: normal or compact or none If no value is provided or a value of normal is provided, the button padding will default to 24 pixels. If a value of compact is provided, the padding will be 16px. If a value of none is provided, the padding will be 0px.

For example:

<onepassword-save-button
  data-onepassword-type="credit-card"
  value="ewoJInRpdGxlIjogIkFDTUUgQ3JlZGl0IE...=="
  lang="en"
  class="black"
  data-theme="dark"
  padding="normal"
>
</onepassword-save-button>

If you're building a single-page app, you may need to call the activateOPButton() function to activate the button. This will dispatch a custom event on the page to tell 1Password to enable the Save in 1Password button.

Step 2: Request to be added to the list of allowed sites

The Save in 1Password button only works on sites approved by 1Password. To request that your site be added to the list or for more information about the Save in 1Password button, contact the 1Password Partnerships team at [e-mail].

Appendix: Supported language codes

Language	Code	Language	Code	Language	Code
English	en	Japanese	ja	Spanish	es
French	fr	Korean	ko	Chinese, simplified	zh-CN
German	de	Portuguese	pt	Chinese, traditional	zh-TW
Italian	it	Russian	ru