Rust SDK

Detailed Rust SDK docs for Keeper Secrets Manager

Download and Installation

Requirements

Rust 1.87 or later is required to use this SDK. This minimum version ensures compatibility with Edition 2024 dependencies and recent security patches.

Adding as Package using Cargo

cargo add keeper-secrets-manager-core

For more information, see https://crates.io/crates/keeper-secrets-manager-core

Source Code

Find the Rust source code in the GitHub repository

Using the SDK

Initialise

Using token only to generate a new config (for later usage) requires at least one read operation to bind the token and fully populate config.json

SecretsManager::new(client_options)?

use keeper_secrets_manager_core::{
    core::{ClientOptions, SecretsManager},
    storage::FileKeyValueStorage,
    custom_error::KSMRError
};

fn main()-> Result<(), KSMRError>{
    let token = "<Your One time token>".to_string();
    let config = FileKeyValueStorage::new_config_storage("test.json".to_string())?;
    let client_options = ClientOptions::new_client_options_with_token(token, config);
    let mut secrets_manager = SecretsManager::new(client_options)?;
    Ok(())
}

Parameter

Required

Description

Type

token

Yes

One Time Access Token

String

config

Yes

Storage Configuration

KeyValueStorage

Proxy Configuration

To route all SDK traffic through an HTTP or HTTPS proxy, set proxy_url on ClientOptions or use environment variables. The proxy applies to all SDK operations: API calls, file uploads, file downloads, thumbnail downloads, and caching requests.

let mut client_options = ClientOptions::new_client_options(config);
client_options.proxy_url = Some("http://proxy.example.com:8080".to_string());
let mut secrets_manager = SecretsManager::new(client_options)?;

use keeper_secrets_manager_core::{
    core::{ClientOptions, SecretsManager},
    storage::InMemoryKeyValueStorage,
    custom_error::KSMRError
};
fn main() -> Result<(), KSMRError> {
    let config_string = "your_base64_goes_here".to_string();
    let config = InMemoryKeyValueStorage::new_config_storage(Some(config_string))?;
    let mut client_options = ClientOptions::new_client_options(config);

    // Authenticated proxy: http://user:pass@host:port
    client_options.proxy_url = Some("http://user:[email protected]:8080".to_string());

    let mut secrets_manager = SecretsManager::new(client_options)?;
    let secrets = secrets_manager.get_secrets(Vec::new())?;
    Ok(())
}

Option

Description

ClientOptions.proxy_url

Set proxy programmatically. Takes precedence over environment variables.

HTTP_PROXY / HTTPS_PROXY

Standard proxy environment variables. Used when proxy_url is not set.

KSM_PROXY_URL

Used by caching_post_function when a proxy is needed for cache requests. Not read by make_caching_post_function. Configure the proxy on the reqwest::blocking::Client you pass to that factory instead.

ClientOptions.insecure_skip_verify

Set to true to disable TLS certificate verification. Not recommended outside testing.

KSM_SKIP_VERIFY

Environment variable alternative to insecure_skip_verify. Set to true to skip verification, false (default) to require it.

Retrieve Secrets

let records_filter = Vec::new(); // add record filters of needed based on UID
let secrets = secrets_manager.get_secrets(records_filter)?;

use keeper_secrets_manager_core::{
    core::{ClientOptions, SecretsManager},
    custom_error::KSMRError,
    storage::FileKeyValueStorage
};

fn main()-> Result<(), KSMRError>{
    let token = "<Your One time token>".to_string();
    let file_name = FileKeyValueStorage::new_config_storage("test.json".to_string())?;
    let client_options = ClientOptions::new_client_options_with_token(token, file_name);
    
    let mut secrets_manager = SecretsManager::new(client_options)?;
    let secrets = secrets_manager.get_secrets(Vec::new())?;

    for secret in secrets {
        secret.print();
        println!("---");
    }
    Ok(())
}

use keeper_secrets_manager_core::{
    core::{ClientOptions, SecretsManager},
    custom_error::KSMRError,
    storage::FileKeyValueStorage
};

fn main()-> Result<(), KSMRError>{
    let token = "<Your One time token>".to_string();
    let file_name = FileKeyValueStorage::new_config_storage("test.json".to_string())?;
    let client_options = ClientOptions::new_client_options_with_token(token, file_name);
    
    let mut secrets_manager = SecretsManager::new(client_options)?;
    let records_filter = vec!["record_uid1".to_string(), "record_uid2".to_string()]; // add record filters if needed based on UID
    let secrets = secrets_manager.get_secrets(records_filter)?;

    for secret in secrets {
        secret.print();
        println!("---");
    }
    Ok(())
}

Parameter

Type

Required

Default

Description

uids

Vec<String>

Yes

Vec::new()

Record UIDs to fetch. Pass an empty vec to fetch all records the application has access to.

Returns

Type: Result<Vec<Record>, KSMRError>

All Keeper records, or records with the given UIDs

default - we will get all records which the token given has access to

Get Secrets with Options

Use get_secrets_with_options() to request additional data such as GraphSync linked records.

let query_options = QueryOptions::with_links(Vec::new(), Vec::new(), true);
let secrets = secrets_manager.get_secrets_with_options(query_options)?;

use keeper_secrets_manager_core::{
    core::{ClientOptions, SecretsManager},
    dto::payload::QueryOptions,
    storage::InMemoryKeyValueStorage,
    custom_error::KSMRError
};
fn main() -> Result<(), KSMRError> {
    let config_string = "your_base64_goes_here".to_string();
    let config = InMemoryKeyValueStorage::new_config_storage(Some(config_string))?;
    let client_options = ClientOptions::new_client_options(config);
    let mut secrets_manager = SecretsManager::new(client_options)?;

    // Request linked records alongside the primary secrets
    // Vec::new() means no UID or folder filter — fetch all secrets
    let query_options = QueryOptions::with_links(Vec::new(), Vec::new(), true);
    let secrets = secrets_manager.get_secrets_with_options(query_options)?;

    for secret in &secrets {
        println!("Secret: {}", secret.title);
        if !secret.links.is_empty() {
            println!("  Linked records: {}", secret.links.len());         }
      }
    Ok(())
}

Parameter

Type

Required

Description

query_options

QueryOptions

Yes

Options for the request

QueryOptions Fields:

Field

Type

Description

records_filter

Vec<String>

Record UIDs to fetch. Empty vec fetches all records.

folders_filter

Vec<String>

Folder UIDs to filter by. Empty vec applies no folder filter.

request_links

Option<bool>

Set to true to include GraphSync linked records in the response. Linked records are available on Record.links.

Returns

Type: Result<Vec<Record>, KSMRError>

All records matching the query options.

Retrieve Values from Secret

Retrieve a password

This shortcut gets the password of a secret once that secret has been retrieved from Keeper Secrets Manager.

secret.get_standard_field_value("password", true);

use keeper_secrets_manager_core::{
    core::{ClientOptions, SecretsManager},
    storage::InMemoryKeyValueStorage,
    custom_error::KSMRError
};
fn main()-> Result<(), KSMRError>{
    // setup secrets manager
    let config_string = "your_base64_goes_here".to_string();
    let config = InMemoryKeyValueStorage::new_config_storage(Some(config_string))?;
    let client_options = ClientOptions::new_client_options(config);
    let mut secrets_manager = SecretsManager::new(client_options)?;

    // get a specific secret by record UID
    let secrets = secrets_manager.get_secrets(vec!["record_uid".to_string()])?;
    let secret = match secrets.len(){
        0 => return Err(KSMRError::CustomError("no secret with given uid is found".to_string())),
        _ => &secrets[0],
    };
    // get password from record
    let my_secret_password = secret.get_standard_field_value("password", true)?;
    Ok(())
}

Retrieve Standard Fields

secret.get_standard_field_value("FIELD_TYPE", true);

use keeper_secrets_manager_core::{
    core::{ClientOptions, SecretsManager},
    storage::FileKeyValueStorage,
    custom_error::KSMRError,
    enums::StandardFieldTypeEnum
};

fn main()-> Result<(), KSMRError>{
    // setup secrets manager
    let token = "your_token_goes_here".to_string();
    let config = FileKeyValueStorage::new_config_storage("test.json".to_string())?;
    let client_options = ClientOptions::new_client_options_with_token(token, config);
    let mut secrets_manager = SecretsManager::new(client_options)?;

    // get a specific secret by record UID
    let secrets = secrets_manager.get_secrets(vec!["record_uid".to_string()])?;
    let secret = match secrets.len(){
        0 => return Err(KSMRError::CustomError("no secret with given uid is found".to_string())),
        _ => &secrets[0],
    };
    // use StandardFieldTypeEnum for getting accurate type for standard field without any typographic errors
    let login_field = StandardFieldTypeEnum::LOGIN.get_type();
    // get login field from the secret
    let my_secret_login = secret.get_standard_field_value(login_field, true)?;
    Ok(())
}

Parameter

Type

Required

Default

Description

field_type

&str

Yes

None

Field type to get

single

bool

Optional

false

Return only the first value

Returns

Type: Result<Value, KSMRError>

The field value as a JSON value. When single = true, returns the first value; otherwise returns an array.

Field types are based on the Keeper Record Type. For a detailed list of available fields based on the Keeper Record Type, see the record-type-info command in Keeper Commander.

Retrieve Custom Fields

secret.get_custom_field_value(“FIELD_TYPE”, true);

use keeper_secrets_manager_core::{
    core::{ClientOptions, SecretsManager},
    storage::InMemoryKeyValueStorage,
    custom_error::KSMRError
};
fn main()-> Result<(), KSMRError>{
    // setup secrets manager
    let config_string = "your_base64_goes_here".to_string();
    let config = InMemoryKeyValueStorage::new_config_storage(Some(config_string))?;
    let client_options = ClientOptions::new_client_options(config);
    let mut secrets_manager = SecretsManager::new(client_options)?;

    // get a specific secret by record UID
    let secrets = secrets_manager.get_secrets(vec!["record_uid".to_string()])?;
    let secret = match secrets.len(){
        0 => return Err(KSMRError::CustomError("no secret with given uid is found".to_string())),
        _ => &secrets[0],
    };
    // Get a custom field, e.g. API Key
    let api_key = secret.get_custom_field_value("API Key", true)?;
    Ok(())
}

Parameter

Type

Required

Default

Description

field_type

&str

Yes

Field type to get

single

bool

Optional

false

Return only the first value

Custom fields are any field that is not part of the record type definition but can be added by users.

Returns

Type: Result<Value, KSMRError>

The field value as a JSON value. When single = true, returns the first value; otherwise returns an array

Search Secrets by Title

Search for secrets using their title instead of UID. The SDK provides two methods:

get_secrets_by_title() - Returns all secrets matching the exact title
get_secret_by_title() - Returns the first secret matching the exact title

secrets_manager.get_secrets_by_title(record_title)

use keeper_secrets_manager_core::{
    core::{ClientOptions, SecretsManager},
    storage::InMemoryKeyValueStorage,
    custom_error::KSMRError
};
fn main()-> Result<(), KSMRError>{
    // setup secrets manager
    let config_string = "your_base64_goes_here".to_string();
    let config = InMemoryKeyValueStorage::new_config_storage(Some(config_string))?;
    let client_options = ClientOptions::new_client_options(config);
    let mut secrets_manager = SecretsManager::new(client_options)?;

    // get all secrets matching the record title
    let matching_secrets = secrets_manager.get_secrets_by_title("My Credentials")?;
    println!("Found {} matching secrets", matching_secrets.len());

    Ok(())
}

use keeper_secrets_manager_core::{
    core::{ClientOptions, SecretsManager},
    storage::InMemoryKeyValueStorage,
    custom_error::KSMRError
};
fn main()-> Result<(), KSMRError>{
    // setup secrets manager
    let config_string = "your_base64_goes_here".to_string();
    let config = InMemoryKeyValueStorage::new_config_storage(Some(config_string))?;
    let client_options = ClientOptions::new_client_options(config);
    let mut secrets_manager = SecretsManager::new(client_options)?;

    // get first secret matching the record title
    if let Some(secret) = secrets_manager.get_secret_by_title("My Credentials")? {
        println!("Found secret: {}", secret.uid);
    } else {
        println!("No secret found with that title");
    }

    Ok(())
}

Response

Method

Return Type

Description

get_secrets_by_title()

Result<Vec<Record>, KSMRError>

All secrets matching the exact title

get_secret_by_title()

Result<Option<Record>, KSMRError>

First secret matching title, or None

Parameter

Type

Required

Description

record_title

&str

Yes

Exact title of the record to find

Title matching is case-sensitive and requires an exact match. For partial or case-insensitive searching, retrieve all secrets and filter client-side.

Retrieve Values using Keeper Notation

secrets_manager.get_notation(query)

use keeper_secrets_manager_core::{
    core::{ClientOptions, SecretsManager},
    storage::InMemoryKeyValueStorage,
    custom_error::KSMRError
};
fn main()-> Result<(), KSMRError>{
    // setup secrets manager
    let config_string = "your_base64_goes_here".to_string();
    let config = InMemoryKeyValueStorage::new_config_storage(Some(config_string))?;
    let client_options = ClientOptions::new_client_options(config);
    let mut secrets_manager = SecretsManager::new(client_options)?;

    // get all secrets matching the notation
    let notation = "HDQTnxkTcPSOsHNAlbI4aQ/field/login".to_string();
    let result = secrets_manager.get_notation(notation)?;
    Ok(())
}

See Keeper Notation documentation to learn about Keeper Notation format and capabilities

Parameter

Type

Required

Default

Description

query

String

Yes

Keeper Notation query for getting a value from a specified field

Returns

Type: Result<serde_json::Value, KSMRError>

The value of the queried field as a JSON value. When the field contains a single value it resolves to a JSON string; multi-value fields resolve to a JSON array.

Retrieve a TOTP Code

get_totp_code(&url)

use keeper_secrets_manager_core::{
    core::{ClientOptions, SecretsManager},
    storage::InMemoryKeyValueStorage,
    custom_error::KSMRError,
    enums::StandardFieldTypeEnum,
    utils
};
fn main()-> Result<(), KSMRError>{
    // setup secrets manager
    let config_string = "your_base64_goes_here".to_string();
    let config = InMemoryKeyValueStorage::new_config_storage(Some(config_string))?;
    let client_options = ClientOptions::new_client_options(config);
    let mut secrets_manager = SecretsManager::new(client_options)?;

    // get a specific secret by UID
    let secrets = secrets_manager.get_secrets(vec!["<RECORD UID>".to_string()])?;
    let record = &secrets[0];

    // get TOTP url value from a record
    let value = record.get_standard_field_value(StandardFieldTypeEnum::ONETIMECODE.get_type(), false)?;
    let url: String = utils::get_otp_url_from_value_obj(value)?;

    // get code from TOTP url
    let totp = utils::get_totp_code(&url)?;
    println!("{}", totp.get_code());
    Ok(())
}

Returns

Type: Result<TotpCode,KSMRError>

Parameter

Type

Required

Description

url

&str

Yes

TOTP Url

Update a Secret

Record update commands don't update local record data on success (esp. updated record revision) so any consecutive updates to an already updated record will fail due to revision mismatch. Make sure to reload all updated records after each update batch.

Update Secret

The update_secret() method is the standard way to update records.

secrets_manager.update_secret(record)

use keeper_secrets_manager_core::{
    core::{ClientOptions, SecretsManager},
    storage::InMemoryKeyValueStorage,
    custom_error::KSMRError,
    enums::StandardFieldTypeEnum
};
fn main()-> Result<(), KSMRError>{
    // setup secrets manager
    let config_string = "your_base64_goes_here".to_string();
    let config = InMemoryKeyValueStorage::new_config_storage(Some(config_string))?;
    let client_options = ClientOptions::new_client_options(config);
    let mut secrets_manager = SecretsManager::new(client_options)?;

    // get a specific secret by UID
    let mut secrets = secrets_manager.get_secrets(vec!["<RECORD UID>".to_string()])?;
    let mut secret_to_update = secrets.into_iter().next()
        .ok_or_else(|| KSMRError::CustomError("no secret found with given UID".to_string()))?;

    // update a field value
    let field_type = StandardFieldTypeEnum::LOGIN.get_type();
    secret_to_update.set_standard_field_value_mut(field_type, "[email protected]".into())?;

    // save the changes
    secrets_manager.update_secret(secret_to_update)?;
    Ok(())
}

Parameter

Type

Required

Default

Description

record

Record

Yes

Record with updated field values

Response

Returns Result<(), KSMRError> - success or error

Password Rotation with Transactions

The update_secret_with_transaction() method enables password rotation workflows where you can test the new password before committing the change.

The rollback parameter follows its name: pass true to roll back the rotation, false to commit it. Pass false to finalize the new password.

secrets_manager.update_secret_with_transaction(record, UpdateTransactionType::Rotation)?;
// Test the new password...
secrets_manager.complete_transaction(record_uid, false)?; // false = commit, true = rollback

use keeper_secrets_manager_core::{
    core::{ClientOptions, SecretsManager},
    storage::InMemoryKeyValueStorage,
    custom_error::KSMRError,
    enums::StandardFieldTypeEnum,
    dto::payload::UpdateTransactionType
};
fn main()-> Result<(), KSMRError>{
    // setup secrets manager
    let config_string = "your_base64_goes_here".to_string();
    let config = InMemoryKeyValueStorage::new_config_storage(Some(config_string))?;
    let client_options = ClientOptions::new_client_options(config);
    let mut secrets_manager = SecretsManager::new(client_options)?;

    // get a specific secret by UID
    let mut secrets = secrets_manager.get_secrets(vec!["<RECORD UID>".to_string()])?;
    let mut secret_to_update = secrets.into_iter().next()
        .ok_or_else(|| KSMRError::CustomError("no secret found with given UID".to_string()))?;
    let record_uid = secret_to_update.uid.clone();

    // update password field
    let field_type = StandardFieldTypeEnum::PASSWORD.get_type();
    secret_to_update.set_standard_field_value_mut(field_type, "NewRotatedPassword123!".into())?;

    // start rotation transaction
    secrets_manager.update_secret_with_transaction(secret_to_update, UpdateTransactionType::Rotation)?;

    // Test the new password in your application...
    // If successful:
    secrets_manager.complete_transaction(record_uid, false)?; // commit

    // If testing failed:
    // secrets_manager.complete_transaction(record_uid, true)?; // rollback

    Ok(())
}

Parameter

Type

Required

Description

record

Record

Yes

Record with updated field values

transaction_type

UpdateTransactionType

Yes

General or Rotation

record_uid

String

Yes

UID of the record to finalize transaction for

rollback

bool

Yes

false to commit, true to rollback

Remove File Links

The update_secret_with_options() method provides fine-grained control over updates, including the ability to remove file links.

let update_options = UpdateOptions::new(
    UpdateTransactionType::General,
    vec!["file-uid-to-remove".to_string()]
);
secrets_manager.update_secret_with_options(record, update_options)?;

use keeper_secrets_manager_core::{
    core::{ClientOptions, SecretsManager},
    storage::InMemoryKeyValueStorage,
    custom_error::KSMRError,
    dto::payload::{UpdateOptions, UpdateTransactionType}
};
fn main()-> Result<(), KSMRError>{
    // setup secrets manager
    let config_string = "your_base64_goes_here".to_string();
    let config = InMemoryKeyValueStorage::new_config_storage(Some(config_string))?;
    let client_options = ClientOptions::new_client_options(config);
    let mut secrets_manager = SecretsManager::new(client_options)?;

    // get a specific secret by UID
    let secrets = secrets_manager.get_secrets(vec!["<RECORD UID>".to_string()])?;
    let secret_to_update = secrets.into_iter().next()
        .ok_or_else(|| KSMRError::CustomError("no secret found with given UID".to_string()))?;

    // Modify fields as needed...

    // Create update options to remove file links
    let update_options = UpdateOptions::new(
        UpdateTransactionType::General,
        vec!["file-uid-to-remove-1".to_string(), "file-uid-to-remove-2".to_string()]
    );

    // Update the record and remove specified file links
    secrets_manager.update_secret_with_options(secret_to_update, update_options)?;

    Ok(())
}

Parameter

Type

Required

Default

Description

record

Record

Yes

Record with updated field values

update_options

UpdateOptions

Yes

Configuration for advanced update behavior

UpdateOptions Fields:

Field

Type

Description

transaction_type

UpdateTransactionType

General or Rotation

links_to_remove

Vec<String>

UIDs of file attachments to remove

Set field values using the set_standard_field_value_mut or the set_custom_field_value_mut method.

Fields are found by type.

For a list of field types, see the Record Types documentation. Some fields have multiple values in these cases, the value can be set to a list.

Generate a Random Password

generate_password_with_options(password_options);

use keeper_secrets_manager_core::{
    core::{ClientOptions, SecretsManager},
    storage::InMemoryKeyValueStorage,
    custom_error::KSMRError,
    enums::StandardFieldTypeEnum,
    utils::{generate_password_with_options, PasswordOptions}
};
fn main()-> Result<(), KSMRError>{
    // setup secrets manager
    let config_string = "your_base64_goes_here".to_string();
    let config = InMemoryKeyValueStorage::new_config_storage(Some(config_string))?;
    let client_options = ClientOptions::new_client_options(config);
    let mut secrets_manager = SecretsManager::new(client_options)?;

    // get a specific secret by UID
    let secrets = secrets_manager.get_secrets(vec!["<RECORD UID>".to_string()])?;
    let mut secret = secrets.into_iter().next()
        .ok_or_else(|| KSMRError::CustomError("no secret found with given UID".to_string()))?;

    // generate a random password
    let charset: String = "$_!?#".to_string();
    let length = 32;
    let digits = 2;
    let lowercase = 2;
    let uppercase = 2;
    let special_characters = 2;
    let password_options = PasswordOptions::new()
        .length(length)
        .digits(digits)
        .lowercase(lowercase)
        .uppercase(uppercase)
        .special_characters(special_characters)
        .special_characterset(charset);
    let password = generate_password_with_options(password_options)?;

    // update record with new password
    let field_type = StandardFieldTypeEnum::PASSWORD.get_type();
    secret.set_standard_field_value_mut(field_type, password.into())?;

    // Save changes to the secret
    secrets_manager.update_secret(secret)?;
    Ok(())
}

Parameter

Type

Required

Default

Description

password_options

PasswordOptions

Yes

Configuration for the password

special_characterset

String

Optional

"""!@#$%()+;<>=?[]{}^.,"""

Set of special characters to be included in the password

length

usize

Optional

Length of password

lowercase

i32

Optional

None

Count of lowercase characters in the password

uppercase

i32

Optional

None

Count of uppercase characters in the password

digits

i32

Optional

None

Count of digits in the password

special_characters

i32

Optional

None

Count of special characters in the password

By default, each count parameter specifies the minimum number of that character type. Pass a negative value to specify an exact count instead — for example, .lowercase(-8) produces exactly 8 lowercase characters. When all count parameters are negative or zero (exact mode), the length parameter is ignored and the total password length is derived from the sum of the absolute values.

Download a File

secret.download_file(file_name, path);

use keeper_secrets_manager_core::{
    core::{ClientOptions, SecretsManager},
    storage::InMemoryKeyValueStorage,
    custom_error::KSMRError
};
fn main()-> Result<(), KSMRError>{
    // setup secrets manager
    let config_string = "your_base64_goes_here".to_string();
    let config = InMemoryKeyValueStorage::new_config_storage(Some(config_string))?;
    let client_options = ClientOptions::new_client_options(config);
    let mut secrets_manager = SecretsManager::new(client_options)?;

    // get a specific secret by UID
    let secrets = secrets_manager.get_secrets(vec!["<RECORD UID>".to_string()])?;
    let secret = &secrets[0];

    // Download file to a specific path
    let path = format!("./temp/demo_{}.txt", secret.title);
    secret.download_file("uploaded_file.txt", &path)?;
    Ok(())
}

Parameter

Type

Required

Description

file_name

&str

Yes

Name, title, or UID of the file to download

path

&str

Yes

Path to download file

Returns

Type: Result<bool, KSMRError>

true if the file was found and saved to path; false if no file with that name, title, or UID exists on the record.

Download File by Title

Downloads a file attachment by record title and filename. The SDK searches all accessible records for one matching record_title, then retrieves the file named file_name from that record.

secrets_manager.download_file_by_title(record_title, file_name)

use keeper_secrets_manager_core::{
    core::{ClientOptions, SecretsManager},
    storage::InMemoryKeyValueStorage,
    custom_error::KSMRError
};
fn main() -> Result<(), KSMRError> {
    let config_string = "your_base64_goes_here".to_string();
    let config = InMemoryKeyValueStorage::new_config_storage(Some(config_string))?;
    let client_options = ClientOptions::new_client_options(config);
    let mut secrets_manager = SecretsManager::new(client_options)?;

    // Download a file by record title and file name
    if let Some(file_data) = secrets_manager.download_file_by_title("My Record Title", "report.pdf")? {
        std::fs::write("./report.pdf", &file_data)
            .map_err(|e| KSMRError::CustomError(e.to_string()))?;
        println!("File downloaded successfully");
    } else {
        println!("Record or file not found");
    }
    Ok(())
}

Parameter

Type

Required

Description

record_title

&str

Yes

Title of the record containing the file

file_name

&str

Yes

Name of the file attachment to download

Returns

Type: Result<Option<Vec<u8>>, KSMRError>

Ok(Some(bytes)) — decrypted file data as raw bytes
Ok(None) — no record with that title, or no file with that name was found
Err(...) — error during download or decryption

Download File Thumbnail

Some file attachments (especially images) have thumbnail previews. You can download these thumbnails separately from the full file.

file.get_thumbnail_data()

use keeper_secrets_manager_core::{
    core::{ClientOptions, SecretsManager},
    storage::InMemoryKeyValueStorage,
    custom_error::KSMRError
};
fn main()-> Result<(), KSMRError>{
    // setup secrets manager
    let config_string = "your_base64_goes_here".to_string();
    let config = InMemoryKeyValueStorage::new_config_storage(Some(config_string))?;
    let client_options = ClientOptions::new_client_options(config);
    let mut secrets_manager = SecretsManager::new(client_options)?;

    // get a specific secret by UID
    let secrets = secrets_manager.get_secrets(vec!["<RECORD UID>".to_string()])?;
    let secret = &secrets[0];

    // Download thumbnails for all files
    for mut file in secret.files.clone() {
        if let Some(thumbnail_data) = file.get_thumbnail_data()? {
            let thumbnail_path = format!("./temp/{}_thumb.jpg", file.name);
            std::fs::write(&thumbnail_path, &thumbnail_data)
                .map_err(|e| KSMRError::FileWriteError(thumbnail_path.clone(), e))?;
            println!("Downloaded thumbnail: {}", thumbnail_path);
        } else {
            println!("No thumbnail available for {}", file.name);
        }
    }

    Ok(())
}

Returns

Type: Result<Option<Vec<u8>>, KSMRError>

Ok(Some(bytes)) - Thumbnail data (typically JPEG)
Ok(None) - No thumbnail available for this file
Err(...) - Error downloading or decrypting thumbnail

Thumbnails are typically available for image files (PNG, JPEG, etc.). Document files and other non-image types usually do not have thumbnails.

Upload File

upload_file(owner_record, keeper_file);

use keeper_secrets_manager_core::{
    core::{ClientOptions, SecretsManager},
    storage::InMemoryKeyValueStorage,
    custom_error::KSMRError,
    dto::file::KeeperFileUpload
};
fn main()-> Result<(), KSMRError>{
    // setup secrets manager
    let config_string = "your_base64_goes_here".to_string();
    let config = InMemoryKeyValueStorage::new_config_storage(Some(config_string))?;
    let client_options = ClientOptions::new_client_options(config);
    let mut secrets_manager = SecretsManager::new(client_options)?;

    // get a specific secret by UID
    let secrets = secrets_manager.get_secrets(vec!["<RECORD UID>".to_string()])?;
    let owner_record = &secrets[0];

    // Prepare file data for upload
    let file_path = "./local_file.txt";
    let file_name = Some("uploaded_file.txt");
    let file_title = Some("My File");
    let mime_type = Some("text/plain");
    let keeper_file = KeeperFileUpload::get_file_for_upload(
        file_path,
        file_name,
        file_title,
        mime_type
    )?;

    // Upload file attached to the owner record and get the file UID
    let file_uid = secrets_manager.upload_file(owner_record, keeper_file)?;
    println!("Uploaded file UID: {}", file_uid);
    Ok(())
}

Upload File Parameters

Parameter

Type

Required

Default

Description

owner_record

Record

Yes

None

The record in which the file has to be uploaded

keeper_file

KeeperFileUpload

Yes

The file to be uploaded

File Parameters

Parameter

Type

Required

Default

Description

file_path

&str

Yes

Path to upload file

file_name

Option<&str>

Yes

Name of the file to be uploaded

file_title

Option<&str>

Yes

Title of the file to be uploaded

mime_type

Option<&str>

Yes

None

The type of data in the file. If none is provided, 'application/octet-stream' will be used

Returns

Type: Result<String, KSMRError>

The file UID of the attached file

Create a Secret

Prerequisites:

Shared folder UID
- The shared folder must be accessible by the Secrets Manager Application
- You and the Secrets Manager application must have edit permission
- There must be at least one record in the shared folder
Created records and record fields must be formatted correctly
- See the documentation for expected field formats for each record type
TOTP fields accept only URL generated outside of the KSM SDK
After record creation, you can upload file attachments using upload_file

Multi-value fields: To assign multiple values to a single field (e.g. two phone numbers, two security questions), pass a JSON array directly to RecordField::new_record_field. Single objects are still wrapped automatically; only pass an array when you have more than one entry.

secrets_manager.create_secret(folder_uid, record);

use keeper_secrets_manager_core::{
    core::{ClientOptions, SecretsManager},
    storage::InMemoryKeyValueStorage,
    custom_error::KSMRError,
    dto::{dtos::RecordCreate, field_structs::RecordField},
    utils
};
use serde_json::{self, json, Number, Value};

fn main()-> Result<(), KSMRError>{
    // setup secrets manager
    let config_string = "your_base64_goes_here".to_string();
    let config = InMemoryKeyValueStorage::new_config_storage(Some(config_string))?;
    let client_options = ClientOptions::new_client_options(config);
    let mut secrets_manager = SecretsManager::new(client_options)?;

    // This is how we create a Record
    let mut created_record =  RecordCreate::new("login".to_string(), "Login Record RUST_LOG_TEST".to_string(), Some("Dummy Notes".to_string()));
    
    // This is how we create a single field 
    let password_field = RecordField::new_record_field_with_options("password", Value::String(utils::generate_password()?), Some("Random password label".to_string()), false, true);

    //This is one way to create all fields directly in a vector
    let fields = vec![
        RecordField::new_record_field("login", Value::String("[email protected]".to_string()), Some("My Custom Login lbl".to_string())),

        password_field,
     ];

    created_record.fields = Some(fields);
  
    // Make the API call
    let _ = secrets_manager.create_secret("Shared_folder_uid".to_string(), created_record)?;
    Ok(())
}

use keeper_secrets_manager_core::{
    core::{ClientOptions, SecretsManager},
    storage::InMemoryKeyValueStorage,
    custom_error::KSMRError,
    dto::{dtos::RecordCreate, field_structs::RecordField},
    utils
};
use serde_json::{self, json, Number, Value};

fn main()-> Result<(), KSMRError>{
    // setup secrets manager
    let config_string = "your_base64_goes_here".to_string();
    let config = InMemoryKeyValueStorage::new_config_storage(Some(config_string))?;
    let client_options = ClientOptions::new_client_options(config);
    let mut secrets_manager = SecretsManager::new(client_options)?;

    // This is how we create a Record
    let mut created_record = RecordCreate::new("login".to_string(), "Login Record RUST_LOG_TEST".to_string(), Some("Dummy Notes".to_string()));

    // This is how we create a single field
    let password_field = RecordField::new_record_field_with_options("password", Value::String(utils::generate_password()?), Some("Random password label".to_string()), false, true);

    // This is one way to create all fields directly in a vector
    let fields = vec![
        RecordField::new_record_field("login", Value::String("[email protected]".to_string()), Some("My Custom Login lbl".to_string())),

        RecordField::new_record_field("login", Value::String("[email protected]".to_string()), Some("My Label".to_string())),

        password_field,

        // Single security question (pass an object for one entry)
        RecordField::new_record_field("securityQuestion", json!({"question": "What is the question?", "answer": "This is the answer!"}), Some("My Security Question".to_string())),

        // Multiple security questions (pass an array for more than one entry)
        RecordField::new_record_field("securityQuestion", json!([
            {"question": "Childhood pet?", "answer": "Fluffy"},
            {"question": "City of birth?", "answer": "Chicago"},
        ]), Some("My Security Questions".to_string())),

        RecordField::new_record_field("multiline", Value::String("This\nIs a multiline\nnote".to_string()), Some("My Multiline lbl".to_string())),

        RecordField::new_record_field("secret", Value::String("SecretText".to_string()), Some("My Hidden Field lbl".to_string())),

        RecordField::new_record_field("pinCode", Value::String("1234567890".to_string()), Some("My Pin Code Field Lbl".to_string())),

        RecordField::new_record_field("addressRef", Value::String("some_UID".to_string()), Some("My Address Reference".to_string())),

        // Single phone number
        RecordField::new_record_field("phone", json!({"region": "US", "number": "510-444-3333"}), Some("My Phone Number".to_string())),

        // Multiple phone numbers (pass an array for more than one entry)
        RecordField::new_record_field("phone", json!([
            {"region": "US", "number": "510-444-3333", "type": "Mobile"},
            {"region": "US", "number": "510-555-6666", "type": "Work"},
        ]), Some("My Phone Numbers".to_string())),

        RecordField::new_record_field("date", Value::Number(Number::from(1641934793000i64)), Some("My date".to_string())),

        RecordField::new_record_field("name", json!({"first": "Lincoln", "last": "Adams"}), Some("His Name".to_string())),
    ];

    // Here we are adding fields object to standard fields
    created_record.fields = Some(fields);

    created_record.custom = Some(
        vec![
            RecordField::new_record_field("phone", json!({"region": "US", "number": "510-222-5555", "ext": "99887", "type": "Mobile"}), Some("My Custom Phone Lbl".to_string())),
        ]
    );

    // Make the API call
    let _ = secrets_manager.create_secret("Shared_folder_uid".to_string(), created_record)?;
    Ok(())
}

Parameter

Type

Required

Description

parent_folder_uid

String

Yes

UID of the shared folder to create the record in

record_create_object

RecordCreate

Yes

Record definition. Type, title, and fields

RecordCreate fields:

Field

Type

Required

Default

Description

record_type

String

Yes

Record type (e.g. "login")

title

String

Yes

Title of the record

notes

Option<String>

None

Optional note on the record

fields

Vec<RecordField>

None

Standard fields

custom

Vec<RecordField>

None

Custom fields

Returns

Type: Result<String, KSMRError>

The record UID of the new record

Delete A Secret

The Rust KSM SDK can delete records in the Keeper Vault.

secrets_manager.delete_secret(vec![record_uid]);

use keeper_secrets_manager_core::{
    core::{ClientOptions, SecretsManager},
    storage::InMemoryKeyValueStorage,
    custom_error::KSMRError
};
fn main()-> Result<(), KSMRError>{
    // setup secrets manager
    let config_string = "your_base64_goes_here".to_string();
    let config = InMemoryKeyValueStorage::new_config_storage(Some(config_string))?;
    let client_options = ClientOptions::new_client_options(config);
    let mut secrets_manager = SecretsManager::new(client_options)?;

    // delete a specific secret by UID
    let secret_to_delete = secrets_manager.delete_secret(vec!["<RECORD UID>".to_string()])?;
    Ok(())
}

Parameter

Type

Required

Default

Description

record_uid

Vec<String>

Yes

None

The uid of the record to be deleted

Returns

Type: Result<String, KSMRError>

The server response string on success.

Caching

To protect against losing access to your secrets when network access is lost, the Rust SDK allows caching of secrets to the local machine in an encrypted file.

Setup and Configure Cache

The Rust SDK provides caching::make_caching_post_function(client) for disaster recovery caching. It stores the last successful API response to a local encrypted file and falls back to that data automatically when the server is unreachable. Build the reqwest::blocking::Client once outside any async context (it is safe to use inside tokio::task::spawn_blocking), then pass it to the factory. As long as there is network connectivity, the SDK always prefers a live response over cached data.

use keeper_secrets_manager_core::caching;

// Build the client once outside any async context — safe under tokio::spawn_blocking
let http_client = reqwest::blocking::Client::builder().build()?;
let mut client_options = ClientOptions::new_client_options_with_token(token, config);
client_options.set_custom_post_function(caching::make_caching_post_function(http_client));
let mut secrets_manager = SecretsManager::new(client_options)?;

use keeper_secrets_manager_core::{
    core::{ClientOptions, SecretsManager},
    storage::FileKeyValueStorage,
    custom_error::KSMRError,
    caching
};
fn main()-> Result<(), KSMRError>{
    let token = "<Your One time token>".to_string();
    let file_name = FileKeyValueStorage::new_config_storage("test.json".to_string())?;

    let mut client_options = ClientOptions::new_client_options_with_token(token, file_name);

    // Build the client once outside any async context — safe under tokio::spawn_blocking
    let http_client = reqwest::blocking::Client::builder()
        .build()
        .map_err(|e| KSMRError::HTTPError(e.to_string()))?;
    client_options.set_custom_post_function(caching::make_caching_post_function(http_client));

    let mut secrets_manager = SecretsManager::new(client_options)?;

    // First successful call saves to cache (default: KSM_CACHE_DIR/ksm_cache.bin)
    let secrets = secrets_manager.get_secrets(Vec::new())?;

    // Subsequent calls automatically fall back to cache if network fails
    println!("Retrieved {} secrets (with automatic cache fallback)", secrets.len());

    Ok(())
}

Cache Location:

Default: $KSM_CACHE_DIR/ksm_cache.bin
If KSM_CACHE_DIR not set, uses system temp directory
Override with environment variable: export KSM_CACHE_DIR=/path/to/cache

The default caching function stores only the last successful request. For example, if the first request (R1) successfully retrieves UID1 and updates the cache, but a subsequent request (R2) for UID2 fails, the cache will not include UID2. As a result, any later operations involving UID2 will return an empty response if network is down, since it was never added to the cache.

Updating a record from cache (or creating new record) invalidates cached record data and consecutive updates of the same record will fail. Batch updates work as long as they modify different records. Always follow up cached record updates with a call to get_secrets() to refresh cache (and pull updated metadata from vault like the new record revision).

Custom Cache Implementations

For advanced use cases requiring custom cache management (e.g., preferring local cache over network, custom refresh intervals), you can implement your own caching logic using the KSMRCache as a starting point.

use keeper_secrets_manager_core::cache::KSMRCache;

let cache = KSMRCache::new_file_cache(Some("./cache.bin"))?;
let mut client_options = ClientOptions::new_client_options_with_token(token, config);
client_options.set_cache(cache.into());
let mut secrets_manager = SecretsManager::new(client_options)?;

use keeper_secrets_manager_core::{
    core::{ClientOptions, SecretsManager},
    custom_error::KSMRError,
    storage::FileKeyValueStorage,
    cache::KSMRCache
};
fn main()-> Result<(), KSMRError>{
    let cache = KSMRCache::new_file_cache(Some("./cache.bin"))?;
    let token = "<Token>".to_string();
    let file_name = FileKeyValueStorage::new_config_storage("test.json".to_string())?;

    let mut client_options = ClientOptions::new_client_options_with_token(token, file_name);
    client_options.set_cache(cache.into());

    let mut secrets_manager = SecretsManager::new(client_options)?;
    let secrets = secrets_manager.get_secrets(Vec::new())?;

    for secret in secrets {
        println!("Secret: {}", secret.title);
    }

    Ok(())
}

Folders

Folders have full CRUD support—create, read, update, and delete operations.

Read Folders

Downloads full folder hierarchy.

secrets_manager.get_folders()

use keeper_secrets_manager_core::{
    core::{ClientOptions, SecretsManager},
    storage::InMemoryKeyValueStorage,
    custom_error::KSMRError
};
fn main()-> Result<(), KSMRError>{
    // setup secrets manager
    let config_string = "your_base64_goes_here".to_string();
    let config = InMemoryKeyValueStorage::new_config_storage(Some(config_string))?;
    let client_options = ClientOptions::new_client_options(config);
    let mut secrets_manager = SecretsManager::new(client_options)?;
    
    // get all folder
    let folders = secrets_manager.get_folders()?;
    Ok(())
}

Returns

Type: Result<Vec<KeeperFolder>, KSMRError>

Create Folder

Requires CreateOptions and folder name to be provided. The folder UID parameter in CreateOptions is required—the UID of a shared folder, while sub-folder UID is optional, and if missing, a new regular folder is created directly under the parent (shared folder). There's no requirement for the sub-folder to be a direct descendant of the parent shared folder - it could be many levels deep.

secrets_manager.create_folder(create_options, folder_name, folders)

use keeper_secrets_manager_core::{
    core::{ClientOptions, SecretsManager},
    storage::InMemoryKeyValueStorage,
    custom_error::KSMRError,
    dto::payload::CreateOptions
};
fn main()-> Result<(), KSMRError>{
    // setup secrets manager
    let config_string = "your_base64_goes_here".to_string();
    let config = InMemoryKeyValueStorage::new_config_storage(Some(config_string))?;
    let client_options = ClientOptions::new_client_options(config);
    let mut secrets_manager = SecretsManager::new(client_options)?;

    // Create a folder directly under the shared folder
    let parent_folder_uid = "<PARENT_SHARED_FOLDER_UID>".to_string();
    let create_options = CreateOptions::new(parent_folder_uid, None);
    let new_folder_name = "My New Folder".to_string();

    let folder_uid = secrets_manager.create_folder(create_options, new_folder_name, Vec::new())?;
    println!("Created folder UID: {}", folder_uid);
    Ok(())
}

use keeper_secrets_manager_core::{
    core::{ClientOptions, SecretsManager},
    storage::InMemoryKeyValueStorage,
    custom_error::KSMRError,
    dto::payload::CreateOptions
};
fn main()-> Result<(), KSMRError>{
    // setup secrets manager
    let config_string = "your_base64_goes_here".to_string();
    let config = InMemoryKeyValueStorage::new_config_storage(Some(config_string))?;
    let client_options = ClientOptions::new_client_options(config);
    let mut secrets_manager = SecretsManager::new(client_options)?;

    // Create a subfolder within an existing folder
    let parent_folder_uid = "<PARENT_SHARED_FOLDER_UID>".to_string();
    let sub_folder_uid = Some("<EXISTING_FOLDER_UID>".to_string());
    let create_options = CreateOptions::new(parent_folder_uid, sub_folder_uid);
    let new_folder_name = "Nested Subfolder".to_string();

    let folder_uid = secrets_manager.create_folder(create_options, new_folder_name, Vec::new())?;
    println!("Created subfolder UID: {}", folder_uid);
    Ok(())
}

Parameter

Type

Required

Default

Description

create_options

CreateOptions

Yes

None

The parent and sub-folder UIDs

folder_name

String

Yes

The folder name

folders

Vec<KeeperFolder>

None

List of folders to use in the search for parent and sub-folder from CreateOptions

Returns

Type: Result<String, KSMRError>

The UID of the newly created folder.

Update Folder

Updates the folder metadata—currently folder name only.

secrets_manager.update_folder(folder_uid, folder_name, folders)

use keeper_secrets_manager_core::{
    core::{ClientOptions, SecretsManager},
    storage::InMemoryKeyValueStorage,
    custom_error::KSMRError
};
fn main()-> Result<(), KSMRError>{
    // setup secrets manager
    let config_string = "your_base64_goes_here".to_string();
    let config = InMemoryKeyValueStorage::new_config_storage(Some(config_string))?;
    let client_options = ClientOptions::new_client_options(config);
    let mut secrets_manager = SecretsManager::new(client_options)?;

    let update_folder = secrets_manager.update_folder("<folder_uid>".to_string(),"dummy_updated_API_RUST".to_string(),Vec::new())?;
    println!("{}",(serde_json::to_string_pretty(&update_folder)?));
    Ok(())
}

Parameter

Type

Required

Default

Description

folder_uid

String

Yes

The folder uid

folder_name

String

Yes

The new folder name

folders

Vec<KeeperFolder>

None

List of folders to use in the search for parent folder

Returns

Type: Result<String, KSMRError>

The server response string on success.

Delete Folders

Removes a list of folders. Use the force_delete flag to remove non-empty folders.

Any folders UIDs missing from the vault or not shared to the KSM Application will not result in error.

When using force_delete avoid sending parent with its children folder UIDs. Depending on the delete order you may get an error - ex. if parent force-deleted child first. There's no guarantee that list will always be processed in FIFO order.

secrets_manager.delete_folder(vec!["<FOLDER_UID>".to_string()], false)?

Parameter

Type

Required

Default

Description

folder_uids

Vec<String>

Yes

The folder UID list

force_delete

bool

false

Set to true to delete non-empty folders. Default false returns an error if the folder contains records.

Returns

Type: Result<Vec<HashMap<String, Value>>, KSMRError>

A list of response entries for each deleted folder. On success the list is typically empty.

PreviousRuby SDK NextPowerShell

Last updated 1 month ago