1Password SDKs - 1Password Developer

1Password SDKs allow you to build integrations that programmatically interact with 1Password using Go, JavaScript, or Python. With 1Password SDKs, you can:

Secure your applications: Load secrets into your code with secret references or read environment variables from 1Password Environments.
Automate item management: Programmatically manage items in your 1Password account.
Securely share items: Share items with anyone, whether or not they have a 1Password account.
Manage vaults and access: Manage your team’s vaults and the permissions groups have in them.
Support biometric authorization: Build local integrations that users authorize with prompts from the 1Password desktop app for human-in-the-loop approval and minimal setup for end users.
Support automated access: Build integrations that authenticate with service account tokens for least-privilege access and automated environments.

See a full list of supported functionality.

Supported languages

Example integrations

See examples of how our partners have used SDKs to build integrations with 1Password:

About the current version

1Password SDKs are currently in version 0, which means they can meet the stability and scalability requirements of production use cases. During version 0, expect more frequent releases as we add additional features and languages.

There is a possibility of breaking changes when you upgrade from one version 0 release to another, for example 0.1.X to 0.2.0. Minor releases (0.1.X to 0.1.Y) will not include breaking changes.
Integration authors may need to update their code when updating the SDK version. Existing code and integrations won’t be affected, as these will have the SDK pinned at a specific version via package.json (JS), requirements.txt (Python), or go.mod (Go).
We will provide three months of support and security patches for version 0, so you can upgrade when it makes sense for your workflows and teams.

You can find information about the latest releases in the 1Password SDK release notes.

Get started

Before you get started, you’ll need to sign up for a 1Password account.

Step 1: Decide how you want to authenticate

You can choose between two authentication methods for 1Password SDKs: local authorization prompts from the 1Password desktop app or automated authentication with a 1Password Service Account.

1Password desktop app: Best for integrations that run locally on a user’s machine. Use desktop app authentication if you want minimal setup for end users, human-in-the-loop approval for sensitive workflows, user-specific auditing, if you need access to your full account, or if you need to perform vault management operations.
Service account: Best for automated access. Use a service account if you want a token-based authentication method that isn’t associated with an individual account to automate access, limit your integration to least privilege access, or for shared building. Service accounts can’t access your built-in Personal, Private, or Employee vault.

1Password desktop app
Service account

Install 1Password for Mac, Windows, or Linux.
Sign in to the account you want to use with your integration.
Select your account or collection at the top of the sidebar, then navigate to Settings > Developer.
Under Integrate with the 1Password SDKs, select Integrate with other apps.
If you want to authenticate with biometrics, navigate to Settings > Security, then turn on the option to unlock using Touch ID, Windows Hello, or system authentication.

Create a service account

Create a 1Password Service Account and give it access to the vaults and Environments you want your integration to be able to access.To allow your integration to update items, make sure to give the service account both read and write permissions in the appropriate vaults. To allow your integration to share items, also add the share permission.

Provision your service account token

We recommend provisioning your token from the environment. Use the following example to provision your token to an environment variable named OP_SERVICE_ACCOUNT_TOKEN. You can also provision your token in other ways, like by reading it from a file.

bash, sh, zsh
fish
Powershell

export OP_SERVICE_ACCOUNT_TOKEN=<your-service-account-token>

set -x OP_SERVICE_ACCOUNT_TOKEN <your-service-account-token>

$Env:OP_SERVICE_ACCOUNT_TOKEN = "<your-service-account-token>"

Step 2: Install the SDK

Install the SDK in your project.

Go
JavaScript
Python

go get github.com/1password/onepassword-sdk-go

npm install @1password/sdk

pip install onepassword-sdk

Step 3: Import the SDK

Import the SDK into your project.

Go
JavaScript
Python

import "github.com/1password/onepassword-sdk-go"

CommonJS

const sdk = require("@1password/sdk");

ES Modules

import sdk from "@1password/sdk";

from onepassword import *

Step 4: Initialize the SDK

When you initialize the SDK, you create a client instance that contains your configuration parameters. For desktop app integrations, you’ll need to provide your 1Password account name. For service account authentication, you’ll need to provide your service account token.

1Password desktop app
Service account

Replace your-account-name in the code below with your 1Password account name as it appears at the top of the left sidebar in the 1Password app.You can also use the account ID that 1Password CLI returns with op account list --format json. Use the value in the account_uuid field.Make sure to specify a name and version for your application in place of My 1Password Integration and v1.0.0.

Go
JavaScript
Python

This example prints an error message and exits if initialization fails. Because it writes the error to standard error, it uses Go’s os package, which you’ll need to import in your project. See the complete example in Step 5 for more context.

// Connects to the 1Password desktop app.
client, err := onepassword.NewClient(context.Background(),
  // TODO: Set to your 1Password account name.
  onepassword.WithDesktopAppIntegration("your-account-name"),
  // TODO: Set to your own integration name and version.
  onepassword.WithIntegrationInfo("My 1Password Integration", "v1.0.0"),
)
if err != nil {
  fmt.Fprintln(os.Stderr, "Initialization error:", err)
  os.Exit(1)
}

The 1Password JavaScript SDK is asynchronous and returns Promises. To make sure your code waits for 1Password to respond before moving to the next line, we recommend using the await keyword inside an async function. See the complete example in Step 5 for the full structure.

// Connects to the 1Password desktop app.
const client = await sdk.createClient({
  // TODO: Set to your 1Password account name.
  auth: new sdk.DesktopAuth("your-account-name"),
  // TODO: Set to your own integration name and version.
  integrationName: "My 1Password Integration",
  integrationVersion: "v1.0.0",
});

The Python SDK is asynchronous. To wait for a response from 1Password, use the await keyword inside an async function in your code. See the complete example in Step 5 for the full structure.

from onepassword import Client, DesktopAuth

# Connects to the 1Password desktop app.
client = await Client.authenticate(
    auth=DesktopAuth(
        # TODO: Set to your 1Password account name.
        account_name="your-account-name"
    ),
    # TODO: Set to your own integration name and version.
    integration_name="My 1Password Integration",
    integration_version="v1.0.0",
)

In the following example, the SDK gets the service account token string from the OP_SERVICE_ACCOUNT_TOKEN environment variable.Make sure to specify a name and version for your application in place of My 1Password Integration and v1.0.0.

Go
JavaScript
Python

// Gets your service account token from the OP_SERVICE_ACCOUNT_TOKEN environment variable.
token := os.Getenv("OP_SERVICE_ACCOUNT_TOKEN")

// Authenticates with your service account token and connects to 1Password.
client, err := onepassword.NewClient(context.Background(),
	onepassword.WithServiceAccountToken(token),
	// TODO: Set the following to your own integration name and version.
	onepassword.WithIntegrationInfo("My 1Password Integration", "v1.0.0"),
)
if err != nil {
	panic(err)
}

// Creates an authenticated client.
const client = await sdk.createClient({
  auth: process.env.OP_SERVICE_ACCOUNT_TOKEN,
  // Set the following to your own integration name and version.
  integrationName: "My 1Password Integration",
  integrationVersion: "v1.0.0",
});

import os

from onepassword import Client

# Get your service account token from the OP_SERVICE_ACCOUNT_TOKEN environment variable
token = os.getenv("OP_SERVICE_ACCOUNT_TOKEN")

# Create an authenticated client
client = await Client.authenticate(
    auth=token,
    # Set to your own integration name and version
    integration_name="My 1Password Integration",
    integration_version="v1.0.0",
)

Step 5: Start building

You can test your setup by building a simple integration that lists all the titles of all the vaults you or the service account has access to.

1Password desktop app
Service account

Go
JavaScript
Python

main.go

package main

import (
    "context"
    "fmt"
    "os"

    "github.com/1password/onepassword-sdk-go"
)

func main() {
    // Connects to the 1Password desktop app.
    client, err := onepassword.NewClient(context.Background(),
        // TODO: Set to your 1Password account name.
        onepassword.WithDesktopAppIntegration("your-account-name"),
        // TODO: Set to your own integration name and version.
        onepassword.WithIntegrationInfo("My 1Password Integration", "v1.0.0"),
    )
    if err != nil {
        fmt.Fprintln(os.Stderr, "Initialization error:", err)
        os.Exit(1)
    }

    // Lists vault titles
    vaults, err := client.Vaults().List(context.Background())
    if err != nil {
        panic(err)
    }
    for _, vault := range vaults {
        fmt.Println(vault.Title)
    }
}

example.js

import sdk from "@1password/sdk";

async function main() {
  // Connects to the 1Password desktop app.
  const client = await sdk.createClient({
    // TODO: Set to your 1Password account name.
    auth: new sdk.DesktopAuth("your-account-name"),
    // TODO: Set to your own integration name and version.
    integrationName: "My 1Password Integration",
    integrationVersion: "v1.0.0",
  });

  // Lists vault titles
  const vaults = await client.vaults.list({ decryptDetails: true });
  for (const vault of vaults) {
    console.log(vault.title);
  }
}

main();

example.py

import asyncio

from onepassword import Client, DesktopAuth


async def main():
    # Connects to the 1Password desktop app.
    client = await Client.authenticate(
        auth=DesktopAuth(
            # TODO: Set to your 1Password account name.
            account_name="your-account-name"
        ),
        # TODO: Set to your own integration name and version.
        integration_name="My 1Password Integration",
        integration_version="v1.0.0",
    )

    # Lists vault titles
    vaults = await client.vaults.list()
    for vault in vaults:
        print(vault.title)


if __name__ == "__main__":
    asyncio.run(main())

In the following example, the service account is scoped to a vault titled Development.

Go
JavaScript
Python

main.go

package main

import (
    "context"
    "fmt"
    "os"

    "github.com/1password/onepassword-sdk-go"
)

func main() {
    // Gets your service account token from the environment.
    token := os.Getenv("OP_SERVICE_ACCOUNT_TOKEN")

    client, err := onepassword.NewClient(context.Background(),
        onepassword.WithServiceAccountToken(token),
        // TODO: Set to your own integration name and version.
        onepassword.WithIntegrationInfo("My 1Password Integration", "v1.0.0"),
    )
    if err != nil {
        fmt.Fprintln(os.Stderr, "Initialization error:", err)
        os.Exit(1)
    }

    // Lists vault titles
    vaults, err := client.Vaults().List(context.Background())
    if err != nil {
        panic(err)
    }
    for _, vault := range vaults {
        fmt.Println(vault.Title)
    }
}

index.js

import sdk from "@1password/sdk";

async function main() {
  const client = await sdk.createClient({
    // Gets your service account token from the environment.
    auth: process.env.OP_SERVICE_ACCOUNT_TOKEN,
    // TODO: Set to your own integration name and version.
    integrationName: "My 1Password Integration",
    integrationVersion: "v1.0.0",
  });

  // Lists vault titles
  const vaults = await client.vaults.list({ decryptDetails: true });
  for (const vault of vaults) {
    console.log(vault.title);
  }
}

main();

example.py

import asyncio
import os
from onepassword import Client


async def main():
    # Gets your service account token from the environment.
    token = os.getenv("OP_SERVICE_ACCOUNT_TOKEN")

    client = await Client.authenticate(
        auth=token,
        # TODO: Set to your own integration name and version.
        integration_name="My 1Password Integration",
        integration_version="v1.0.0",
    )

    # Lists vault titles
    vaults = await client.vaults.list()
    for vault in vaults:
        print(vault.title)


if __name__ == "__main__":
    asyncio.run(main())

Visit the Go, JavaScript, or Python SDK GitHub repositories for more examples.

Get help

To get help with 1Password SDKs, join our Developer Slack workspace and ask a question in the #sdk channel. To request a new feature or report a bug, file an issue in the appropriate GitHub repo:

Documentation Index

​Supported languages

​Example integrations

​About the current version

​Get started

​Step 1: Decide how you want to authenticate

​Create a service account

​Provision your service account token

​Step 2: Install the SDK

​Step 3: Import the SDK

​CommonJS

​ES Modules

​Step 4: Initialize the SDK

​Step 5: Start building

​Get help

Supported languages

Example integrations

About the current version

Get started

Step 1: Decide how you want to authenticate

Create a service account

Provision your service account token

Step 2: Install the SDK

Step 3: Import the SDK

CommonJS

ES Modules

Step 4: Initialize the SDK

Step 5: Start building

Get help