LogoLogo
KeeperPAM and Secrets Manager
KeeperPAM and Secrets Manager
  • KeeperPAM
  • Privileged Access Manager
    • Setup Steps
    • Quick Start: Sandbox
    • Getting Started
      • Architecture
        • Architecture Diagram
        • Vault Security
        • Router Security
        • Gateway Security
        • Connection and Tunnel Security
      • KeeperPAM Licensing
      • Enforcement Policies
      • Vault Structure
      • Record Linking
      • Applications
      • Devices
      • Gateways
        • Creating a Gateway
        • Docker Installation
        • Linux Installation
        • Windows Installation
        • Auto Updater
        • Alerts and SIEM Integration
        • Advanced Configuration
          • Gateway Configuration with AWS KMS
          • Gateway Configuration with Custom Fields
      • PAM Configuration
        • AWS Environment Setup
        • Azure Environment Setup
        • Local Environment Setup
      • PAM Resources
        • PAM Machine
          • Example: Linux Machine
          • Example: Azure Windows VM
        • PAM Database
          • Example: MySQL Database
          • Example: PostgreSQL Database
          • Example: Microsoft SQL Server Database
        • PAM Directory
        • PAM Remote Browser
        • PAM User
      • Sharing and Access Control
      • Just-In-Time Access (JIT)
    • Password Rotation
      • Rotation Overview
      • Rotation Use Cases
        • Azure
          • Azure AD Users
          • Azure VM User Accounts
          • Azure Managed Database
            • Azure SQL
            • Azure MySQL - Single or Flexible Database
            • Azure MariaDB Database
            • Azure PostgreSQL - Single or Flexible Database
          • Azure App Secret Rotation
        • AWS
          • IAM User Password
          • Managed Microsoft AD User
          • EC2 Virtual Machine User
          • IAM User Access Key
          • Managed Database
            • AWS RDS for MySQL
            • AWS RDS for SQL Server
            • AWS RDS for PostgreSQL
            • AWS RDS for MariaDB
            • AWS RDS for Oracle
        • Local Network
          • Active Directory or OpenLDAP User
          • Windows User
          • Linux User
          • macOS User
          • Database
            • Native MySQL
            • Native MariaDB
            • Native PostgreSQL
            • Native MongoDB
            • Native MS SQL Server
            • Native Oracle
        • SaaS Accounts
          • Okta User
          • Snowflake User
          • Rotate Credential via REST API
        • Network Devices
          • Cisco IOS XE
          • Cisco Meraki
      • Service Management
      • Post-Rotation Scripts
        • Inputs and Outputs
        • Attaching Scripts
        • Code Examples
    • Connections
      • Getting Started
      • Session Protocols
        • SSH Connections
        • RDP Connections
        • MySQL Connections
        • SQL Server Connections
        • PostgreSQL Connections
        • VNC Connections
        • Telnet Connections
        • Kubernetes
        • RBI Connections
      • Examples
        • SSH Protocol - Linux Machine
        • RDP Protocol - Azure Virtual Machine
        • MySQL Protocol - MySQL Database
        • PostgreSQL Protocol - PostgreSQL Database
    • Tunnels
      • Setting up Tunnels
    • Remote Browser Isolation
      • Setting up RBI
        • URL Patterns & Resource URL Patterns
        • Browser Autofill
    • Session Recording & Playback
    • SSH Agent
      • Integration with Git
    • Discovery
      • Discovery Basics
      • Discovery using Commander
      • Discovery using the Vault
    • KeeperAI
    • On-Prem Connection Manager
    • References
      • Port Mapping
      • Setting up SSH
      • Setting up WinRM
      • Setting up SQL Server
      • Database Import and Export
      • Installing sqlcmd on Linux
      • Installing Docker on Linux
      • Creating KSM App for Rotation
      • Active Directory Least Privilege
      • Event Reporting
      • Importing PAM Records
      • Managing Rotation via CLI
      • Commander SDK
      • Cron Spec
      • Preview Access
  • Endpoint Privilege Manager
    • Overview
    • Setup
    • Deployment
    • Policies
    • Managing Requests
  • FAQs
  • Secrets Manager
    • Secrets Manager Overview
    • Quick Start Guide
    • About KSM
      • Architecture
      • Terminology
      • Security & Encryption Model
      • One Time Access Token
      • Secrets Manager Configuration
      • Keeper Notation
      • Event Reporting
      • Field/Record Types
    • Secrets Manager CLI
      • Profile Command
      • Init Command
      • Secret Command
      • Folder Command
      • Sync Command
      • Exec Command
      • Config Command
      • Version Command
      • Misc Commands
      • Docker Container
      • Custom Record Types
    • Password Rotation
    • Developer SDKs
      • Python SDK
      • Java/Kotlin SDK
        • Record Field Classes
      • JavaScript SDK
      • .NET SDK
      • Go SDK
        • Record Field Classes
      • PowerShell
      • Vault SDKs
    • Integrations
      • Ansible
        • Ansible Plugin
        • Ansible Tower
      • AWS CLI Credential Process
      • AWS Secrets Manager Sync
      • AWS KMS Encryption
      • Azure DevOps Extension
      • Azure Key Vault Sync
      • Azure Key Vault Encryption
      • Bitbucket Plugin
      • Docker Image
      • Docker Runtime
      • Docker Writer Image
      • Entrust HSM Encryption
      • Git - Sign Commits with SSH
      • GitHub Actions
      • GitLab
      • Google Cloud Secret Manager Sync
      • Google Cloud Key Management Encryption
      • Hashicorp Vault
      • Heroku
      • Jenkins Plugin
      • Keeper Connection Manager
      • Kubernetes External Secrets Operator
      • Kubernetes (alternative)
      • Linux Keyring
      • Octopus Deploy
      • Oracle Key Vault Encryption
      • PowerShell Plugin
      • ServiceNow
      • TeamCity
      • Teller
      • Terraform Plugin
        • Terraform Registry
      • Windows Credential Manager
      • XSOAR
    • Troubleshooting
  • Commander CLI
    • Commander Overview
    • Installation and Setup
      • CLI Installation on Windows
      • CLI Installation on macOS
      • CLI Installation on Linux
      • Python Developer Setup
      • .NET Developer Setup
      • PowerShell Module
      • Logging in
      • Configuration and Usage
        • AWS Secrets Manager
        • AWS Key Management Service
      • Automating with Windows Task
      • Automating with AWS Lambda
      • Uninstallation
    • Command Reference
      • Import and Export Data
        • Import/Export Commands
        • CyberArk Import
        • LastPass Data Import
        • Delinea / Thycotic Secret Server Import
        • Keepass Import
        • ManageEngine Import
        • Myki Import
        • Proton Pass Import
        • CSV Import
        • JSON Import
      • Reporting Commands
        • Report Types
      • Enterprise Management Commands
        • Creating and Inviting Users
        • Compliance Commands
        • Breachwatch Commands
        • SCIM Push Configuration
      • Record Commands
        • Record Type Commands
        • Creating Record Types
      • Sharing Commands
      • KeeperPAM Commands
      • Connection Commands
        • SSH
        • SSH Agent
        • RDP
        • Connect Command
        • SFTP Sync
      • Secrets Manager Commands
      • MSP Management Commands
      • Miscellaneous Commands
      • Password Rotation
        • Password Rotation Commands
        • AWS Plugin
        • Azure Plugin
        • Microsoft SQL Server Plugin
        • MySQL Plugin
        • Oracle Plugin
        • PostgreSQL Plugin
        • PSPasswd Plugin
        • SSH Plugin
        • Unix Passwd Plugin
        • Windows Plugin
        • Active Directory Plugin
        • Automatic Execution
    • Service Mode REST API
    • Troubleshooting
Powered by GitBook

Company

  • Keeper Home
  • About Us
  • Careers
  • Security

Support

  • Help Center
  • Contact Sales
  • System Status
  • Terms of Use

Solutions

  • Enterprise Password Management
  • Business Password Management
  • Privileged Access Management
  • Public Sector

Pricing

  • Business and Enterprise
  • Personal and Family
  • Student
  • Military and Medical

© 2025 Keeper Security, Inc.

On this page
  • Download and Installation
  • Install With Maven or Gradle
  • Cryptographic Provider
  • Source Code
  • Initialize Storage
  • Retrieve Secrets
  • Retrieve Secrets by Title
  • Retrieve Values From a Secret
  • Update Values in a Secret
  • Download a File
  • Download a Thumbnail
  • Upload a File
  • Create a Secret
  • Delete a Secret
  • Caching
  • Folders
  • Read Folders
  • Create a Folder
  • Update a Folder
  • Delete Folders

Was this helpful?

Export as PDF
  1. Secrets Manager
  2. Developer SDKs

Java/Kotlin SDK

Detailed Java and Kotlin SDK docs for Keeper Secrets Manager

PreviousPython SDKNextRecord Field Classes

Last updated 4 months ago

Was this helpful?

Download and Installation

Install With Maven or Gradle

build.gradle
repositories {
    mavenCentral()
}

dependencies {
    implementation 'com.keepersecurity.secrets-manager:core:17.0.0+'
    implementation("org.bouncycastle:bc-fips:1.0.2.4")
}
pom.xml
<dependency>
  <groupId>com.keepersecurity.secrets-manager</groupId>
  <artifactId>core</artifactId>
  <version>[17.0.0,)</version>
</dependency>

Cryptographic Provider

The Keeper Secrets Manager SDK expects the developer to use their required cryptographic provider. As documented above, Keeper will use the default cryptographic module of the Java runtime unless a specific provider is added. In the examples here in this documentation, we are using the BouncyCastle FIPS provider.

In the source code, ensure that the provider is loaded in the security context:

fun main() {
    Security.addProvider(BouncyCastleFipsProvider())
...

See the file CryptoUtilsTest.kt as shown in this on how to use a custom security provider.

Source Code

Initialize Storage

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

In order to retrieve secrets, you must first initialize the local storage on your machine.

initializeStorage(storage: KeyValueStorage, clientKey: String? = null, hostName: String? = null)

Parameter

Type

Required

Default

Description

storage

KeyValueStorage

Yes

clientKey

String

Optional

null

hostName

String

Optional

null

Example Usage

import static com.keepersecurity.secretsManager.core.SecretsManager.initializeStorage;
import com.keepersecurity.secretsManager.core.LocalConfigStorage;
import com.keepersecurity.secretsManager.core.SecretsManagerOptions;
import java.security.Security;
import org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider;

// oneTimeToken is used only once to initialize the storage
// after the first run, subsequent calls will use "ksm-config.txt" file
String oneTimeToken = "[One Time Access Token]";
LocalConfigStorage storage = new LocalConfigStorage("ksm-config.txt");

Security.addProvider(new BouncyCastleFipsProvider());

try {
    initializeStorage(storage, oneTimeToken);
    SecretsManagerOptions options = new SecretsManagerOptions(storage);
    // Using token only to generate a config (for later usage)
    // requires at least one access operation to bind the token
    //getSecrets(options)
 } catch (Exception e) {
    System.out.println(e.getMessage());
 }

Retrieve Secrets

getSecrets(options: SecretsManagerOptions, recordsFilter: List<String> = emptyList()): KeeperSecrets

Parameter

Type

Required

Default

Description

options

SecretsManagerOptions

Yes

Storage and query configuration

recordsFilter

List<String>

Optional

Empty List

Record search filters

Response

Type: KeeperSecrets

Object containing all Keeper records, or records that match the given filter criteria

Example Usage

Retrieve all Secrets

import com.keepersecurity.secretsManager.core.SecretsManagerOptions;
import com.keepersecurity.secretsManager.core.SecretsManager;
import com.keepersecurity.secretsManager.core.KeeperRecord;
import com.keepersecurity.secretsManager.core.KeeperSecrets;
import java.security.Security;
import org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider;

// Ensure security provider is loaded
Security.addProvider(new BouncyCastleFipsProvider());

//get secrets
SecretsManagerOptions options = new SecretsManagerOptions(storage);
KeeperSecrets secrets = SecretsManager.getSecrets(options);

//get records from secrets
List<KeeperRecord> records = secrets.getRecords();

Retrieve one secret by UID

import com.keepersecurity.secretsManager.core.SecretsManagerOptions;
import com.keepersecurity.secretsManager.core.SecretsManager;
import com.keepersecurity.secretsManager.core.KeeperRecord;
import com.keepersecurity.secretsManager.core.KeeperSecrets;
import java.security.Security;
import org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider;

// Ensure security provider is loaded
Security.addProvider(new BouncyCastleFipsProvider());

//get secrets
SecretsManagerOptions options = new SecretsManagerOptions(storage);
KeeperSecrets secrets = SecretsManager.getSecrets(options);

// identify one or more record UID to fetch secrets by
List<String> uidFilter = List.of("[XXX]");

// fetch secrets with the filter
KeeperSecrets secrets = SecretsManager.getSecrets(options, uidFilter);

//get records from secrets
List<KeeperRecord> records = secrets.getRecords();

Retrieve Secrets by Title

// get all matching records
getSecretsByTitle(recordTitle: String): List<KeeperRecord>

// get only the first matching record
getSecretByTitle(recordTitle: String): KeeperRecord
Parameter
Type
Required
Description

recordTitle

String

Yes

Record title to search for

Example Usage

import com.keepersecurity.secretsManager.core.*;
import java.util.List;

public class KSMSample {
    public static void main(String[] args){
        
        // Ensure security provider is loaded
        Security.addProvider(new BouncyCastleFipsProvider());

        // get pre-initialized storage
        KeyValueStorage storage = new LocalConfigStorage("ksm-config.json");
        try {
            SecretsManagerOptions options = new SecretsManagerOptions(storage);

            // title of the record to fetch
            String recordTitle = "My Credentials";
            
            // search for record by title
            KeeperRecord myCredentials = secrets.getRecords().getSecretByTitle(recordTitle);

            // print out record details
            System.out.println("Record UID: " + myCredentials.getRecordUid());
            System.out.println("Title: " + myCredentials.getData().getTitle());
        } catch (Exception e) {
            System.out.println(e.getMessage());
        }
    }
}

Retrieve Values From a Secret

Retrieve a Password

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

secret.getPassword()
import com.keepersecurity.secretsManager.core.SecretsManagerOptions;
import com.keepersecurity.secretsManager.core.SecretsManager;
import com.keepersecurity.secretsManager.core.KeeperRecord;
import com.keepersecurity.secretsManager.core.KeeperSecrets;
import java.security.Security;
import org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider;

// Ensure security provider is loaded
Security.addProvider(new BouncyCastleFipsProvider());

//get secrets
SecretsManagerOptions options = new SecretsManagerOptions(storage);
KeeperSecrets secrets = SecretsManager.getSecrets(options);

//get the first record
List<KeeperRecord> records = secrets.getRecords().get(0);

//get the password from the first record
firstRecord.getPassword()

Retrieve Fields

secret.getData().getField(<FIELD_TYPE>)
import com.keepersecurity.secretsManager.core.SecretsManagerOptions;
import com.keepersecurity.secretsManager.core.SecretsManager;
import com.keepersecurity.secretsManager.core.KeeperRecord;
import com.keepersecurity.secretsManager.core.KeeperSecrets;
import java.security.Security;
import org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider;

// Ensure security provider is loaded
Security.addProvider(new BouncyCastleFipsProvider());

//get secrets
SecretsManagerOptions options = new SecretsManagerOptions(storage);
KeeperSecrets secrets = SecretsManager.getSecrets(options);

//get the first record
List<KeeperRecord> records = secrets.getRecords();
KeeperRecord firstRecord = secrets.getRecords().get(0);

//get the password from the first record
KeeperRecordField pwd = firstRecord.getData().getField(Password.class)

Keeper Notation

Notation.getValue(secret, "<query>");
// Query example "<RECORD UID>/field/login"
import static com.keepersecurity.secretsManager.core.SecretsManager.*
import static com.keepersecurity.secretsManager.core.Notation.*;
import java.security.Security;
import org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider;

// Ensure security provider is loaded
Security.addProvider(new BouncyCastleFipsProvider());

// get secrets
KeeperSecrets secrets = getSecrets(options);

// get login with dot notation
String login = getValue(secrets, "BediNKCMG21ztm5xGYgNww/field/login");

Parameter

Type

Required

Default

Description

secret

KeeperRecord

Yes

Record to get field value from

query

String

Yes

Dot notation query of desired field

Get TOTP Code

TotpCode.uriToTotpCode(url)
import static com.keepersecurity.secretsManager.core.Notation.*;
import static com.keepersecurity.secretsManager.core.TotpCode.*;
import java.security.Security;
import org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider;

...

// get secrets
KeeperSecrets secrets = getSecrets(options);

// get TOTP url from record
String url= getValue(secrets, "BediNKCMG21ztm5xGYgNww/field/oneTimeCode");

// get TOTP code
TotpCode totp = uriToTotpCode(url);

Parameter

Type

Required

Default

Description

url

String

Yes

TOTP Url

Update Values in 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

updateSecret(options: SecretsManagerOptions, recordToUpdate: KeeperRecord);
import com.keepersecurity.secretsManager.core.KeeperRecord;
import com.keepersecurity.secretsManager.core.KeeperSecrets;
import com.keepersecurity.secretsManager.core.SecretsManagerOptions;
import static com.keepersecurity.secretsManager.core.SecretsManager.*;

// Ensure security provider is loaded
Security.addProvider(new BouncyCastleFipsProvider());

// get secrets
SecretsManagerOptions options = SecretsManagerOptions(storage);
KeeperSecrets secrets = getSecrets(options);

// we'll update the first record
KeeperRecord recordToUpdate = secrets.getRecords().get(0);

// update password
recordToUpdate.updatePassword("aP1$t367QOCvL$eM$bG#");

// update title and notes
recordToUpdate.data.title = "New Title"
recordToUpdate.data.notes = "My Notes"

// save changes
updateSecret(options, recordToUpdate); 
import com.keepersecurity.secretsManager.core.KeeperRecord;
import com.keepersecurity.secretsManager.core.KeeperSecrets;
import com.keepersecurity.secretsManager.core.SecretsManagerOptions;

import static com.keepersecurity.secretsManager.core.SecretsManager.*;

...

// get secrets
SecretsManagerOptions options = SecretsManagerOptions(storage);
KeeperSecrets secrets = getSecrets(options);

// we'll update the first record
KeeperRecord record = secrets.getRecords().get(0);

// rotate password on the record
record.updatePassword("aP1$t367QOCvL$eM$bG#");

// start a transaction
updateSecret(options, record, transactionType = UpdateTransactionType.GENERAL);
// rotate password on remote host
boolean success = rotateRemoteSshPassword("aP1$t367QOCvL$eM$bG#");
// complete the transaction - commit or rollback
completeTransaction(options, record.recordUid, rollback = !success);

Update Secret is used to save changes made to a secret. Once updateSecret is performed successfully, the changes are reflected in the Keeper Vault.

Parameter

Type

Required

Default

Description

options

SecretsManagerOptions

Yes

Storage and query configuration

recordToUpdate

KeeperRecord

Yes

Record to update

Update Password

recordToUpdate.updatePassword(password: String);

SecretsManager.updateSecret(options, recordToUpdate);
import static com.keepersecurity.secretsManager.core.SecretsManager;

import com.keepersecurity.secretsManager.core.SecretsManagerOptions;
import com.keepersecurity.secretsManager.core.KeeperRecord;
import com.keepersecurity.secretsManager.core.KeeperSecrets;

// get secrets
SecretsManagerOptions options = SecretsManagerOptions(storage);
KeeperSecrets secrets = getSecrets(options);

// we'll update the first record
KeeperRecord recordToUpdate = secrets.getRecords().get(0);

// update password
recordToUpdate.updatePassword("aP1$t367QOCvL$eM$bG#");

// save changes
SecretsManager.updateSecret(options, recordToUpdate);

Parameter

Type

Required

Default

Description

password

String

Yes

New password to set

Update other fields

//format
RecordField.getValue().set(index, value)

//example - Login field
recordLogin.getValue().set(0, "New Login");
// get field to edit
Login recordLogin = (Login) recordToUpdate.getData().getField(Login.class);

// update field value
recordLogin.getValue().set(0, "New Login");

// save changes
SecretsManager.updateSecret(options, recordToUpdate);

Fields can have multiple values, which is accessed in a List. In this example we are updating the login field, which only accepts one value, so we update the one value in the values list.

Generate a Random Password

generatePassword(length: int, lowercase: int, uppercase: int, digits: int, specialCharacters: int)
import com.keepersecurity.secretsManager.core.CryptoUtils;

// Ensure security provider is loaded
Security.addProvider(new BouncyCastleFipsProvider());

// get field to edit
Password recordPassword = (Password) recordToUpdate.getData().getField(Password.class);

// generate a random password
String password = CryptoUtils.generatePassword();

// update field value
recordPassword.getValue().set(0, password);

// save changes
SecretsManager.updateSecret(options, recordToUpdate);
Parameter
Type
Required
Default

length

int

Optional

64

lowercase

int

Optional

0

uppercase

int

Optional

0

digits

int

Optional

0

specialCharacters

int

Optional

0

Each parameter indicates the min number of a type of character to include. For example, 'uppercase' indicates the minimum number of uppercase letters to include.

Download a File

SecretsManager.downloadFile(file): ByteArray
import static com.keepersecurity.secretsManager.core.SecretsManager;
import com.keepersecurity.secretsManager.core.KeeperRecord;
import com.keepersecurity.secretsManager.core.KeeperFile;

// Ensure security provider is loaded
Security.addProvider(new BouncyCastleFipsProvider());

// download the first file from the first record
KeeperRecord firstRecord = secrets.getRecords().get(0);
KeeperFile file = firstRecord.getFileByName("acme.cer");
byte[] fileBytes = SecretsManager.downloadFile(file);

// write file to a disk
try (FileOutputStream fos = new FileOutputStream(file.getData().getName())) {
    fos.write(fileBytes);
} catch (IOException ioException){
    ioException.printStackTrace();
}

Parameter

Type

Required

Default

Description

file

KeeperFile

Yes

File to download

Response

Type: ByteArray

ByteArray of file for download

Download a Thumbnail

SecretsManager.downloadThumbnail(file): ByteArray
import static com.keepersecurity.secretsManager.core.SecretsManager;
import com.keepersecurity.secretsManager.core.KeeperRecord;
import com.keepersecurity.secretsManager.core.KeeperFile;

// Ensure security provider is loaded
Security.addProvider(new BouncyCastleFipsProvider());

// download the first file from the first record
KeeperRecord firstRecord = secrets.getRecords().get(0);
KeeperFile file = firstRecord.getFileByName("acme.cer");
byte[] fileBytes = SecretsManager.downloadThumbnail(file);

// write file to a disk
try (FileOutputStream fos = new FileOutputStream(file.getData().getName())) {
    fos.write(fileBytes);
} catch (IOException ioException){
    ioException.printStackTrace();
}

Parameter

Type

Required

Default

Description

file

KeeperFile

Yes

File with thumbnail to download

Response

Type: ByteArray

ByteArray of thumbnail for download

Upload a File

Upload File:

uploadFile(options: SecretsManagerOptions, ownerRecord: KeeperRecord, file: KeeperFileUpload): String
Parameter
Type
Required
Description

options

SecretsManagerOptions

Yes

Storage and query configuration

ownerRecord

KeeperRecord

Yes

The record to attach the uploaded file to

file

KeeperFileUpload

Yes

The File to upload

Creating the Keeper File Upload Object:

KeeperFileUpload(
    val name: String,
    val title: String,
    val type: String?,
    val data: ByteArray
)
Parameter
Type
Required
Description

name

string

Yes

What the name of the file will be in Keeper once uploaded

title

string

Yes

What the title of the file will be in Keeper once uploaded

type

string

Optional

The mime type of data in the file. 'application/octet-stream' will be used if nothing is given

data

ByteArray

Yes

File data as bytes

Example Usage

import com.keepersecurity.secretsManager.core.*;

import java.io.File;
import java.io.FileInputStream;
import java.util.Arrays;

public class KSMSample {
    public static void main(String[] args){
    
        // Ensure security provider is loaded
        Security.addProvider(new BouncyCastleFipsProvider());

        // get pre-initialized storage
        KeyValueStorage storage = new LocalConfigStorage("ksm-config.json");
        try {
            SecretsManagerOptions options = new SecretsManagerOptions(storage);

            // create a filter with the UID of the record we want
            List<String> uidFilter = List.of("XXX");

            // fetch secrets with the filter
            KeeperSecrets secrets = SecretsManager.getSecrets(options, uidFilter);

            // get the desired secret to upload a file to
            KeeperRecord ownerRecord = secrets.getRecords().get(0);
        
            // get bytes from file to upload
            File file = new File("./myFile.json");
            FileInputStream fl = new FileInputStream(file);
            byte[] fileBytes = new byte[(int)file.length()];
            fl.read(fileBytes);
            fl.close();
            
            // create a Keeper File to upload
            KeeperFileUpload myFile = new KeeperFileUpload(
                "myFile.json",
                "My File", 
                "application/json", 
                fileBytes
            )

            // upload the file to the selected record
            SecretsManager.uploadFile(options, ownerRecord, myFile);
            
        } catch (Exception e) {
            System.out.println("KSM ran into an problem: " + e.getMessage());
        }
    }
}

Create a Secret

Prerequisites:

  • Shared 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

  • Created records and record fields must be formatted correctly

  • TOTP fields accept only URL generated outside of the KSM SDK

SecretsManager.createSecret(options, folderUid, newRecordData, secrets);
Parameter
Type
Required
Default

options

SecretsManagerOptions

Yes

folderUid

String

Yes

newRecordData

KeeperRecordData

Yes

secrets

KeeperSecrets

Optional

Freshly fetched list of all secrets from the Keeper servers

SecretsManager.createSecret2(options, createOptions, newRecordData, folders);
Parameter
Type
Required
Default

options

SecretsManagerOptions

Yes

createOptions

CreateOptions

Yes

newRecordData

KeeperRecordData

Yes

folders

KeeperFolder[]

Optional

Freshly fetched list of all folders from the Keeper servers

This example creates a login type record with a login value and a generated password.

Replace '[FOLDER UID]' in the example with the UID of a shared folder that your Secrets Manager Application has access to.

import com.keepersecurity.secretsManager.core.*;

KeeperRecordData newRecordData = new KeeperRecordData(
        "Sample KSM Record: Java",
        "login",
        Arrays.asList(
                new Login("My Username"),
                new Password(CryptoUtils.generatePassword())
        ),
        null,
        "This is a \nmultiline\n\n\tnote"
);

String recordUid = SecretsManager.createSecret(options, folderUid, newRecordData);

This example creates a record with a custom record type.

Replace '[FOLDER UID]' in the example with the UID of a shared folder that your Secrets Manager Application has access to.

import com.keepersecurity.secretsManager.core.*;

KeeperRecordData newRecordData = new KeeperRecordData(
        "Sample Custom Type KSM Record: Java",
        "Custom Login",                              // Record Type Name
        Arrays.asList(
                new Hosts(
                        "My Custom Host lbl",        // label
                        true,                        // required
                        false,                       // private screen
                        List.of(new Host("127.0.0.1", "8000"))),
                // OR new Hosts(new Host("127.0.0.1", "8000"))

                new Login("My Custom Login lbl",
                        true,
                        false,
                        List.of("login@email.com")),
                // OR new Login("username@email.com")

                new Password( "My Custom Password lbl",
                        true,
                        false,
                        List.of(CryptoUtils.generatePassword())),
                // OR new Password(CryptoUtils.generatePassword())

                new Url("My Login Page",
                        true,
                        false,
                        List.of("http://localhost:8080/login")),
                // OR new Url("http://localhost:8080/login")
                
                new SecurityQuestions(
                        "My Question 1",
                        true,
                        false,
                        List.of(new SecurityQuestion("What is one plus one (write just a number)", "2"))),
                // OR new SecurityQuestions(new SecurityQuestion("What is one plus one (write just a number)", "2"))

                new Phones("My Phone Number",
                        true,
                        false,
                        List.of(new Phone("US", "510-444-3333", "2345", "Mobile"))),
                // OR new Phones(new Phone("US", "510-444-3333", "2345", "Mobile"))

                new Date("My Date Lbl",
                        true,
                        false,
                        List.of(1641934793000L)
                ),
                // OR new Date(1641934793000L),

                new Names("My Custom Name lbl",
                        true,
                        false,
                        List.of(new Name("John", "Patrick", "Smith"))),
                // OR new Names(new Name("John", "Patrick", "Smith"))

                new OneTimeCode("My TOTP",
                        true,
                        false,
                        List.of("otpauth://totp/Example:alice@google.com?secret=JBSWY3DPEHPK3PXP&issuer=Example"))
                // OR new OneTimeCode("otpauth://totp/Example:alice@google.com?secret=JBSWY3DPEHPK3PXP&issuer=Example")
        ),
        Arrays.asList(
                new Phones(new Phone("US", "(510) 123-3456")),
                new Phones(new Phone("US", "510-111-3333", "45674", "Mobile"))
        ),
        "\tThis custom type record was created\n\tvia KSM Java Document Example"
);

String recordUid = SecretsManager.createSecret(options, "[FOLDER UID]", newRecordData);

Delete a Secret

The Java/Kotlin KSM SDK can delete records in the Keeper Vault.

deleteSecret(smOptions, recordUids);

Parameter
Type
Required

smOptions

SecretsManagerOptions

Yes

recordUids

List<Sting>

Yes

// setup secrets manager
val storage = LocalConfigStorage("ksm-config.json")
//initializeStorage(storage, "<One Time Access Token>")
val smOptions = SecretsManagerOptions(storage)

// delete a specific secret by record UID
deleteSecret(smOptions, List.of("EG6KdJaaLG7esRZbMnfbFA"));

Caching

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

Setup and Configure Cache

In order to setup caching in the Java SDK, include a caching post function as the second argument when instantiating aSecretsManagerOptions object.

The Java SDK includes a default caching function cachingPostFunction which stores cached queries to a file.

//create options with caching
SecretsManagerOptions options = new SecretsManagerOptions(storage, SecretsManager::cachingPostFunction);

//example get all secrets
SecretsManager.getSecrets(options)

Folders

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

Read Folders

Downloads full folder hierarchy.

getFolders(options: SecretsManagerOptions): List<KeeperFolder>

Response

Type: List<KeeperFolder>

Example Usage

import com.keepersecurity.secretsManager.core.*;
SecretsManagerOptions options = new SecretsManagerOptions(new LocalConfigStorage("ksm-config.json"));
List<KeeperFolder> folders = SecretsManager.getFolders(options);

Create a Folder

Requires CreateOptions and folder name to be provided. The folder UID parameter in CreateOptions is required - UID of a shared folder, while sub-folder UID is optional and if missing 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.

createFolder(options: SecretsManagerOptions, createOptions: CreateOptions, folderName: String, folders: List<KeeperFolder> = getFolders(options)): String
Parameter
Type
Required
Default
Description

options

SecretsManagerOptions

Yes

Preconfigured options

createOptions

CreateOptions

Yes

The parent and sub-folder UIDs

folderName

String

Yes

The Folder name

folders

List<KeeperFolder>

No

List<KeeperFolder>

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

data class CreateOptions  constructor(
    val folderUid: String,
    val subFolderUid: String? = null,
)
data class KeeperFolder(
    val folderKey: ByteArray,
    val folderUid: String,
    val parentUid: String? = null,
    val name: String
)

Example Usage

import com.keepersecurity.secretsManager.core.*;
SecretsManagerOptions options = new SecretsManagerOptions(new LocalConfigStorage("ksm-config.json"));
CreateOptions co := new CreateOptions("[PARENT_SHARED_FOLDER_UID]");
String folderUid = SecretsManager.createFolder(options, co, "new_folder");

Update a Folder

Updates the folder metadata - currently folder name only.

updateFolder(options: SecretsManagerOptions, folderUid: String, folderName: String, folders: List<KeeperFolder> = getFolders(options))
Parameter
Type
Required
Default
Description

options

SecretsManagerOptions

Yes

Preconfigured options

folderUid

String

Yes

The folder UID

folderName

String

Yes

The new folder name

folders

List<KeeperFolder>

No

List<KeeperFolder>

List of folders to use in the search for parent folder

Example Usage

import com.keepersecurity.secretsManager.core.*;
SecretsManagerOptions options = new SecretsManagerOptions(new LocalConfigStorage("ksm-config.json"));
SecretsManager.updateFolder(options, "[FOLDER_UID]", "new_folder_name");

Delete Folders

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

When using forceDeletion 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.

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

deleteFolder(options: SecretsManagerOptions, folderUids: List<String>, forceDeletion: Boolean = false): SecretsManagerDeleteResponse
Parameter
Type
Required
Default
Description

options

SecretsManagerOptions

Yes

Preconfigured options

folderUids

List<String>

Yes

The folder UID list

forceDeletion

Boolean

No

false

Force deletion of non-empty folders

Example Usage

import com.keepersecurity.secretsManager.core.*;
SecretsManagerOptions options = new SecretsManagerOptions(new LocalConfigStorage("ksm-config.json"));
SecretsManager.deleteFolder(options, Arrays.asList("[FOLDER_UID1]", "[FOLDER_UID2]"), true);

Find the Java/Kotlin source code in the

To get a field value, you will need to cast the return to the of the corresponding field type. For a list of field types see the page.

See to learn about Keeper Notation format and capabilities

Each record field type is represented by a class. Cast the field to the corresponding class in order to correctly access the field's value. Check the documentation for a list of field types.

See the for expected field formats for each record type

After record creation, you can upload file attachments using

example
GitHub repository
Keeper Notation documentation
uploadFile
class
Record Types
Record Types
documentation