{"id":7461,"library":"onepasswordconnectsdk","title":"1Password Connect Python SDK","description":"The 1Password Connect Python SDK provides a convenient way to interact with the 1Password Connect API, allowing applications to retrieve and manage secrets stored in 1Password vaults. The current version is 2.0.0, released in July 2024, with a fairly active development cadence addressing features, fixes, and dependencies.","status":"active","version":"2.0.0","language":"en","source_language":"en","source_url":"https://github.com/1Password/connect-sdk-python","tags":["security","password-manager","1password","api-client","secrets-management"],"install":[{"cmd":"pip install onepasswordconnectsdk","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"HTTP client for communicating with the 1Password Connect server.","package":"httpx"}],"imports":[{"note":"Main entry point for interacting with the 1Password Connect API.","symbol":"client","correct":"from onepasswordconnectsdk import client"},{"note":"Contains data models for items, fields, vaults, etc.","symbol":"models","correct":"from onepasswordconnectsdk import models"},{"note":"Used for custom HTTPX client configuration (e.g., timeouts, SSL verification) as of v2.0.0.","symbol":"ConfigClass","correct":"from onepasswordconnectsdk.config import ConfigClass"}],"quickstart":{"code":"import os\nfrom onepasswordconnectsdk import client\n\n# Configure 1Password Connect client via environment variables:\n# OP_CONNECT_HOST - e.g., \"http://localhost:8080\"\n# OP_CONNECT_TOKEN - your 1Password Connect server token\n# OP_VAULT_UUID - the UUID of a vault you want to access\n\nhost = os.environ.get(\"OP_CONNECT_HOST\", \"http://localhost:8080\")\ntoken = os.environ.get(\"OP_CONNECT_TOKEN\", \"dummy_token_replace_me\")\nvault_uuid = os.environ.get(\"OP_VAULT_UUID\", \"dummy_vault_uuid_replace_me\")\n\nif token == \"dummy_token_replace_me\" or vault_uuid == \"dummy_vault_uuid_replace_me\":\n    print(\"Please set OP_CONNECT_HOST, OP_CONNECT_TOKEN, and OP_VAULT_UUID environment variables.\")\n    print(\"For this quickstart, we'll proceed but it will likely fail without real credentials.\")\n\ntry:\n    connect_client = client.Client(host, token)\n    print(f\"Connecting to 1Password Connect server at: {host}\")\n    items = connect_client.get_items(vault_uuid)\n    print(f\"Successfully retrieved {len(items)} items from vault {vault_uuid}.\")\n    for item in items[:3]: # Print first 3 item titles\n        print(f\"- {item.title}\")\nexcept Exception as e:\n    print(f\"Error: {e}\")\n    print(\"Ensure 1Password Connect server is running and accessible, and environment variables are correct.\")","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade your Python environment to 3.10 or newer. For projects requiring older Python versions, consider using `onepasswordconnectsdk<2.0.0`.","message":"As of v2.0.0, the minimum supported Python version is 3.10. Older Python versions will result in installation or runtime errors.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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))`.","message":"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.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Prefer using UUIDs when interacting with vaults and items. Retrieve UUIDs programmatically or from the 1Password web interface/CLI.","message":"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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Run `pip install onepasswordconnectsdk` to install the library.","cause":"The `onepasswordconnectsdk` library is not installed in the current Python environment.","error":"ModuleNotFoundError: No module named 'onepasswordconnectsdk'"},{"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.","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.","error":"onepasswordconnectsdk.errors.APIError: Unauthorized"},{"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.","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.","error":"TypeError: Client() missing 2 required positional arguments: 'host', 'token'"},{"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.","cause":"The provided vault UUID does not exist on the 1Password Connect server, or the authenticated token lacks permission to access it.","error":"KeyError: 'Cannot find vault with UUID: <your-vault-uuid>'"}]}