Registry / auth-security / onepassword-sdk

onepassword-sdk

JSON →
library0.4.0pypypi✓ verified 85d ago

The 1Password Python SDK (version 0.4.0) offers programmatic read and write access to your secrets, vaults, and user/group permissions within 1Password. It supports authentication via the 1Password desktop app or 1Password Service Accounts, and is currently in its 0.x version series, indicating a rapid release cadence with ongoing feature additions.

pip install onepassword-sdk
INSTALL
IMPORT
SIG · ONEPASSWORD-SDK
O
onepassword-sdk
auth-securitypythonv0.4.0
Install
3.8s avg
Import
745ms
Disk
46MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.4.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.920 runs
installs and imports cleanly · install 0.0s · import 0.611s · 48.5MB
glibc
py 3.103.920 runs
installs and imports cleanly · install 3.8s · import 0.581s · 47MB
46MB installed
● package 46MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Client
from onepassword.client import Client
Primary client class for interacting with the 1Password API.
DesktopAuth
from onepassword.client import Client, DesktopAuth
Used for authenticating via the 1Password desktop application.

This quickstart demonstrates how to authenticate with the 1Password SDK using a Service Account token provided via an environment variable (`OP_SERVICE_ACCOUNT_TOKEN`). It then shows how to resolve a secret using a 1Password secret reference and how to list available vaults. Remember to replace placeholder values like 'op://MyVault/MyLoginItem/password' and ensure your service account has the necessary permissions.

import asyncio import os from onepassword.client import Client from onepassword.models import FieldPurpose async def main(): # Authenticate using a 1Password Service Account token from environment variable token = os.environ.get("OP_SERVICE_ACCOUNT_TOKEN") if not token: print("Error: OP_SERVICE_ACCOUNT_TOKEN environment variable not set.") return # Connect to 1Password with your integration details client = await Client.authenticate( auth=token, integration_name="My Test Integration", integration_version="v1.0.0", ) # Example: Retrieve a secret using a secret reference # Replace 'op://vault/item/field' with your actual secret reference URI try: secret_value = await client.secrets.resolve("op://MyVault/MyLoginItem/password") print(f"Retrieved secret: {secret_value}") # Example: List vaults (requires appropriate permissions) vaults = await client.vaults.list() print(f"Found {len(vaults)} vaults:") for vault in vaults: print(f"- {vault.name} (ID: {vault.id})") except Exception as e: print(f"An error occurred: {e}") finally: # Ensure the client connection is closed (if applicable, though often handled internally) pass if __name__ == '__main__': asyncio.run(main())
Debug
Known issues
breakingThe SDK is currently in version 0.x, which means breaking changes are possible between minor versions (e.g., 0.1.x to 0.2.0). Review release notes carefully when upgrading to a new minor version.
fix
Consult the official release notes and migration guides for each minor version upgrade to adapt your code. Patch releases (0.x.y to 0.x.z) should not contain breaking changes.
affects: 0.x series (e.g., 0.1.x -> 0.2.x)
gotchaOn Linux, the SDK requires `libssl 3` and `glibc 2.32` or later. Older distributions (e.g., Debian 11, Ubuntu 20.04) running `libssl 1.1.1` will encounter errors.
fix
Update your Linux distribution to a newer version or manually install the required `libssl 3` and `glibc 2.32` dependencies.
affects: All 0.x versions on affected Linux systems
gotchaThere are two distinct Python SDKs for 1Password: `onepassword-sdk` (for direct 1Password account interaction) and `onepasswordconnectsdk` (for self-hosted 1Password Connect servers). Using the wrong SDK for your deployment method will lead to connection or authentication failures.
fix
Ensure you install `onepassword-sdk` for direct account access (desktop app or service account authentication) or `onepasswordconnectsdk` if you are using a 1Password Connect server.
affects: All 0.x versions
gotchaThe SDK supports two primary authentication methods: 1Password desktop app (for local, human-in-the-loop) and 1Password Service Accounts (for automated access). Each requires specific setup and configuration.
fix
Choose the appropriate authentication method for your use case and follow the official documentation for setup, including creating a Service Account token or enabling desktop app integration in 1Password settings.
affects: All 0.x versions, especially from 0.4.0 onward with desktop app integration
Errors
Common errors & fixes
Client.authenticate() hangs indefinitely
When using `DesktopAuth`, the SDK's IPC channel with the 1Password desktop app can enter a broken state after the app goes through lock/unlock cycles or runs for an extended period, causing `Client.authenticate()` to block indefinitely without error or timeout.
fix
As a workaround, force-kill all 1Password processes (`pkill -9 -f 1Password` on macOS/Linux) and relaunch the 1Password desktop app before attempting to authenticate again. Ensure your 1Password desktop app is up-to-date.
invalid service account token, please make sure you provide a valid service account token as parameter: service account deserialization failed
This error indicates that the provided 1Password Service Account token is either missing, malformed, expired, or lacks the necessary permissions to authenticate or access the requested resources.
fix
Ensure the `OP_SERVICE_ACCOUNT_TOKEN` environment variable is correctly set with a valid and active service account token, or pass a valid token directly to the `Client.authenticate()` method. Verify the service account has the required permissions for the vaults and items you are trying to access.
ModuleNotFoundError: No module named 'src'
This error typically occurs during the installation of the `onepassword-sdk` when `pip` attempts to build the package from source in an environment that may have issues resolving internal package structures or dependencies, potentially related to Python version incompatibilities or outdated `setuptools`/`wheel`.
fix
Ensure your `pip`, `setuptools`, and `wheel` packages are up-to-date (`pip install --upgrade pip setuptools wheel`). Also, confirm you are using a compatible Python version (3.9 or later, avoiding very new or beta Python versions that might not be fully supported yet, like Python 3.14 at the time of some reports).
NameError: name 'Website' is not defined
This `NameError` occurs when specific data types, like `Website`, `ItemField`, or `AutofillBehavior`, are used in your code without being explicitly imported from the `onepassword.types` module.
fix
Add explicit import statements for the required types from `onepassword.types`. For example: `from onepassword.types import ItemField, Website, AutofillBehavior`.
Upgrade
Version history
0.4.0latest on PyPI · released Feb 10, 2026
Audit
Dependencies
PythonrequiredRequires Python 3.9 or later.
libssl 3requiredRequired for Linux distributions. Older versions like libssl 1.1.1 (e.g., Debian 11, Ubuntu 20.04) are not supported without an update.
glibc 2.32requiredRequired for Linux distributions. Older versions are not supported without an update.
Agent activity
9 hits · last 30 days
node
8
OpenAI (training)
1
Resources
onepassword-sdk — pip install onepassword-sdk · libregistry