Java/Kotlin SDK

Detailed Java and Kotlin SDK docs for Keeper Secrets Manager

Download and Installation

Install With Maven or Gradle

build.gradle

repositories {
    mavenCentral()
}

dependencies {
    implementation 'com.keepersecurity.secrets-manager:core:17.2.0+'
    implementation("org.bouncycastle:bc-fips:2.1.1")
}

pom.xml

<dependency>
    <groupId>com.keepersecurity.secrets-manager</groupId>
    <artifactId>core</artifactId>
    <version>[17.2.0,)</version>
</dependency>
<dependency>
    <groupId>org.bouncycastle</groupId>
    <artifactId>bc-fips</artifactId>
    <version>2.1.1</version>
</dependency>

For more information, see https://central.sonatype.com/artifact/com.keepersecurity.secrets-manager/core

Cryptographic Provider Note: The Keeper Secrets Manager SDK does not require BouncyCastle. You can use:

BouncyCastle FIPS (bc-fips:2.1.1 - as in the installation instructions above)
Java's default crypto provider
Any JCE-compatible cryptographic provider

The examples in this documentation use BouncyCastle FIPS for demonstration purposes.

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 example on how to use a custom security provider.

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, oneTimeToken: String, hostName: String? = null)

Parameter

Type

Required

Default

Description

storage

KeyValueStorage

Yes

Storage Implementation

oneTimeToken

String

Yes

One-time access token

hostName

String

Optional

null

Custom hostname

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());
 }

Binding Lifecycle

The one-time token is redeemed on the first getSecrets() 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.

import com.keepersecurity.secretsManager.core.*

// First run: storage file contains the one-time token.
val storage = LocalConfigStorage("ksm-config.json")
val options = SecretsManagerOptions(storage)
val secrets = SecretsManager.getSecrets(options)
// Token is redeemed here; ksm-config.json is updated with bound credentials.

// Subsequent runs: no changes needed — storage holds the bound credentials.
val secrets2 = SecretsManager.getSecrets(options)

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);

            // get all secrets first
            KeeperSecrets secrets = SecretsManager.getSecrets(options);

            // title of the record to fetch
            String recordTitle = "My Credentials";

            // search for record by title
            KeeperRecord myCredentials = secrets.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
KeeperRecord firstRecord = secrets.getRecords().get(0);

//get the password from the first record
String password = firstRecord.getPassword();
System.out.println("Password: " + password);

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)

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

Notation.getValue(secrets, "<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");

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

Parameter

Type

Required

Description

secrets

KeeperSecrets

Yes

Secrets collection to resolve the notation against

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

Description

url

String

Yes

TOTP Url

PAM Record Types

Use record.getType() to identify PAM records.

for (record in secrets.records) {
    when (record.getType()) {
        "pamMachine"  -> { /* host field available */ }
        "pamUser"     -> { /* login field available */ }
        "pamDatabase" -> { /* databaseType field available */ }
    }
}

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

Linked Credentials

Pass requestLinks = true in QueryOptions to retrieve PAM resource records with their linked credentials included. Each link is a KeeperRecordLink exposing typed accessors for the target record UID and the link's privileges and permitted operations (isAdminUser(), isLaunchCredential(), allowsRotation(), allowsConnections(), …). See Linked Credentials on PAM Records for the full reference.

val queryOptions = QueryOptions(requestLinks = true)
val secrets = SecretsManager.getSecrets2(options, queryOptions)

for (record in secrets.records) {
    // links is null when requestLinks was not set, empty when set but none exist
    record.links?.forEach { link ->
        println("link -> ${link.recordUid} (admin=${link.isAdminUser()}, launch=${link.isLaunchCredential()})")
    }
}

QueryOptions Parameters

Parameter

Type

Required

Default

Description

recordsFilter

List<String>

Empty

Filter by record UIDs

foldersFilter

List<String>

Empty

Filter by folder UIDs

requestLinks

Boolean?

null

Set to true to retrieve links; null/false returns no links

For the cross-SDK overview of the linked credentials workflow, see Linked Credentials.

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.

KeeperRecord.isEditable reflects the write permission set on the Secrets Manager application's share. Check it before calling updateSecret if you want to detect read-only records before attempting a write. The SDK does not enforce this field — a write to a read-only record fails at the server.

Parameter

Type

Required

Description

options

SecretsManagerOptions

Yes

Storage and query configuration

recordToUpdate

KeeperRecord

Yes

Record to update

transactionType

UpdateTransactionType

Set to start a two-phase update; complete it with completeTransaction

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

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);

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

generatePassword(
    minLength: Int = 32,
    lowercase: Int? = null,
    uppercase: Int? = null,
    digits: Int? = null,
    specialCharacters: Int? = null,
    specialCharacterSet: String = "\"!@#$%()+;<>=?[]{}^.,"
)

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

Description

minLength

Int

Optional

Minimum total length of the generated password

lowercase

Int

Optional

null

Minimum lowercase letters (treated as an exact count if 0 or negative)

uppercase

Int

Optional

null

Minimum uppercase letters (treated as an exact count if 0 or negative)

digits

Int

Optional

null

Minimum digits (treated as an exact count if 0 or negative)

specialCharacters

Int

Optional

null

Minimum special characters (treated as an exact count if 0 or negative)

specialCharacterSet

String

Optional

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

Custom set of special characters to draw from

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

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

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());
        }
    }
}

Remove Files from a Record

SDK Version Required: 17.1.1 or higher

This feature add the ability to remove file attachments from records using the UpdateOptions class with the linksToRemove parameter.

Prerequisites:

Record UID or KeeperRecord object containing files
File UIDs of the files to be removed
Files must exist on the record to be removed

Parameter

Type

Required

Description

options

SecretsManagerOptions

Yes

Preconfigured options

record

KeeperRecord

Yes

The record to update

updateOptions

UpdateOptions

Yes

Options containing files to remove

Parameter

Type

Required

Default

Description

transactionType

UpdateTransactionType

null

Transaction type for batch operations

linksToRemove

List<String>

Yes

List of file UIDs to remove

// Remove files that start with "teamp_"
List<String> filesToRemove = new ArrayList<>();
for (KeeperFile file : record.getFiles()) {
    if (file.getData().getTitle().startsWith("temp_")) {
        filesToRemove.add(file.getFileUid());
    }
}

if (!filesToRemove.isEmpty()) {
    UpdateOptions updateOptions = new UpdateOptions(null, filesToRemove);
    SecretsManager.updateSecretWithOptions(options, record, updateOptions);
}

// Remove files that start with "teamp_"
val filesToRemove = record.files
    ?.filter { it.data?.title?.startsWith("temp_") == true }
    ?.map { it.fileUid }
    ?: emptyList()

if (filesToRemove.isNotEmpty()) {
    updateSecretWithOptions(
        options,
        record,
        UpdateOptions(linksToRemove = filesToRemove)
    )
}

Full Example Usage:

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

// Get record with files
QueryOptions queryOptions = new QueryOptions(
    Arrays.asList(recordUid),
    Collections.emptyList(),
    true  // request files
);

KeeperSecrets secrets = SecretsManager.getSecrets2(options, queryOptions);
KeeperRecord record = secrets.getRecords().get(0);

// Remove specific files
List<String> fileUidsToRemove = Arrays.asList("fileUid1", "fileUid2");

UpdateOptions updateOptions = new UpdateOptions(
    null,              // transactionType
    fileUidsToRemove  // linksToRemove
);

SecretsManager.updateSecretWithOptions(options, record, updateOptions);

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

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 serverCredentials record — a server login with host, username, and password.

Replace <FOLDER UID> with the UID of a shared folder your Secrets Manager Application has access to.

import com.keepersecurity.secretsManager.core.*;

KeeperRecordData newRecordData = new KeeperRecordData(
        "prod-ssh-server",
        "serverCredentials",
        Arrays.asList(
                new Hosts(new Host("prod.example.com", "22")),
                new Login("admin"),
                new Password(CryptoUtils.generatePassword())
        )
);

String recordUid = SecretsManager.createSecret(options, "<FOLDER UID>", newRecordData);

databaseCredentials Example

This example creates a databaseCredentials record — a database login with connection details.

Replace <FOLDER UID> with the UID of a shared folder your Secrets Manager Application has access to.

import com.keepersecurity.secretsManager.core.*;

KeeperRecordData dbRecordData = new KeeperRecordData(
        "prod-mysql",
        "databaseCredentials",
        Arrays.asList(
                new Text("MySQL"),
                new Hosts(new Host("db.example.com", "3306")),
                new Login("db_admin"),
                new Password(CryptoUtils.generatePassword())
        )
);

String recordUid = SecretsManager.createSecret(options, "<FOLDER UID>", dbRecordData);

sshKeys Example

This example creates an sshKeys record — an SSH key pair with host and login.

Replace <FOLDER UID> with the UID of a shared folder your Secrets Manager Application has access to.

import com.keepersecurity.secretsManager.core.*;

KeeperRecordData sshRecordData = new KeeperRecordData(
        "prod-ssh-key",
        "sshKeys",
        Arrays.asList(
                new Login("admin"),
                new KeyPairs(new KeyPair("<PUBLIC KEY>", "<PRIVATE KEY>")),
                new Hosts(new Host("prod.example.com", "22"))
        )
);

String recordUid = SecretsManager.createSecret(options, "<FOLDER UID>", sshRecordData);

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<String>

Yes

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

// delete a specific secret by record UID
SecretsManager.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>

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>

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 folder UIDs missing from the vault or not shared with the KSM Application do not throw an exception. Check responseCode on each entry in the returned SecretsManagerDeleteFolderResponse.folders list to detect a per-folder failure.

SecretsManagerDeleteFolderResponse deleteFolder(SecretsManagerOptions options, List<String> folderUids, boolean forceDeletion)

Response

Type: SecretsManagerDeleteFolderResponse

public class SecretsManagerDeleteFolderResponse {
    public List<SecretsManagerDeleteFolderResponseRecord> folders;
}

public class SecretsManagerDeleteFolderResponseRecord {
    public String errorMessage;   // null on success, set on per-item failure
    public String folderUid;
    public String responseCode;   // "ok" on success
}

Parameter

Type

Required

Default

Description

options

SecretsManagerOptions

Yes

Preconfigured options

folderUids

List<String>

Yes

The folder UID list

forceDeletion

Boolean

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);

Record Field Classes

Each record field type is represented by a class. Cast the field to the corresponding class to access the field's value. See the Record Types documentation for a list of field types.

List<KeeperRecordField> fields = record.getData().getFields();
for (KeeperRecordField field : fields) {
    if (field instanceof Login) {
        Login loginField = (Login) field;
        String loginValue = loginField.getValue().get(0);
    } else if (field instanceof Password) {
        Password passwordField = (Password) field;
        String passwordValue = passwordField.getValue().get(0);
    }
}

Proxy Support

To route SDK traffic through an HTTP or HTTPS proxy, set proxyUrl on SecretsManagerOptions.

Java — static factory (recommended):

SecretsManagerOptions options = SecretsManagerOptions.withProxy(
    storage, "http://proxy.local:8080");

Kotlin — named parameter:

val options = SecretsManagerOptions(storage, proxyUrl = "http://proxy.local:8080")

Authenticated proxies use the http://user:password@host:port URL form. Percent-encode reserved characters in the password (for example, p%40ss for p@ss).

Authenticated Proxies and the JVM Flag

Java disables Basic authentication over HTTPS CONNECT tunnels by default. The SDK clears this restriction automatically when proxy credentials are detected, but only if no other HTTP or HTTPS connection has loaded HttpURLConnection before the SDK's first call — which application servers and frameworks nearly always do first.

If you use an authenticated proxy, set this JVM flag before your application makes any other HTTP or HTTPS call:

-Djdk.http.auth.tunneling.disabledSchemes=

Pass it on the command line or via JDK_JAVA_OPTIONS (Java 9+). If the flag is not set in time, the SDK throws a SecretsManagerException naming this remedy rather than a bare 407 error.

Ambient Proxy Settings

When proxyUrl is not set, the SDK reads JVM system properties (https.proxyHost/https.proxyPort) and then the HTTPS_PROXY/https_proxy environment variables. NO_PROXY/no_proxy and http.nonProxyHosts exclusions are honored.

Starting in 17.4.0, the SDK honors ambient proxy settings that it previously ignored. If your environment sets HTTPS_PROXY or https.proxyHost for other tools, verify those values before upgrading.

Connection and Read Timeouts

SecretsManagerOptions exposes connectTimeoutMillis (default 5,000 ms) and readTimeoutMillis (default 30,000 ms). A stalled server raises SocketTimeoutException rather than hanging indefinitely. Use Kotlin named parameters to set only the values you need:

val options = SecretsManagerOptions(
    storage,
    connectTimeoutMillis = 10_000,
    readTimeoutMillis = 60_000
)

PreviousPython SDK

NextRecord Field Classes

Last updated 20 days ago