Java/Kotlin SDK

Detailed Java and Kotlin SDK docs for Keeper Secrets Manager
Download and Installation
Install With Maven or Gradle
Maven
Gradle
pom.xml
<dependency>
  <groupId>com.keepersecurity.secrets-manager</groupId>
  <artifactId>core</artifactId>
  <version>[16.6.2,)</version>
</dependency>
build.gradle
repositories {
    mavenCentral()
}
​
dependencies {
    implementation 'com.keepersecurity.secrets-manager:core:16.6.2+'
}
Source Code
Find the Java/Kotlin source code in the GitHub repository​
Using the SDK
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;
​
// 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");
​
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;
​
//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;
​
//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){
        // 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.
Get Password
Example Usage
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;
​
//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
Get Field
Example Usage
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;
​
//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)
To get a field value, you will need to cast the return to the class of the corresponding field type. For a list of field types see the Record Types page.
Keeper Notation
Get Value
Example Usage
Notation.getValue(secret, "<query>");
// Query example "<RECORD UID>/field/login"
import static com.keepersecurity.secretsManager.core.SecretsManager.*
import static com.keepersecurity.secretsManager.core.Notation.*;
...
​
// get secrets
KeeperSecrets secrets = getSecrets(options);
​
// get login with dot notation
String login = getValue(secrets, "BediNKCMG21ztm5xGYgNww/field/login");
See Keeper Notation documentation to learn about Keeper Notation format and capabilities
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
Get TOTP Code
Example Usage
TotpCode.uriToTotpCode(url)
import static com.keepersecurity.secretsManager.core.Notation.*;
import static com.keepersecurity.secretsManager.core.TotpCode.*;
​
...
​
// 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
Update Secret
Update Secret
Example Usage
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.*;
​
...
​
// 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
updateSecret(options, recordToUpdate); 
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
Update Password
Example Usage
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
Set Value
Example Usage
//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);
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 Record Types documentation for a list of field types.
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
Generate Password
Example Usage
generatePassword(length: int, lowercase: int, uppercase: int, digits: int, specialCharacters: int)
import com.keepersecurity.secretsManager.core.CryptoUtils;
​
// 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
Download File
Example Usage
SecretsManager.downloadFile(file): ByteArray
import static com.keepersecurity.secretsManager.core.SecretsManager;
import com.keepersecurity.secretsManager.core.KeeperRecord;
import com.keepersecurity.secretsManager.core.KeeperFile;
​
// 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
Download Thumbnail
Example Usage
SecretsManager.downloadThumbnail(file): ByteArray
import static com.keepersecurity.secretsManager.core.SecretsManager;
import com.keepersecurity.secretsManager.core.KeeperRecord;
import com.keepersecurity.secretsManager.core.KeeperFile;
​
// 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){
        // 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
See the documentation for expected field formats for each record type
TOTP fields accept only URL generated outside of the KSM SDK
After record creation, you can upload file attachments using uploadFile​
Create a Record
Login Record Example
Custom Type Example
SecretsManager.createSecret(options, folderUid, newRecordData, secrets);
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("[email protected]")),
                // OR new Login("[email protected]")
​
                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
Parameter	Type	Required	Default	Description
`storage`	`KeyValueStorage`	Yes
`clientKey`	String	Optional	null
`hostName`	String	Optional	null
Parameter	Type	Required	Default
length	`int`	Optional	64
lowercase	`int`	Optional	0
uppercase	`int`	Optional	0
digits	`int`	Optional	0
specialCharacters	`int`	Optional	0
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
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
Java/Kotlin SDK

Download and Installation

Install With Maven or Gradle

Source Code

Using the SDK

Initialize Storage

Example Usage

Retrieve Secrets

Retrieve Secrets by Title

Retrieve Values From a Secret

Retrieve a Password

Retrieve Fields

Get TOTP Code

​

Update Values in a Secret

Generate a Random Password

Download a File

Download a Thumbnail

Upload a File

Create a Secret

Prerequisites:
