1Password Rust SDK

Build integrations that programmatically interact with 1Password.

Documentation | Examples

---

Note: This is an unofficial, community-maintained Rust SDK for the 1Password platform.

Requirements

• Rust 1.93.1 or later (edition 2024)
• A 1Password account with either:
  • A service account token, or
  • The 1Password desktop app installed

Get started

Add the SDK to your Cargo.toml:

[dependencies]
onepassword-sdk = { git = "https://github.com/lightcap/onepassword-sdk-rust" }

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

Option 1: 1Password desktop app

1Password desktop app authentication is best for local integrations that require minimal setup from end users and sensitive workflows that require human-in-the-loop approval.

1. Install the 1Password desktop app and sign in to your account.

2. Navigate to Settings > Developer.

3. Under Integrate with the 1Password SDKs, select Integrate with other apps.

4. 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.

5. Enable the desktop feature in your Cargo.toml:

   [dependencies]
   onepassword-sdk = { git = "https://github.com/lightcap/onepassword-sdk-rust", default-features = false, features = ["desktop"] }

6. Use the SDK in your project, replacing your-account-name with the name of your 1Password account:

use onepassword_sdk::{Client, SecretsApi};

fn main() {
    let client = Client::builder()
        .desktop_app_integration("your-account-name")
        .integration_info("My 1Password Integration", "v1.0.0")
        .build()
        .expect("Failed to create client");

    let secret = client
        .secrets()
        .resolve("op://vault/item/field")
        .expect("Failed to resolve secret");

    println!("Secret resolved successfully");
}

Option 2: 1Password Service Account

Service account authentication is best for automated access and limiting your integration to least privilege access.

1. Create a service account and give it the appropriate permissions in the vaults where the items you want to use with the SDK are saved.

2. Provision your service account token. We recommend provisioning your token from the environment. For example:

   macOS or Linux

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

   Windows

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

3. Use the SDK in your project:

use onepassword_sdk::{Client, SecretsApi};

fn main() {
    let token = std::env::var("OP_SERVICE_ACCOUNT_TOKEN")
        .expect("Set OP_SERVICE_ACCOUNT_TOKEN environment variable");

    let client = Client::builder()
        .service_account_token(&token)
        .integration_info("My 1Password Integration", "v1.0.0")
        .build()
        .expect("Failed to create client");

    let secret = client
        .secrets()
        .resolve("op://vault/item/field")
        .expect("Failed to resolve secret");

    println!("Secret resolved successfully");
}

Make sure to use secret reference URIs with the syntax op://vault/item/field to securely load secrets from 1Password into your code.

Usage

Resolve secrets

Use secret references to load individual secrets without retrieving full items:

use onepassword_sdk::{Client, SecretsApi};

let secret = client.secrets().resolve("op://vault/item/field")?;

Resolve multiple secrets at once:

let refs = vec![
    "op://vault/item/username".to_string(),
    "op://vault/item/password".to_string(),
];
let resolved = client.secrets().resolve_all(&refs)?;

Validate a secret reference URI without resolving it (no client required):

use onepassword_sdk::Secrets;

Secrets::validate_secret_reference("op://vault/item/field")?;

Manage items

Create, retrieve, update, delete, archive, and list items:

use onepassword_sdk::{Client, ItemsApi, ItemCreateParams, ItemCategory, ItemField, ItemFieldType};

// Create an item
let params = ItemCreateParams {
    title: "My Login".to_string(),
    category: ItemCategory::Login,
    vault_id: "vault-uuid".to_string(),
    fields: Some(vec![
        ItemField {
            id: "username".to_string(),
            title: "Username".to_string(),
            value: "user@example.com".to_string(),
            field_type: ItemFieldType::Text,
            section_id: None,
            details: None,
        },
        ItemField {
            id: "password".to_string(),
            title: "Password".to_string(),
            value: "my-secret-password".to_string(),
            field_type: ItemFieldType::Concealed,
            section_id: None,
            details: None,
        },
    ]),
    sections: None,
    notes: None,
    tags: None,
    websites: None,
    files: None,
    document: None,
};
let item = client.items().create(params)?;

// Get an item
let item = client.items().get("vault-uuid", "item-uuid")?;

// Update an item
let updated = client.items().put(item)?;

// List items
let overviews = client.items().list("vault-uuid", &[])?;

// Archive an item
client.items().archive("vault-uuid", "item-uuid")?;

// Delete an item
client.items().delete("vault-uuid", "item-uuid")?;

Batch operations

Create, get, or delete multiple items in a single call:

// Create multiple items at once
let response = client.items().create_all("vault-uuid", &[params1, params2])?;

// Get multiple items by ID
let item_ids = vec!["item-1".to_string(), "item-2".to_string()];
let response = client.items().get_all("vault-uuid", &item_ids)?;

// Delete multiple items
let response = client.items().delete_all("vault-uuid", &item_ids)?;

Manage files

Attach, read, delete files and replace documents on items:

use onepassword_sdk::{ItemsApi, ItemsFilesApi, FileCreateParams, FileAttributes, DocumentCreateParams};

// Attach a file to an item
let file_params = FileCreateParams {
    name: "config.json".to_string(),
    content: std::fs::read("config.json")?,
    section_id: "section-uuid".to_string(),
    field_id: "field-uuid".to_string(),
};
let updated_item = client.items().files().attach(item, file_params)?;

// Read a file
let content: Vec<u8> = client.items().files().read(
    "vault-uuid",
    "item-uuid",
    FileAttributes { name: "config.json".to_string(), id: "file-uuid".to_string(), size: 1024 },
)?;

// Delete a file from an item
let updated_item = client.items().files().delete(item, "section-uuid", "field-uuid")?;

// Replace a document item's content
let doc_params = DocumentCreateParams {
    name: "updated-doc.pdf".to_string(),
    content: std::fs::read("updated-doc.pdf")?,
};
let updated_item = client.items().files().replace_document(item, doc_params)?;

Share items

Share items securely with other users:

use onepassword_sdk::{ItemsApi, ItemsSharesApi, ItemShareParams, ItemShareDuration};

// Get the sharing policy for the item
let policy = client.items().shares().get_account_policy("vault-uuid", "item-uuid")?;

// Validate recipients
let recipients = client.items().shares().validate_recipients(
    policy.clone(),
    &["recipient@example.com".to_string()],
)?;

// Create the share
let share_params = ItemShareParams {
    recipients: Some(recipients),
    expire_after: Some(ItemShareDuration::SevenDays),
    one_time_only: false,
};
let share_link = client.items().shares().create(item, policy, share_params)?;

Generate passwords

Generate passwords without requiring a client:

use onepassword_sdk::{Secrets, PasswordRecipe, PasswordRecipeRandomInner};

// Generate a random password
let response = Secrets::generate_password(
    PasswordRecipe::Random(PasswordRecipeRandomInner {
        length: 32,
        include_digits: true,
        include_symbols: true,
    }),
)?;
println!("Password generated successfully");

Manage vaults

Create, retrieve, update, delete, and list vaults:

use onepassword_sdk::{Client, VaultsApi, VaultCreateParams, VaultGetParams, VaultUpdateParams};

// Create a vault
let params = VaultCreateParams {
    title: "Engineering Secrets".to_string(),
    description: Some("Shared secrets for the engineering team".to_string()),
    allow_admins_access: Some(true),
};
let vault = client.vaults().create(params)?;

// Get a vault overview (lightweight)
let overview = client.vaults().get_overview("vault-uuid")?;

// Get full vault details (with optional accessor info)
let vault = client.vaults().get("vault-uuid", VaultGetParams { accessors: Some(true) })?;

// Update a vault
let updated = client.vaults().update("vault-uuid", VaultUpdateParams {
    title: Some("Renamed Vault".to_string()),
    description: None,
})?;

// List vaults
let vault_overviews = client.vaults().list(None)?;

// Delete a vault
client.vaults().delete("vault-uuid")?;

Manage vault permissions

Grant, update, and revoke group permissions on vaults:

use onepassword_sdk::{VaultsApi, GroupAccess, GroupVaultAccess, permissions};

// Grant group access to a vault
let access = GroupAccess {
    group_id: "group-uuid".to_string(),
    permissions: permissions::READ_ITEMS | permissions::CREATE_ITEMS,
};
client.vaults().grant_group_permissions("vault-uuid", &[access])?;

// Update existing group permissions
let updated_access = GroupVaultAccess {
    vault_id: "vault-uuid".to_string(),
    group_id: "group-uuid".to_string(),
    permissions: permissions::READ_ITEMS | permissions::UPDATE_ITEMS | permissions::CREATE_ITEMS,
};
client.vaults().update_group_permissions(&[updated_access])?;

// Revoke group access
client.vaults().revoke_group_permissions("vault-uuid", "group-uuid")?;

Retrieve groups

use onepassword_sdk::{GroupsApi, GroupGetParams};

let group = client.groups().get("group-uuid", GroupGetParams {
    vault_permissions: Some(true),
})?;

Read 1Password Environments (beta)

use onepassword_sdk::EnvironmentsApi;

let response = client.environments().get_variables("environment-uuid")?;
for var in response.variables {
    println!("{}: {}", var.name, var.value);
}

Feature flags

Feature	Default	Description
wasm	Yes	Embedded WASM core via Extism. Use for standalone applications with service account authentication.
desktop	No	Native shared library integration with the 1Password desktop app. Use for local development and user-facing applications.

Error handling

All SDK operations return Result<T, SdkError>. The error variants are:

Variant	Description
Core	Error from the 1Password core engine
Serialization	JSON serialization/deserialization failure
Plugin	WASM plugin runtime error
Config	Client configuration error (e.g., missing token)
DesktopSessionExpired	Desktop app session expired (automatically retried)
RateLimitExceeded	API rate limit hit
SharedLib	Shared library loading or call error

use onepassword_sdk::{Client, SecretsApi, SdkError};

match client.secrets().resolve("op://vault/item/field") {
    Ok(_) => println!("Secret resolved successfully"),
    Err(SdkError::Core { name, message }) => {
        eprintln!("1Password error ({}): {}", name, message);
    }
    Err(e) => eprintln!("Error: {e}"),
}

Supported functionality

Item management

Operations:

• Retrieve secrets
• Retrieve items
• Create items
• Update items
• Delete items
• Archive items
• List items
• Share items
• Generate PIN, random, and memorable passwords

Field types:

• API Keys, Passwords, Concealed fields, Text fields, Notes
• SSH private keys, public keys, fingerprint and key type
• One-time passwords
• URLs, Websites (used to suggest and autofill logins)
• Phone numbers, Credit card types/numbers, Emails
• References to other items
• Address, Date, MM/YY
• File attachments and Document items
• Menu
• Passkeys

Vault management

• Retrieve vaults
• Create vaults
• Update vaults
• Delete vaults
• List vaults
• Manage group vault permissions
• Manage user vault permissions

User & access management

• Retrieve groups
• Provision, Retrieve, List, Suspend users
• List, Create groups, Update group membership

Environments management

• Read 1Password Environments (beta)

Compliance & reporting

• Watchtower insights
• Travel mode
• Events (use 1Password Events Reporting API directly)

Authentication

• 1Password Service Accounts
• User authentication (desktop app)
• 1Password Connect

Learn more

• Load secrets
• Read 1Password Environments (beta)
• Manage items
• Manage files
• Share items
• List vaults and items
• Manage vaults
• Manage vault permissions
• Manage groups
• 1Password SDK concepts

License

Licensed under the MIT License.