`
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
{% tabs %}
{% tab title="Get All Secrets by Title" %}
```rust
secrets_manager.get_secrets_by_title(record_title)
```
{% endtab %}
{% tab title="Get All Secrets by Title Example" %}
```rust
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(())
}
```
{% endtab %}
{% tab title="Get First Secret by Title" %}
```rust
secrets_manager.get_secret_by_title(record_title)
```
{% endtab %}
{% tab title="Get First Secret by Title Example" %}
```rust
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(())
}
```
{% endtab %}
{% endtabs %}
**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 |
{% hint style="info" %}
Title matching is **case-sensitive** and requires an **exact match**. For partial or case-insensitive searching, retrieve all secrets and filter client-side.
{% endhint %}
#### Retrieve Values using Keeper Notation
{% tabs %}
{% tab title="get Notation" %}
```rust
secrets_manager.get_notation(query)
```
{% endtab %}
{% tab title="Notation Example" %}
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(())
}
{% endtab %}
{% endtabs %}
See [Keeper Notation documentation](/en/keeperpam/secrets-manager/about/keeper-notation.md) 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`
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
{% tabs %}
{% tab title="Get TOTP Code" %}
```rust
get_totp_code(&url)
```
{% endtab %}
{% tab title="Example Usage" %}
```rust
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!["".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(())
}
```
{% endtab %}
{% endtabs %}
**Returns**
> Type: `Result`
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ----------- |
| `url` | `&str` | Yes | TOTP Url |
### Update a Secret
{% hint style="warning" %}
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.
{% endhint %}
#### **Update Secret**
The `update_secret()` method is the standard way to update records.
{% tabs %}
{% tab title="Update Secret" %}
```rust
secrets_manager.update_secret(record)
```
{% endtab %}
{% tab title="Update Secret Example" %}
```rust
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!["".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, "sample@ks.com".into())?;
// save the changes
secrets_manager.update_secret(secret_to_update)?;
Ok(())
}
```
{% endtab %}
{% endtabs %}
| 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.
{% hint style="info" %}
The `rollback` parameter follows its name: pass `true` to roll back the rotation, `false` to commit it. Pass `false` to finalize the new password.
{% endhint %}
{% tabs %}
{% tab title="Password Rotation" %}
```rust
secrets_manager.update_secret_with_transaction(record, UpdateTransactionType::Rotation)?;
// Test the new password...
secrets_manager.complete_transaction(record_uid, false)?; // false = commit, true = rollback
```
{% endtab %}
{% tab title="Password Rotation Example" %}
```rust
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!["".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(())
}
```
{% endtab %}
{% endtabs %}
| 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.
{% tabs %}
{% tab title="Update with Options" %}
```rust
let update_options = UpdateOptions::new(
UpdateTransactionType::General,
vec!["file-uid-to-remove".to_string()]
);
secrets_manager.update_secret_with_options(record, update_options)?;
```
{% endtab %}
{% tab title="Update with Options Example" %}
```rust
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!["".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(())
}
```
{% endtab %}
{% endtabs %}
| 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` | 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](/en/enterprise-guide/record-types.md) documentation. Some fields have multiple values in these cases, the value can be set to a list.
#### Generate a Random Password
{% tabs %}
{% tab title="Generate Password" %}
```rust
generate_password_with_options(password_options);
```
{% endtab %}
{% tab title="Generate Password Example" %}
```rust
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!["".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(())
}
```
{% endtab %}
{% endtabs %}
| 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 | 32 | 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
{% tabs %}
{% tab title="Download File" %}
```rust
secret.download_file(file_name, path);
```
{% endtab %}
{% tab title="Download File example" %}
```rust
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!["".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(())
}
```
{% endtab %}
{% endtabs %}
| 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`
`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.
{% tabs %}
{% tab title="Download File by Title" %}
```rust
secrets_manager.download_file_by_title(record_title, file_name)
```
{% endtab %}
{% tab title="Example" %}
```rust
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(())
}
```
{% endtab %}
{% endtabs %}
| 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>, 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.
{% tabs %}
{% tab title="Download Thumbnail" %}
```rust
file.get_thumbnail_data()
```
{% endtab %}
{% tab title="Download Thumbnail Example" %}
```rust
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!["".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(())
}
```
{% endtab %}
{% endtabs %}
**Returns**
> Type: `Result>, KSMRError>`
* `Ok(Some(bytes))` - Thumbnail data (typically JPEG)
* `Ok(None)` - No thumbnail available for this file
* `Err(...)` - Error downloading or decrypting thumbnail
{% hint style="info" %}
Thumbnails are typically available for image files (PNG, JPEG, etc.). Document files and other non-image types usually do not have thumbnails.
{% endhint %}
### Upload File
{% tabs %}
{% tab title="Upload File" %}
```rust
upload_file(owner_record, keeper_file);
```
{% endtab %}
{% tab title="Upload File Example" %}
```rust
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!["".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(())
}
```
{% endtab %}
{% endtabs %}
**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`
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](/en/keeperpam/commander-cli/command-reference/record-commands/creating-and-updating-records.md#record-types) 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](/en/keeperpam/secrets-manager/developer-sdk-library/python-sdk.md#upload-a-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.
{% tabs %}
{% tab title="Create Record" %}
```rust
secrets_manager.create_secret(folder_uid, record);
```
{% endtab %}
{% tab title="Login record Example" %}
```rust
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("login@email.com".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(())
}
```
{% endtab %}
{% tab title="Custom Type Example" %}
```rust
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("login@email.com".to_string()), Some("My Custom Login lbl".to_string())),
RecordField::new_record_field("login", Value::String("login@email.com".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(())
}
```
{% endtab %}
{% endtabs %}
| 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> | No | None | Optional note on the record |
fields | Vec<RecordField> | No | None | Standard fields |
custom | Vec<RecordField> | No | None | Custom fields |
**Returns**
> Type: `Result`
The record UID of the new record
### Delete A Secret
The Rust KSM SDK can delete records in the Keeper Vault.
{% tabs %}
{% tab title="Delete Secret" %}
```rust
secrets_manager.delete_secret(vec![record_uid]);
```
{% endtab %}
{% tab title="Delete Secret Example" %}
```rust
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!["".to_string()])?;
Ok(())
}
```
{% endtab %}
{% endtabs %}
| Parameter | Type | Required | Default | Description |
|---|
record_uid | Vec<String> | Yes | None | The uid of the record to be deleted |
**Returns**
> Type: `Result`
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.
{% tabs %}
{% tab title="Setup Caching" %}
```rust
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)?;
```
{% endtab %}
{% tab title="Caching Example" %}
```rust
use keeper_secrets_manager_core::{
core::{ClientOptions, SecretsManager},
storage::FileKeyValueStorage,
custom_error::KSMRError,
caching
};
fn main()-> Result<(), KSMRError>{
let 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(())
}
```
{% endtab %}
{% endtabs %}
**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`
{% hint style="danger" %}
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.
{% endhint %}
{% hint style="warning" %}
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).
{% endhint %}
#### 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.
{% tabs %}
{% tab title="Custom Cache Setup" %}
```rust
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)?;
```
{% endtab %}
{% tab title="Custom Cache Example" %}
```rust
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 = "".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(())
}
```
{% endtab %}
{% endtabs %}
### Folders
Folders have full CRUD support—create, read, update, and delete operations.
### Read Folders
Downloads full folder hierarchy.
{% tabs %}
{% tab title="Read Folders" %}
```rust
secrets_manager.get_folders()
```
{% endtab %}
{% tab title="Read Folders Example" %}
```rust
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(())
}
```
{% endtab %}
{% endtabs %}
**Returns**
> Type: `Result, 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.
{% tabs %}
{% tab title="Create Folder" %}
```rust
secrets_manager.create_folder(create_options, folder_name, folders)
```
{% endtab %}
{% tab title="Create Folder Under Shared Folder" %}
```rust
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 = "".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(())
}
```
{% endtab %}
{% tab title="Create Nested Subfolder" %}
```rust
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 = "".to_string();
let sub_folder_uid = Some("".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(())
}
```
{% endtab %}
{% endtabs %}
| 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> | No | None | List of folders to use in the search for parent and sub-folder from CreateOptions |
**Returns**
> Type: `Result`
The UID of the newly created folder.
### Update Folder
Updates the folder metadata—currently folder name only.
{% tabs %}
{% tab title="Update Folder" %}
```rust
secrets_manager.update_folder(folder_uid, folder_name, folders)
```
{% endtab %}
{% tab title="Update Folder Example" %}
```rust
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("".to_string(),"dummy_updated_API_RUST".to_string(),Vec::new())?;
println!("{}",(serde_json::to_string_pretty(&update_folder)?));
Ok(())
}
```
{% endtab %}
{% endtabs %}
| Parameter | Type | Required | Default | Description |
| ------------- | ------------------- | -------- | ------- | ------------------------------------------------------ |
| `folder_uid` | `String` | Yes | | The folder uid |
| `folder_name` | `String` | Yes | | The new folder name |
| `folders` | `Vec` | No | None | List of folders to use in the search for parent folder |
**Returns**
> Type: `Result`
The server response string on success.
### Delete Folders
Removes a list of folders. Use the `force_delete` flag to remove non-empty folders.
{% hint style="info" %}
Any folders UIDs missing from the vault or not shared to the KSM Application will not result in error.
{% endhint %}
{% hint style="info" %}
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.
{% endhint %}
{% tabs %}
{% tab title="Delete Folder" %}
```rust
secrets_manager.delete_folder(vec!["".to_string()], false)?
```
{% endtab %}
{% endtabs %}
| Parameter | Type | Required | Default | Description |
|---|
folder_uids | Vec<String> | Yes | | The folder UID list |
force_delete | bool | No | false | Set to true to delete non-empty folders. Default false returns an error if the folder contains records. |
**Returns**
> Type: `Result>, KSMRError>`
A list of response entries for each deleted folder. On success the list is typically empty.
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.keeper.io/en/keeperpam/secrets-manager/developer-sdk-library/rust-sdk.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
