1Password Python SDK

Install the SDK using pip:

pip install onepassword-sdk

Requirements

Ensure your environment meets the following criteria:

• python 3.9 or later
• libssl 3
• glibc 2.32 or later

Note: If you are on a Linux distribution using libssl 1.1.1 (e.g., Debian 11 or Ubuntu 20.04), you must update to a later version or install the required dependencies.

Before running examples or using the SDK with a service account, you must export your service account token and the target vault UUID as environment variables.

Required variables:

• OP_SERVICE_ACCOUNT_TOKEN: Your valid 1Password service account token.
• OP_VAULT_ID: The UUID of the vault you wish to interact with.

export OP_SERVICE_ACCOUNT_TOKEN="<your token>"
export OP_VAULT_ID="<your vault uuid>"

Use this method for local integrations that require human-in-the-loop approval (e.g., biometrics via Touch ID or Windows Hello).

1. Install the 1Password desktop app and sign in.
2. In the app, go to Settings > Developer and select Integrate with other apps under 'Integrate with the 1Password SDKs'.
3. (Optional) Enable biometrics in Settings > Security.
4. In your code, use DesktopAuth and provide your account_name (the name appearing at the top left of your 1Password sidebar).

import asyncio
from onepassword.client import Client, DesktopAuth

async def main():
    client = await Client.authenticate(
        auth=DesktopAuth(account_name="your-account-name"),
        integration_name="My 1Password Integration",
        integration_version="v1.0.0",
    )
    # ...

asyncio.run(main())

To execute the demonstration script which showcases various vault and item operations, navigate to the project root directory and run the example.py file using Python.

python example/example.py

A 1Password Item is a collection of fields, sections, and metadata.

Key components include:

• Fields: Individual data points (e.g., username, password, URL) identified by an id and title. Fields have a field_type (e.g., Text, Concealed, Totp, SshKey).
• Sections: Logical groupings of fields within an item.
• Websites: A list of Website objects used for autofill behavior (e.g., ExactDomain, AnywhereOnWebsite).
• Files: Items can contain ItemFile objects stored within specific sections or fields.
• Metadata: Includes tags, notes, category (e.g., Login, SecureNote, Password), and timestamps (created_at, updated_at).

Note that some fields provide specialized details via ItemFieldDetails, such as OtpFieldDetails for TOTP codes or SshKeyAttributes for SSH keys.

A Vault represents a container for items.

Key attributes include:

• ID and Title: Unique identifier and display name.
• Vault Type: Can be personal, everyone, transfer, or userCreated.
• Versions: content_version increments when items change; attribute_version increments when vault metadata (like title) changes.
• Access: Managed via VaultAccess objects, which define how a user or group accesses the vault and what permissions they hold.

To securely load secrets into your code, use secret reference URIs with the syntax op://vault/item/field. Use the client.secrets.resolve() method to retrieve the actual value.

import asyncio
from onepassword.client import Client, DesktopAuth

async def main():
    client = await Client.authenticate(
        auth=DesktopAuth(account_name="your-account-name"),
        integration_name="My Integration",
        integration_version="v1.0.0",
    )
    
    # Resolves the secret value from the URI
    value = await client.secrets.resolve("op://vault/item/field")
    print(value)

asyncio.run(main())

To modify an existing vault or remove it entirely:

1. Update: Use update with VaultUpdateParams to change vault settings. async def update(self, vault_id: str, params: VaultUpdateParams) -> Vault

2. Delete: Use delete to remove a vault by its ID. async def delete(self, vault_id: str) -> None

# Update
await vaults.update(vault_id="vault_id", params=VaultUpdateParams(name="New Name"))

# Delete
await vaults.delete(vault_id="vault_id")

Generate a new item sharing link. This requires an Item object, an ItemShareAccountPolicy, and ItemShareParams. The method returns the sharing link as a string.

# item: Item
# policy: ItemShareAccountPolicy
# params: ItemShareParams
sharing_link = await items_shares.create(item=item, policy=policy, params=params)
print(f"Sharing link: {sharing_link}")

Use the attach method of the ItemsFiles class to add files to a 1Password Item. This method requires the Item object and a FileCreateParams object containing the file details.

Returns the updated Item object.

await items_files.attach(item=my_item, file_params=my_file_params)