Ruby SDK

Detailed Ruby SDK docs for Keeper Secrets Manager

Keeper Secrets Manager (KSM) is a zero-knowledge secrets management platform. The Ruby SDK provides programmatic access to your Keeper Vault from Ruby applications.

Requirements

Ruby 3.1 or higher.

Download and Installation

Installation

For more information, see the RubyGems package page

Install with gem

gem install keeper_secrets_manager -v 17.2.1

Or add to your Gemfile

gem 'keeper_secrets_manager', '~> 17.2'

Then run:

bundle install

Source Code

Find the Ruby source code in the GitHub repository

Using the SDK

Initialize Storage

The SDK requires a One-Time Access Token to initialize storage on a client device. After initialization, the SDK stores the configuration for future use.

KeeperSecretsManager.new(token: token, config: storage, hostname: hostname, verify_ssl_certs: verify_ssl_certs)

Parameter	Type	Required	Default	Description
token	String	Optional	nil	One-Time Access Token for initial binding
config	KeyValueStorage	Yes	-	Storage implementation for configuration persistence
hostname	String	Optional	'keepersecurity.com'	API hostname (e.g., 'keepersecurity.eu' for EU datacenter)
verify_ssl_certs	Boolean	Optional	true	Enable/disable SSL certificate verification

Using a One-Time Access Token requires at least one read operation to bind the token and fully populate the configuration.

Example Usage

Using a One-Time Access Token:

require 'keeper_secrets_manager'

token = "US:ONE_TIME_TOKEN"

# First time setup - bind the token
storage = KeeperSecretsManager::Storage::FileStorage.new('keeper_config.json')
secrets_manager = KeeperSecretsManager.new(token: token, config: storage)

# Complete the binding (requires at least one operation)
records = secrets_manager.get_secrets

# Verify config was saved
File.exist?('keeper_config.json')  # Should return true

Using File-Based Storage

For persistent configuration across application restarts:

require 'keeper_secrets_manager'

# After first time binding, load from file
secrets_manager = KeeperSecretsManager.from_file('keeper_config.json')

Alternatively connect with the base64 configuration file generated by your vault:

require 'keeper_secrets_manager'

base64_config = File.read('config.base64').strip
storage = KeeperSecretsManager::Storage::InMemoryStorage.new(base64_config)
secrets_manager = KeeperSecretsManager.new(config: storage)

Using a Base64 Config String

KeeperSecretsManager.from_config is a convenience initializer for base64-encoded configuration strings, which is the format produced by Commander's export command or stored in environment variables like KSM_CONFIG.

require 'keeper_secrets_manager'

# Initialize directly from a base64 config string
config_base64 = ENV['KSM_CONFIG']
secrets_manager = KeeperSecretsManager.from_config(config_base64)

records = secrets_manager.get_secrets

All keyword options accepted by KeeperSecretsManager.new (:hostname, :verify_ssl_certs, :proxy_url, etc.) are supported as a second argument hash.

Using Environment Variables

For read-only configuration from environment. EnvironmentStorage maps each config key to <prefix><KEY.upcase> with no separators inserted, so the variable names do not match the record's camelCase key names directly:

require 'keeper_secrets_manager'

# Set environment variables:
# export KSM_HOSTNAME=keepersecurity.com
# export KSM_CLIENTID=your-client-id
# export KSM_PRIVATEKEY=your-private-key
# export KSM_APPKEY=your-app-key
# export KSM_SERVERPUBLICKEYID=10
# export KSM_APPOWNERPUBLICKEY=your-app-owner-public-key

# Load from environment
config = KeeperSecretsManager::Storage::EnvironmentStorage.new('KSM_')
secrets_manager = KeeperSecretsManager.new(config: config)

KSM_APPOWNERPUBLICKEY is required by create_secret and upload_file. EnvironmentStorage is read-only, so this value must be set directly as an environment variable; it cannot be populated by binding a One-Time Access Token the way file- or memory-backed storage is.

Binding Lifecycle

The one-time token is redeemed on the first get_secrets() call, not at construction. If you persist config to an external store (AWS Secrets Manager, Azure Key Vault, etc.), read it back only after that call. For the full explanation, see Binding Lifecycle.

require 'keeper_secrets_manager'

# First run: provide a one-time token and a persistent storage path.
secrets_manager = KeeperSecretsManager.from_file(
  'keeper_config.json',
  token: 'US:ONE_TIME_TOKEN'
)
records = secrets_manager.get_secrets  # Token is redeemed here; keeper_config.json is updated.

# Subsequent runs: omit the token. Stored credentials are used directly.
secrets_manager = KeeperSecretsManager.from_file('keeper_config.json')
records = secrets_manager.get_secrets

Retrieve Secrets

Get Secrets

get_secrets(uids = nil, request_links: false)

Parameter	Type	Required	Default	Description
uids	Array<String>	Optional	nil	Record UIDs to retrieve. nil or empty retrieves all secrets.
request_links	Boolean	Optional	false	When true, each returned record's links array is populated with linked-credential entries accessible via record.get_links.

Response:

Type: Array<KeeperRecord>

Array containing all Keeper records, or records that match the given UID filter.

Example Usage

Retrieve All Secrets:

require 'keeper_secrets_manager'

secrets_manager = KeeperSecretsManager.from_file('keeper_config.json')

# Retrieve all secrets
records = secrets_manager.get_secrets

records.each do |record|
  puts "#{record.title} (#{record.type})"
end

Retrieve Secrets by UID:

# Get single secret by UID
records = secrets_manager.get_secrets(['RECORD_UID'])
record = records.first

# Get multiple secrets by UIDs
uids = ['UID1', 'UID2', 'UID3']
records = secrets_manager.get_secrets(uids)

Get Secrets by Title

# Get all secrets matching title
get_secrets_by_title(title)

# Get first secret matching title
get_secret_by_title(title)

Parameter	Type	Required	Default	Description
title	String	Yes	-	Record title to search for (exact match)

Response:

Type: Array<KeeperRecord> (for get_secrets_by_title) or KeeperRecord (for get_secret_by_title)

Returns all records matching the title, or the first matching record.

Example Usage

require 'keeper_secrets_manager'

secrets_manager = KeeperSecretsManager.from_file('keeper_config.json')

# Get secret by exact title match
record = secrets_manager.get_secret_by_title('My Database Credentials')

# Get multiple secrets with same title
records = secrets_manager.get_secrets_by_title('My Login')

# Access fields from the record
puts "Login: #{record.login}"
puts "Password: #{record.password}"

Linked Credentials

When a PAM record has linked credentials, pass request_links: true to get_secrets to include them. Call record.get_links to get a typed Array<KeeperRecordLink> view over the raw links array.

records = secrets_manager.get_secrets(['PAM_RECORD_UID'], request_links: true)
record = records.first

links = record.get_links
links.each do |link|
  puts "Linked UID: #{link.record_uid}"
  puts "Admin user: #{link.admin_user?}"
  puts "Allows rotation: #{link.allows_rotation?}"
end

KeeperRecordLink accessors — all non-raising (return false/nil on failure):

Accessor	Returns	Description
record_uid	String	UID of the linked record
path	String or nil	Discriminator: "meta", "ai_settings", "jit_settings", or nil for credential links
admin_user?	Boolean	Link grants admin privileges
launch_credential?	Boolean	Link is a launch credential
iam_user?	Boolean	Link is an IAM user credential
allows_rotation?	Boolean	Rotation allowed (reads allowedSettings)
allows_connections?	Boolean	Connections allowed
allows_session_recording?	Boolean	Session recording allowed
allows_port_forwards?	Boolean	Port forwarding allowed
get_link_data(record_key)	Hash or nil	Full parsed link data payload (plain or decrypted)
get_decrypted_data(record_key)	String or nil	AES-256-GCM decrypted data string (for encrypted paths)
get_meta_data	Hash or nil	PAM rotation/connection settings from a "meta" link
get_ai_settings_data(record_key)	Hash or nil	AI settings from an "ai_settings" link
get_jit_settings_data(record_key)	Hash or nil	JIT settings from a "jit_settings" link

record_key is record.record_key (the decrypted record key bytes) and is required only for encrypted link paths (ai_settings, jit_settings). Plain-JSON links parse without a key.

For the full cross-SDK reference, see Linked Credentials.

Retrieve Values From a Secret

Once a secret is retrieved, individual fields can be accessed using multiple approaches:

Using Dynamic Field Access

record = secrets_manager.get_secrets(['RECORD_UID']).first

# Access standard fields dynamically
login = record.login
password = record.password
url = record.url

# Access complex fields
host = record.host  # Returns hash with hostName and port

Using Explicit Field Methods

# Get single field value (returns first value)
login = record.get_field_value_single('login')

# Get all values for a field (returns array)
passwords = record.get_field_value('password')

# Access custom fields by label
api_key = record.get_field_value_single('API Key')
environment = record.get_field_value_single('Environment')

Using Keeper Notation

# Access fields using URI-style notation
password = secrets_manager.get_notation("keeper://#{record.uid}/field/password")

# Access by record title
url = secrets_manager.get_notation("keeper://My Login/field/url")

# Access complex field properties
hostname = secrets_manager.get_notation("keeper://#{record.uid}/field/host[hostName]")
port = secrets_manager.get_notation("keeper://#{record.uid}/field/host[port]")

# Access custom fields
env = secrets_manager.get_notation("keeper://#{record.uid}/custom_field/Environment")

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

Error-Safe Notation: try_get_notation

try_get_notation is a non-raising wrapper around get_notation. It returns an Array on success and an empty array [] on any error, so it is safe to use without a rescue block when a missing field should silently produce no value.

# Returns [] instead of raising on invalid notation or missing record
values = secrets_manager.try_get_notation("keeper://#{record.uid}/field/password")
password = values.first  # nil if not found, no exception

get_notation continues to raise NotationError on invalid input and is the correct choice when an error should halt execution.

Array Notation: get_notation_results and try_get_notation_results

get_notation_results resolves a notation URI and always returns an Array of matching values, preserving all elements for multi-value fields (e.g. multiple hosts in a host field). It raises NotationError on invalid input. Complex (non-string) field values are serialized to JSON strings, not returned as Ruby hashes.

try_get_notation_results is the non-raising variant: it logs errors and returns [] instead of raising.

# Returns all matching values as an Array; complex values come back as JSON strings
values = secrets_manager.get_notation_results("keeper://#{record.uid}/field/host")
# => ["{\"hostName\":\"db1.example.com\",\"port\":\"5432\"}", "{\"hostName\":\"db2.example.com\",\"port\":\"5432\"}"]

# Safe variant — never raises
values = secrets_manager.try_get_notation_results("keeper://#{record.uid}/field/host")
# => [] if the notation is invalid or the record does not exist

Contrast with get_notation, which returns a scalar (the first value for most selectors), and try_get_notation, which wraps get_notation in Array(). try_get_notation returns a single-element array even when only one value matches. Use get_notation_results when you need the full set of values for a multi-value field.

Inflating Reference Fields

Some PAM record fields store UIDs that reference other records rather than inline values. inflate_field_value resolves those UIDs by fetching the referenced records and returning their field values directly.

inflate_field_value(uids, replace_fields)

Parameter	Type	Required	Description
uids	Array<String>	Yes	UIDs of reference records to resolve
replace_fields	Array<String>	Yes	Field types to extract from the referenced records (e.g. ['address'])

Response:

Type: Array — one entry per resolved UID, with nil entries removed. Each entry is the resolved field value (a String, Hash, or nested Array depending on the field type).

To look up which field types a reference type resolves to, call get_inflate_ref_types:

get_inflate_ref_types(field_type)

Field type	Resolves to
addressRef	['address']
cardRef	['paymentCard', 'text', 'pinCode', 'addressRef']
other	[] (unknown ref types return an empty array)

Example Usage

require 'keeper_secrets_manager'

secrets_manager = KeeperSecretsManager.from_file('keeper_config.json')

record = secrets_manager.get_secrets(['PAM_RECORD_UID']).first

# Find a cardRef field
card_field = record.get_field('cardRef')
if card_field
  ref_uids   = card_field['value'] || []
  field_types = secrets_manager.get_inflate_ref_types('cardRef')
  inflated    = secrets_manager.inflate_field_value(ref_uids, field_types)
  inflated.each { |v| puts v.inspect }
end

Retrieve a TOTP Code

To generate a TOTP code, retrieve the TOTP URL from the record and use the KeeperSecretsManager::TOTP module. TOTP generation requires the base32 gem (gem install base32) to decode the secret.

# Get TOTP URL from record
totp_url = record.get_field_value_single('oneTimeCode')

# Parse and generate code
require 'keeper_secrets_manager/totp'
totp_params = KeeperSecretsManager::TOTP.parse_url(totp_url)
totp_code = KeeperSecretsManager::TOTP.generate_code(
  totp_params['secret'],
  algorithm: totp_params['algorithm'],
  digits: totp_params['digits'],
  period: totp_params['period']
)

Parameter	Type	Required	Default	Description
secret	String	Yes	-	Base32-encoded TOTP secret
algorithm	String	Optional	'SHA1'	Hash algorithm (SHA1, SHA256, SHA512)
digits	Integer	Optional	6	Number of digits in the code
period	Integer	Optional	30	Time period in seconds

Response:

Type: String

Returns the current Time-Based One-Time Password (TOTP) code for two-factor authentication.

Example Usage

require 'keeper_secrets_manager'

secrets_manager = KeeperSecretsManager.from_file('keeper_config.json')

# Get record with TOTP
record = secrets_manager.get_secrets(['RECORD_UID']).first

# Get TOTP URL from record
totp_url = record.get_field_value_single('oneTimeCode')

# Parse TOTP parameters
require 'keeper_secrets_manager/totp'
totp_params = KeeperSecretsManager::TOTP.parse_url(totp_url)

# Generate TOTP code
totp_code = KeeperSecretsManager::TOTP.generate_code(
  totp_params['secret'],
  algorithm: totp_params['algorithm'],
  digits: totp_params['digits'],
  period: totp_params['period']
)

puts "Current TOTP code: #{totp_code}"
puts "Expires in: #{30 - (Time.now.to_i % 30)} seconds"

Generate a Random Password

Generate cryptographically secure random passwords with customizable character requirements. This utility function is useful when creating or updating secrets programmatically.

KeeperSecretsManager::Utils.generate_password(
  length: 64,
  lowercase: 0,
  uppercase: 0,
  digits: 0,
  special_characters: 0
)

Parameter	Type	Required	Default	Description
length	Integer	Optional	64	Total password length
lowercase	Integer	Optional	0	Minimum number of lowercase letters (a-z)
uppercase	Integer	Optional	0	Minimum number of uppercase letters (A-Z)
digits	Integer	Optional	0	Minimum number of digit characters (0-9)
special_characters	Integer	Optional	0	Minimum number of special characters (!@#$%^&*()_+-=[]{}

Response:

Type: String

Returns a cryptographically secure random password meeting the specified requirements.

This function uses Ruby's SecureRandom for cryptographic-strength randomness and applies Fisher-Yates shuffle to ensure proper character distribution.

Example Usage

Generate a default 64-character password:

require 'keeper_secrets_manager'

# Generate with all defaults (64 random characters)
password = KeeperSecretsManager::Utils.generate_password
puts "Generated: #{password}"
# => "Xk9$mP2..."  (64 characters)

Generate password with specific requirements:

# Generate 32-character password with specific minimums
password = KeeperSecretsManager::Utils.generate_password(
  length: 32,
  lowercase: 2,
  uppercase: 2,
  digits: 2,
  special_characters: 2
)

puts "Generated: #{password}"
# => "aB12$xY34..."  (32 chars with at least 2 of each type)

# Generate strong password with mixed requirements
password = KeeperSecretsManager::Utils.generate_password(
  length: 20,
  lowercase: 3,
  uppercase: 3,
  digits: 3,
  special_characters: 3
)

Use when creating a new secret:

require 'keeper_secrets_manager'

secrets_manager = KeeperSecretsManager.from_file('keeper_config.json')

# Create a new login record with generated password
record_data = {
  type: 'login',
  title: 'Production Database',
  fields: [
    { type: 'login', value: ['db_admin'] },
    {
      type: 'password',
      value: [KeeperSecretsManager::Utils.generate_password(
        length: 32,
        lowercase: 4,
        uppercase: 4,
        digits: 4,
        special_characters: 4
      )]
    },
    { type: 'url', value: ['https://db.example.com'] }
  ],
  notes: 'Auto-generated secure password'
}

# Create options with required folder_uid
options = KeeperSecretsManager::Dto::CreateOptions.new(folder_uid: 'FOLDER_UID')
record_uid = secrets_manager.create_secret(record_data, options)

puts "Created record with secure password: #{record_uid}"

Use when updating an existing secret:

require 'keeper_secrets_manager'

secrets_manager = KeeperSecretsManager.from_file('keeper_config.json')

# Get existing record
record = secrets_manager.get_secrets(['RECORD_UID']).first

# Generate and set new password
new_password = KeeperSecretsManager::Utils.generate_password(
  length: 40,
  lowercase: 5,
  uppercase: 5,
  digits: 5,
  special_characters: 5
)

record.password = new_password

# Save changes
secrets_manager.update_secret(record)

puts "Password updated with new secure value"

Password rotation script:

require 'keeper_secrets_manager'

secrets_manager = KeeperSecretsManager.from_file('keeper_config.json')

# Rotate passwords for multiple records
record_uids = ['UID1', 'UID2', 'UID3']

record_uids.each do |uid|
  record = secrets_manager.get_secrets([uid]).first

  # Generate new password
  new_password = KeeperSecretsManager::Utils.generate_password(
    length: 32,
    lowercase: 3,
    uppercase: 3,
    digits: 3,
    special_characters: 3
  )

  # Update record
  record.password = new_password
  record.notes = "Password rotated on #{Time.now}"

  secrets_manager.update_secret(record)

  puts "✓ Rotated password for: #{record.title}"
end

PAM Record Types

Use record.type to identify PAM records.

records.each do |record|
  case record.type
  when 'pamMachine'
    # host field available
  when 'pamUser'
    # login field available
  when 'pamDatabase'
    # databaseType field available
  end
end

For field schemas of all 11 PAM record types, see PAM Record Types.

PAM Rotation Transactions

complete_transaction finalizes or rolls back a staged PAM rotation update. It is called after update_secret during a rotation workflow to commit the change to the server.

complete_transaction(record_uid, rollback: false)

Parameter	Type	Required	Default	Description
record_uid	String	Yes	-	UID of the record whose staged transaction should be finalized
rollback	Boolean	Optional	false	When true, rolls back the staged update instead of committing it

Response:

Type: Boolean, returns true on success.

Example Usage

require 'keeper_secrets_manager'

secrets_manager = KeeperSecretsManager.from_file('keeper_config.json')

record = secrets_manager.get_secrets(['PAM_RECORD_UID']).first
record.password = 'NewRotatedPassword!'
secrets_manager.update_secret(record)

# Commit the staged rotation
secrets_manager.complete_transaction(record.uid)

# Or roll back if rotation validation failed
# secrets_manager.complete_transaction(record.uid, rollback: true)

update_secret stages the change; complete_transaction is what actually commits or discards it. Omitting complete_transaction leaves the change staged indefinitely.

Update a Secret

update_secret(record)

Parameter	Type	Required	Default	Description
record	KeeperRecord	Yes	-	The modified record to update in the vault

Response:

Type: void

Updates the secret in the vault with the modified values.

Example Usage

require 'keeper_secrets_manager'

secrets_manager = KeeperSecretsManager.from_file('keeper_config.json')

# Get existing record
record = secrets_manager.get_secrets(['RECORD_UID']).first

# Update fields using dynamic access
record.password = 'NewSecurePassword123!'

# Update fields using explicit method
record.set_field('login', '[e-mail]')

# Update notes
record.notes = "Updated on #{Time.now}"

# Save changes
secrets_manager.update_secret(record)

puts "Secret updated successfully"

Non-Finalizing Save: save and save_with_options

save posts the record update to the server without calling complete_transaction. Use it in PAM rotation workflows where you need to stage a change and then separately commit or roll back, or when you want to update a record without triggering a finalization round-trip.

save(record, transaction_type: nil, links_to_remove: nil)

Parameter	Type	Required	Default	Description
record	Dto::KeeperRecord, Hash	Yes	-	Record to update (must have been retrieved via get_secrets)
transaction_type	String or nil	Optional	nil	PAM transaction type ('rotation', 'general', or nil)
links_to_remove	Array<String>	Optional	nil	UIDs of linked records to remove from this record

Response:

Type: Boolean — returns true on success.

For full control over UpdateOptions, call save_with_options directly:

save_with_options(record, update_options = nil)

update_options is a Dto::UpdateOptions object with transaction_type: and links_to_remove: attributes.

Comparison with update_secret

	update_secret	save / save_with_options
Calls complete_transaction	Yes (always)	No
Refreshes record.revision after update	Yes	No
Extra get_secrets round-trip for key	Yes	No (uses existing key)
Use when	Standard CRUD updates	PAM staging, batch updates, manual commit control

Example Usage

require 'keeper_secrets_manager'

secrets_manager = KeeperSecretsManager.from_file('keeper_config.json')

record = secrets_manager.get_secrets(['PAM_RECORD_UID']).first
record.password = 'StagedNewPassword!'

# Stage the change without committing
secrets_manager.save(record, transaction_type: 'rotation')

# Later: commit or roll back
if validation_passed?
  secrets_manager.complete_transaction(record.uid)
else
  secrets_manager.complete_transaction(record.uid, rollback: true)
end

Download a File

download_file(file)

Parameter	Type	Required	Default	Description
file	KeeperFile	Yes	-	File object from a KeeperRecord to download

Response:

Type: Hash

Returns a hash containing:

• 'name' - File name
• 'data' - File contents as binary string
• 'size' - File size in bytes
• 'type' - MIME type of the file

Example Usage

require 'keeper_secrets_manager'

secrets_manager = KeeperSecretsManager.from_file('keeper_config.json')

# Get record with files
record = secrets_manager.get_secrets(['RECORD_UID']).first

# Check if record has files
if record.files && record.files.any?
  # Download first file
  file = record.files.first
  downloaded = secrets_manager.download_file(file)

  # Save to disk
  filename = downloaded['name'] || 'downloaded_file'
  File.write(filename, downloaded['data'])

  puts "Downloaded: #{filename}"
  puts "Size: #{downloaded['size']} bytes"
  puts "Type: #{downloaded['type']}"
end

Download a File Thumbnail

download_thumbnail(file_data)

Parameter	Type	Required	Default	Description
file_data	KeeperFile or Hash	Yes	-	File object from a record, or a raw file metadata hash

Response:

Type: Hash

Returns a hash containing:

• 'file_uid' - File UID
• 'data' - Decrypted thumbnail contents as a binary string
• 'size' - Thumbnail size in bytes

Example Usage

require 'keeper_secrets_manager'

secrets_manager = KeeperSecretsManager.from_file('keeper_config.json')
record = secrets_manager.get_secrets(['RECORD_UID']).first

if record.files && record.files.any?
  file = record.files.first
  thumb = secrets_manager.download_thumbnail(file)
  File.write('thumbnail.jpg', thumb['data'], mode: 'wb') if thumb
end

Upload a File

upload_file(owner_record_uid, file_data, file_name, file_title = nil)

Parameter	Type	Required	Default	Description
owner_record_uid	String	Yes	-	UID of the record to attach the file to
file_data	String	Yes	-	File contents as binary string or text
file_name	String	Yes	-	Name of the file in Keeper
file_title	String	Optional	nil	Title/description of the file in Keeper

Response:

Type: String

Returns the UID of the uploaded file.

Example Usage

require 'keeper_secrets_manager'

secrets_manager = KeeperSecretsManager.from_file('keeper_config.json')

# Upload a file
file_uid = secrets_manager.upload_file(
  'RECORD_UID',                          # owner_record_uid
  File.read('/path/to/certificate.pem'), # file_data
  'certificate.pem',                      # file_name
  'Server Certificate'                    # file_title (optional)
)

puts "File uploaded with UID: #{file_uid}"

# Upload text content
file_uid = secrets_manager.upload_file(
  'RECORD_UID',
  "server=localhost\nport=5432\n",
  'config.txt',
  'Database Config'
)

Upload from a File Path

upload_file_from_path reads the file from disk automatically, removing the need for a manual File.binread call.

upload_file_from_path(owner_record_uid, file_path, file_title: nil)

Parameter	Type	Required	Default	Description
owner_record_uid	String	Yes	-	UID of the record to attach the file to
file_path	String	Yes	-	Absolute or relative path to the file on disk
file_title	String	Optional	filename	Title shown in Keeper; defaults to the base filename

Response:

Type: String — UID of the uploaded file.

require 'keeper_secrets_manager'

secrets_manager = KeeperSecretsManager.from_file('keeper_config.json')

file_uid = secrets_manager.upload_file_from_path(
  'RECORD_UID',
  '/path/to/certificate.pem',
  file_title: 'Server Certificate'
)

puts "Uploaded with UID: #{file_uid}"

Create a Secret

create_secret(record_data, options = nil)

Parameter	Type	Required	Default	Description
record_data	Hash	Yes	-	Hash containing record structure (type, title, fields, custom, notes)
options	CreateOptions	Yes	-	CreateOptions object containing folder_uid (required) and optional settings

Response:

Type: String

Returns the UID of the created secret.

Prerequisites:

• Shared folder UID (if specifying folder_uid)
• 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
• Record fields must be formatted correctly (see field type documentation)

Example Usage

require 'keeper_secrets_manager'

secrets_manager = KeeperSecretsManager.from_file('keeper_config.json')

# Create a login record
record_data = {
  type: 'login',
  title: 'Production Database',
  fields: [
    { type: 'login', value: ['db_admin'] },
    { type: 'password', value: ['SecurePassword123!'] },
    { type: 'url', value: ['https://db.example.com'] },
    {
      type: 'host',
      value: [{ hostName: '192.168.1.100', port: '5432' }],
      label: 'Database Host'
    }
  ],
  custom: [
    { type: 'text', label: 'Environment', value: ['Production'] },
    { type: 'text', label: 'Database Name', value: ['main_db'] }
  ],
  notes: 'Production database credentials'
}

# Create options with required folder_uid
options = KeeperSecretsManager::Dto::CreateOptions.new(folder_uid: 'FOLDER_UID')

# Create the secret
record_uid = secrets_manager.create_secret(record_data, options)

puts "Secret created with UID: #{record_uid}"

# Alternative: Create options inline
record_uid = secrets_manager.create_secret(
  record_data,
  KeeperSecretsManager::Dto::CreateOptions.new(folder_uid: 'FOLDER_UID')
)

Create Custom Type Record

# Create a database credentials record
record_data = {
  type: 'databaseCredentials',
  title: 'MySQL Production',
  fields: [
    { type: 'text', label: 'Database Type', value: ['MySQL'] },
    {
      type: 'host',
      value: [{ hostName: 'mysql.example.com', port: '3306' }]
    },
    { type: 'login', value: ['root'] },
    { type: 'password', value: ['SecurePassword123!'] }
  ],
  notes: 'MySQL production database'
}

# Create options with required folder_uid
options = KeeperSecretsManager::Dto::CreateOptions.new(folder_uid: 'FOLDER_UID')
record_uid = secrets_manager.create_secret(record_data, options)

Create with Pre-Fetched Folders

create_secret_with_options accepts a CreateOptions object and an optional pre-fetched folder list. Use it when you are creating multiple records in the same session and already hold the folder list — the method skips the internal get_folders call, saving a round-trip.

create_secret_with_options(create_options, record_data, folders: nil)

Parameter	Type	Required	Default	Description
create_options	Dto::CreateOptions	Yes	-	Options object with folder_uid: (required) and subfolder_uid: (optional)
record_data	Dto::KeeperRecord, Hash	Yes	-	Record to create (same shape accepted by create_secret)
folders	Array<KeeperFolder>	Optional	nil	Pre-fetched folder list; fetched automatically when nil

Response:

Type: String — UID of the newly created record.

require 'keeper_secrets_manager'

secrets_manager = KeeperSecretsManager.from_file('keeper_config.json')

# Fetch folders once, reuse for multiple creates
folders = secrets_manager.get_folders
options = KeeperSecretsManager::Dto::CreateOptions.new(folder_uid: 'FOLDER_UID')

record_data = { type: 'login', title: 'My Record', fields: [] }
uid = secrets_manager.create_secret_with_options(options, record_data, folders: folders)
puts "Created: #{uid}"

create_secret is the convenience wrapper for the common single-create case and calls create_secret_with_options internally.

Delete a Secret

delete_secret(uids)

Parameter	Type	Required	Default	Description
uids	String or Array<String>	Yes	-	UID or array of UIDs of secrets to delete

Response:

Type: void

Deletes the specified secret(s) from the vault.

Example Usage

require 'keeper_secrets_manager'

secrets_manager = KeeperSecretsManager.from_file('keeper_config.json')

# Delete a single secret
secrets_manager.delete_secret('RECORD_UID')

puts "Secret deleted successfully"

# Delete multiple secrets
uids = ['UID1', 'UID2', 'UID3']
secrets_manager.delete_secret(uids)

puts "#{uids.length} secrets deleted"

Folders

The Ruby SDK provides full CRUD support for folder operations.

Get Folders

get_folders

Response:

Type: Array<KeeperFolder>

Returns all folders accessible to the Secrets Manager application.

Example Usage

require 'keeper_secrets_manager'

secrets_manager = KeeperSecretsManager.from_file('keeper_config.json')

# Get all folders
folders = secrets_manager.get_folders

folders.each do |folder|
  puts "#{folder.name} (UID: #{folder.uid})"
end

Get Folder Path

get_folder_path(folder_uid)

Parameter	Type	Required	Default	Description
folder_uid	String	Yes	-	UID of the folder

Response:

Type: String

Returns the full path to the folder (breadcrumb trail separated by "/").

Example Usage

# Get folder path (breadcrumb trail)
path = secrets_manager.get_folder_path('FOLDER_UID')
puts "Folder path: #{path}"  # "Parent/Child/Grandchild"

Find Folder by Name

find_folder_by_name(name, parent_uid: nil)

Parameter	Type	Required	Default	Description
name	String	Yes	-	Name of the folder to find
parent_uid	String	Optional	nil	UID of parent folder to search within

Response:

Type: KeeperFolder or nil

Returns the first folder matching the name, or nil if not found.

Example Usage

# Find folder by name
folder = secrets_manager.find_folder_by_name('Finance')

# Find folder within specific parent
folder = secrets_manager.find_folder_by_name('Reports', parent_uid: 'PARENT_UID')

Build Folder Tree

# Get folder manager for advanced operations
fm = secrets_manager.folder_manager

# Build complete folder tree structure
tree = fm.build_folder_tree

# Print folder tree to console
fm.print_tree

# Get folder relationships
ancestors = fm.get_ancestors('FOLDER_UID')      # [parent, grandparent, ...]
descendants = fm.get_descendants('FOLDER_UID')   # [children, grandchildren, ...]

Create a Folder

create_folder(name, parent_uid:)

Parameter	Type	Required	Default	Description
name	String	Yes	-	Name of the folder to create
parent_uid	String	Yes	-	UID of the parent shared folder

Response:

Type: String

Returns the UID of the created folder.

Example Usage

require 'keeper_secrets_manager'

secrets_manager = KeeperSecretsManager.from_file('keeper_config.json')

# Create folder at root level (within a shared folder)
folder_uid = secrets_manager.create_folder('New Folder', parent_uid: 'SHARED_FOLDER_UID')

puts "Folder created with UID: #{folder_uid}"

# Create subfolder within existing folder
subfolder_uid = secrets_manager.create_folder(
  'Subfolder',
  parent_uid: folder_uid
)

puts "Subfolder created: #{subfolder_uid}"

Update a Folder

update_folder(folder_uid, new_name)

Parameter	Type	Required	Default	Description
folder_uid	String	Yes	-	UID of the folder to update
new_name	String	Yes	-	New name for the folder

Response:

Type: void

Renames the specified folder.

Example Usage

require 'keeper_secrets_manager'

secrets_manager = KeeperSecretsManager.from_file('keeper_config.json')

# Rename a folder
secrets_manager.update_folder('FOLDER_UID', 'New Folder Name')

puts "Folder renamed successfully"

Delete Folders

delete_folder(folder_uid, force: false)

Parameter	Type	Required	Default	Description
folder_uid	String	Yes	-	UID of the folder to delete
force	Boolean	Optional	false	If true, deletes folder and all its contents. If false, only deletes empty folders.

Response:

Type: void

Deletes the specified folder from the vault.

Example Usage

require 'keeper_secrets_manager'

secrets_manager = KeeperSecretsManager.from_file('keeper_config.json')

# Delete empty folder
secrets_manager.delete_folder('FOLDER_UID')

# Force delete folder (removes all contents)
secrets_manager.delete_folder('FOLDER_UID', force: true)

puts "Folder deleted"

# Delete multiple folders
folder_uids = ['UID1', 'UID2', 'UID3']
folder_uids.each do |uid|
  secrets_manager.delete_folder(uid, force: true)
end

Caching

Improve performance by caching secrets locally:

Using CachingStorage

require 'keeper_secrets_manager'

# Create base storage
base_storage = KeeperSecretsManager::Storage::FileStorage.new('keeper_config.json')

# Wrap with caching (600 second TTL)
cached_storage = KeeperSecretsManager::Storage::CachingStorage.new(base_storage, 600)

# Use cached storage
secrets_manager = KeeperSecretsManager.new(config: cached_storage)

# First call fetches from server
records = secrets_manager.get_secrets

# Subsequent calls within TTL use cache
records = secrets_manager.get_secrets  # Uses cached data

Built-in Disaster Recovery Cache

KeeperSecretsManager::CachingPostFunction is a drop-in custom_post_function that saves each successful API response to an encrypted local cache file and falls back to that cache automatically when the network is unavailable. This matches the disaster-recovery caching pattern found in the Python, Java, JavaScript, and .NET SDKs.

require 'keeper_secrets_manager'

secrets_manager = KeeperSecretsManager.from_file(
  'keeper_config.json',
  custom_post_function: KeeperSecretsManager::CachingPostFunction
)

# On success: response is cached to ./ksm_cache.bin (or $KSM_CACHE_DIR/ksm_cache.bin)
# On network failure: falls back to last cached response transparently
records = secrets_manager.get_secrets

The cache file location defaults to ./ksm_cache.bin. Set the KSM_CACHE_DIR environment variable to redirect it to a different directory.

To manage the cache directly:

KeeperSecretsManager::Cache.cache_exists?     # Check whether a cache file is present
KeeperSecretsManager::Cache.clear_cache       # Delete the cache file

Custom Caching with custom_post_function

custom_post_function is called only for the read-only get_secret and get_folders paths (create/update/delete always use the SDK's built-in transport), as call(url, transmission_key, encrypted_payload, verify_ssl_certs). It must return a Dto::KSMHttpResponse (status_code:, data:, and an optional http_response:), not a raw response body:

require 'keeper_secrets_manager'

# Create custom cache
cache = {}

custom_post = lambda do |url, transmission_key, encrypted_payload, verify_ssl_certs|
  cache_key = "#{url}:#{transmission_key.public_key_id}"

  # Check cache
  if cache[cache_key] && cache[cache_key][:expires_at] > Time.now
    return cache[cache_key][:response]
  end

  # Make actual request
  uri = URI(url)
  request = Net::HTTP::Post.new(uri)
  request['Content-Type'] = 'application/octet-stream'
  request['PublicKeyId'] = transmission_key.public_key_id.to_s
  request['TransmissionKey'] = KeeperSecretsManager::Utils.bytes_to_base64(transmission_key.encrypted_key)
  request['Authorization'] = "Signature #{KeeperSecretsManager::Utils.bytes_to_base64(encrypted_payload.signature)}"
  request.body = encrypted_payload.encrypted_payload

  http_response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
    http.request(request)
  end

  response = KeeperSecretsManager::Dto::KSMHttpResponse.new(
    status_code: http_response.code.to_i,
    data: http_response.body,
    http_response: http_response
  )

  # Cache response for 10 minutes
  cache[cache_key] = {
    response: response,
    expires_at: Time.now + 600
  }

  response
end

secrets_manager = KeeperSecretsManager.from_file(
  'keeper_config.json',
  custom_post_function: custom_post
)

Error Handling

The SDK provides specific exception classes for different error scenarios:

require 'keeper_secrets_manager'

begin
  secrets_manager = KeeperSecretsManager.from_file('keeper_config.json')
  records = secrets_manager.get_secrets

rescue KeeperSecretsManager::AuthenticationError => e
  puts "Authentication failed: #{e.message}"
  # Token expired or invalid

rescue KeeperSecretsManager::NetworkError => e
  puts "Network error: #{e.message}"
  # Connection timeout or DNS failure
  
rescue KeeperSecretsManager::ThrottledError => e
  puts "Rate limit exceeded: #{e.message}"
  # All automatic retries (up to 5) exhausted; back off before retrying

rescue KeeperSecretsManager::CryptoError => e
  puts "Encryption error: #{e.message}"
  # Decryption failed or key error
  
rescue KeeperSecretsManager::DecryptionError => e
  puts "Decryption failed: #{e.message}"
  # AES-GCM authentication tag failure; wrong key or tampered ciphertext

rescue KeeperSecretsManager::NotationError => e
  puts "Notation parsing error: #{e.message}"
  # Invalid notation URI format

rescue KeeperSecretsManager::Error => e
  puts "General error: #{e.message}"
  # Other SDK errors

rescue StandardError => e
  puts "Unexpected error: #{e.message}"
end

Common Error Scenarios

# Handle missing records gracefully
begin
  record = secrets_manager.get_secret_by_title('Nonexistent Record')
rescue KeeperSecretsManager::Error => e
  puts "Record not found: #{e.message}"
  # Provide fallback or create new record
end

# Retry logic for network errors
max_retries = 3
retries = 0

begin
  records = secrets_manager.get_secrets
rescue KeeperSecretsManager::NetworkError => e
  retries += 1
  if retries < max_retries
    sleep 2 ** retries  # Exponential backoff
    retry
  else
    raise
  end
end

Advanced Configuration

Custom Hostname

require 'keeper_secrets_manager'

# EU datacenter
secrets_manager = KeeperSecretsManager.new(
  token: 'EU:ONE_TIME_TOKEN',
  hostname: 'keepersecurity.eu',
  config: storage
)

# Australian datacenter
secrets_manager = KeeperSecretsManager.new(
  token: 'AU:ONE_TIME_TOKEN',
  hostname: 'keepersecurity.com.au',
  config: storage
)

SSL Certificate Verification

require 'keeper_secrets_manager'

secrets_manager = KeeperSecretsManager.new(
  config: storage,
  verify_ssl_certs: true  # Default is true
)

Custom Logging

require 'keeper_secrets_manager'
require 'logger'

# Create custom logger
logger = Logger.new(STDOUT)
logger.level = Logger::DEBUG

secrets_manager = KeeperSecretsManager.new(
  config: storage,
  logger: logger,
  log_level: Logger::DEBUG
)

HTTP Proxy

Pass proxy_url: at initialization to route all SDK traffic (API calls, file uploads, file downloads) through an HTTP or HTTPS proxy. Authenticated proxies are supported by embedding credentials in the URL.

require 'keeper_secrets_manager'

# Explicit proxy
secrets_manager = KeeperSecretsManager.from_file(
  'keeper_config.json',
  proxy_url: 'http://proxy.example.com:8080'
)

# Authenticated proxy
secrets_manager = KeeperSecretsManager.from_file(
  'keeper_config.json',
  proxy_url: 'http://user:[e-mail]:8080'
)

If proxy_url: is not provided, the SDK checks the HTTPS_PROXY and https_proxy environment variables automatically.

An invalid proxy_url (malformed URL or missing host) raises ArgumentError at initialization with a descriptive message.

All Configuration Options

require 'keeper_secrets_manager'

secrets_manager = KeeperSecretsManager.new(
  token: 'US:ONE_TIME_TOKEN',                   # One-time access token
  config: storage,                              # Storage implementation
  hostname: 'keepersecurity.com',               # API hostname
  verify_ssl_certs: true,                       # SSL verification
  proxy_url: 'http://proxy.example.com:8080',   # HTTP/HTTPS proxy (optional)
  logger: Logger.new(STDOUT),                   # Custom logger
  log_level: Logger::WARN,                      # Log level
  custom_post_function: my_post_func            # Custom HTTP handler
)

Field Type Helpers

Optional convenience methods for creating typed fields:

require 'keeper_secrets_manager'

# Use field helpers for type safety
fields = [
  KeeperSecretsManager::FieldTypes::Helpers.login('admin'),
  KeeperSecretsManager::FieldTypes::Helpers.password('SecurePass123!'),
  KeeperSecretsManager::FieldTypes::Helpers.url('https://example.com'),
  KeeperSecretsManager::FieldTypes::Helpers.host(
    hostname: '192.168.1.100',
    port: 22
  ),
  KeeperSecretsManager::FieldTypes::Helpers.name(
    first: 'John',
    middle: 'Q',
    last: 'Doe'
  ),
  KeeperSecretsManager::FieldTypes::Helpers.address(
    street1: '123 Main St',
    city: 'New York',
    state: 'NY',
    zip: '10001'
  )
]

# Convert to hashes for record creation
record_data = {
  type: 'login',
  title: 'Server with Helpers',
  fields: fields.map(&:to_h)
}

# Create options with required folder_uid
options = KeeperSecretsManager::Dto::CreateOptions.new(folder_uid: 'FOLDER_UID')
record_uid = secrets_manager.create_secret(record_data, options)

Dynamic Record Access

The Ruby SDK uses method_missing to provide JavaScript-style dynamic field access:

# Get record
record = secrets_manager.get_secrets(['RECORD_UID']).first

# Dynamic getters
login = record.login          # Returns field value
password = record.password    # Returns field value
url = record.url             # Returns field value

# Dynamic setters
record.password = 'NewPassword123!'
record.url = 'https://newurl.example.com'

# Check if field exists
if record.respond_to?(:oneTimeCode)
  # Generate TOTP code from oneTimeCode field
  require 'keeper_secrets_manager/totp'
  totp_url = record.oneTimeCode
  totp_params = KeeperSecretsManager::TOTP.parse_url(totp_url)
  totp_code = KeeperSecretsManager::TOTP.generate_code(
    totp_params['secret'],
    algorithm: totp_params['algorithm'],
    digits: totp_params['digits'],
    period: totp_params['period']
  )
end

# Access all fields as an Array of field hashes
fields = record.fields
fields.each do |field|
  puts "#{field['type']}: #{Array(field['value']).join(', ')}"
end