1Password Connect Python SDK

Common errors

• ModuleNotFoundError: No module named 'onepasswordconnectsdk'

  cause The `onepasswordconnectsdk` library is not installed in the current Python environment.
  fix Run `pip install onepasswordconnectsdk` to install the library.

• onepasswordconnectsdk.errors.APIError: Unauthorized

  cause The 1Password Connect server rejected the request due to an invalid or missing access token, or the token does not have permissions for the requested operation.
  fix Double-check the `OP_CONNECT_TOKEN` environment variable or the token passed to `client.Client()`. Ensure it's correct and has the necessary permissions. Also, verify `OP_CONNECT_HOST` is correct and the server is running and accessible.

• TypeError: Client() missing 2 required positional arguments: 'host', 'token'

  cause The `client.Client` constructor was called without providing the `host` and `token` arguments, and the corresponding environment variables (`OP_CONNECT_HOST`, `OP_CONNECT_TOKEN`) were not set.
  fix Pass `host` and `token` directly to `client.Client(host, token)` or ensure `OP_CONNECT_HOST` and `OP_CONNECT_TOKEN` environment variables are properly set before running your application.

• KeyError: 'Cannot find vault with UUID: <your-vault-uuid>'

  cause The provided vault UUID does not exist on the 1Password Connect server, or the authenticated token lacks permission to access it.
  fix Verify the `vault_uuid` variable (or `OP_VAULT_UUID` environment variable) matches an existing vault's UUID in your 1Password account and that the Connect token has access to it.

Warnings

• breaking As of v2.0.0, the minimum supported Python version is 3.10. Older Python versions will result in installation or runtime errors.
  Fix: Upgrade your Python environment to 3.10 or newer. For projects requiring older Python versions, consider using `onepasswordconnectsdk<2.0.0`.
• gotcha Authentication with the 1Password Connect server requires a host URL and an access token. These can be passed directly to the `client.Client()` constructor or set via `OP_CONNECT_HOST` and `OP_CONNECT_TOKEN` environment variables. Incorrect or missing values will lead to 'Unauthorized' or connection errors.
  Fix: Verify that `OP_CONNECT_HOST` points to your running 1Password Connect server and `OP_CONNECT_TOKEN` is a valid, active token. Ensure the server is accessible from your application's environment.
• gotcha For v2.0.0 and later, custom HTTPX client configurations (e.g., timeout, SSL verification) should be managed through `onepasswordconnectsdk.config.ConfigClass`. Pass an instance of `ConfigClass` to the `config` argument of the `client.Client` constructor.
  Fix: Instead of attempting to configure HTTPX directly, use `from onepasswordconnectsdk.config import ConfigClass` and initialize `client.Client('host', 'token', config=ConfigClass(timeout=30.0, verify=False))`.
• gotcha Many SDK methods (e.g., `get_item`, `get_items`) primarily operate with 1Password vault and item UUIDs. While methods like `get_item_by_title` exist, using UUIDs is generally more robust and recommended to avoid ambiguity or issues with non-unique names.
  Fix: Prefer using UUIDs when interacting with vaults and items. Retrieve UUIDs programmatically or from the 1Password web interface/CLI.

Install

• pip install onepasswordconnectsdk Install stable version

Imports

• client

  from onepasswordconnectsdk import client

  Main entry point for interacting with the 1Password Connect API.
• models

  from onepasswordconnectsdk import models

  Contains data models for items, fields, vaults, etc.
• ConfigClass

  from onepasswordconnectsdk.config import ConfigClass

  Used for custom HTTPX client configuration (e.g., timeouts, SSL verification) as of v2.0.0.

Quickstart

Initialize the 1Password Connect client and fetch items from a specified vault. This example relies on environment variables for configuration. Make sure `OP_CONNECT_HOST`, `OP_CONNECT_TOKEN`, and `OP_VAULT_UUID` are set.

import os
from onepasswordconnectsdk import client

# Configure 1Password Connect client via environment variables:
# OP_CONNECT_HOST - e.g., "http://localhost:8080"
# OP_CONNECT_TOKEN - your 1Password Connect server token
# OP_VAULT_UUID - the UUID of a vault you want to access

host = os.environ.get("OP_CONNECT_HOST", "http://localhost:8080")
token = os.environ.get("OP_CONNECT_TOKEN", "dummy_token_replace_me")
vault_uuid = os.environ.get("OP_VAULT_UUID", "dummy_vault_uuid_replace_me")

if token == "dummy_token_replace_me" or vault_uuid == "dummy_vault_uuid_replace_me":
    print("Please set OP_CONNECT_HOST, OP_CONNECT_TOKEN, and OP_VAULT_UUID environment variables.")
    print("For this quickstart, we'll proceed but it will likely fail without real credentials.")

try:
    connect_client = client.Client(host, token)
    print(f"Connecting to 1Password Connect server at: {host}")
    items = connect_client.get_items(vault_uuid)
    print(f"Successfully retrieved {len(items)} items from vault {vault_uuid}.")
    for item in items[:3]: # Print first 3 item titles
        print(f"- {item.title}")
except Exception as e:
    print(f"Error: {e}")
    print("Ensure 1Password Connect server is running and accessible, and environment variables are correct.")