JavaScript SDK

Detailed Javascript SDK docs for Keeper Secrets Manager

Download and Installation

Install with NPM

npm install @keeper-security/secrets-manager-core

For more information, see https://www.npmjs.com/package/@keeper-security/secrets-manager-core

Source Code

Find the JavaScript 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		storage location
clientKey	string	Optional	null	token for connecting with Keeper Secrets Manager
hostName	string	Optional	null	server location to get secrets. If nothing is passed, will use keepersecurity.com (US)

Example Usage

const { getSecrets, initializeStorage, localConfigStorage } = require('@keeper-security/secrets-manager-core')

const getKeeperRecords = async () => {

    // oneTimeToken is used only once to initialize the storage
    // after the first run, subsequent calls will use ksm-config.txt
    const oneTimeToken = "<One Time Access Token>";
    
    const storage = localConfigStorage("ksm-config.json")
    
    await initializeStorage(storage, oneTimeToken)
    // Using token only to generate a config (for later usage)
    // requires at least one access operation to bind the token
    //await getSecrets({storage: storage})
    
    const {records} = await getSecrets({storage: storage})
    console.log(records)

    const firstRecord = records[0]
    const firstRecordPassword = firstRecord.data.fields.find(x => x.type === 'password')
    console.log(firstRecordPassword.value[0])
}

getKeeperRecords().finally()

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 { getSecrets, localConfigStorage } from '@keeper-security/secrets-manager-core';

// First run: config file contains the one-time token (generated by `ksm init`).
const storage = localConfigStorage('ksm-config.json');
const { records } = await getSecrets({ storage });
// Token is redeemed on this call; ksm-config.json is updated with bound credentials.

// Subsequent runs: no changes needed — storage holds the bound credentials.
const { records: records2 } = await getSecrets({ storage });

Retrieve Secrets

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

Parameter	Type	Required	Default	Description
storage	KeyValueStorage	Yes		Storage location
recordsFilter	string[]	Optional	Empty List	Record UIDs to get

Response

Type: KeeperSecrets

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

Example Usage

Retrieve all Secrets

const storage = inMemoryStorage() // see initialization example
const secrets = await getSecrets({storage: storage})

Retrieve Secrets by Title

// get all matching records
getSecretsByTitle = async (options: SecretManagerOptions, recordTitle: string): Promise<KeeperRecord[]>

// get only the first matching record
getSecretByTitle = async (options: SecretManagerOptions, recordTitle: string): Promise<KeeperRecord>

Parameter	Type	Required	Description
options	SecretsManagerOptions	Yes	Preconfigured options
recordTitle	string	Yes	Record title to search for

Example Usage

const {
    getSecretByTitle,
    localConfigStorage,
} = require('@keeper-security/secrets-manager-core')

const getKeeperRecord = async () => {
    const options = { storage: localConfigStorage("ksm-config.json") }
    const myCredential = await getSecretByTitle(options, "My Credential")
}

getKeeperRecord().finally()

Retrieve Values From a Secret

Retrieve a Password

Get Password

secret.data.fields.find(x => x.type === 'password')

Example Usage

Field types are based on the Keeper Record Type. For a detailed list of available fields based on the Keeper Record Type, see the record-type-info command in Keeper Commander.

Retrieve other Fields with Keeper Notation

Get Value

getValue(secrets: KeeperSecrets, query: string): any

Example Usage

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

Parameter	Type	Required	Default	Description
secrets	KeeperSecrets	Yes		Secrets to query
query	string	Yes		Keeper Notation query

Returns

Type: any

The value of the field at the location specified by the dot notation query if any, otherwise undefined.

Retrieve a TOTP Code

Get TOTP Code

getTotpCode(
    url: string,
    unixTimeSeconds?: number
): Promise<{
    code: string
    timeLeft: number
    period: number
} | null>

Example

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

Parameter	Type	Required	Default	Description
url	string	Yes		TOTP Url
unixTimeSeconds	number	Optional	Current timestamp	Unix timestamp in seconds (for testing/verification)

* The record UID in the notation query must be for a secret passed in the secrets parameter or nothing will be found by the query

Returns

Type: Promise<{code: string, timeLeft: number, period: number} | null>

An object containing:

• code - The TOTP code (6-8 digits)

• timeLeft - Seconds remaining until code expires

• period - TOTP period in seconds (typically 30)

Returns null if the TOTP URL is invalid or cannot be processed.

PAM Record Types

Use record.data.type to identify PAM records.

for (const record of records) {
    switch (record.data.type) {
        case 'pamMachine':
            // access host field
            break;
        case 'pamUser':
            // access login field
            break;
        case 'pamDatabase':
            // access databaseType field
            break;
    }
}

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 pamUser records included.

Use getLinks(record) to get typed KeeperRecordLink objects with permission, data, and settings accessors. The raw record.links array is also still available.

import { getSecrets2, getLinks } from '@keeper-security/secrets-manager-core';

const { records } = await getSecrets2({ storage }, { requestLinks: true });

for (const record of records) {
    for (const link of getLinks(record)) {
        console.log(`linked UID: ${link.recordUid}, path: ${link.path ?? ''}`);

        // permission accessors (non-throwing booleans)
        if (link.allowsRotation() && link.allowsConnections()) {
            // ...
        }

        // settings accessors: returns null when not present or decryption fails
        const aiSettings = await link.getAiSettingsData();
        if (aiSettings !== null) {
            // use aiSettings
        }
    }
}

getLinks(record) returns an empty array when links were not requested or none exist. For the full cross-SDK reference, see Linked Credentials.

Update 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, record)

Example Usage

Transactional updates

Parameter	Type	Required	Default	Description
options	SecretManagerOptions	Yes
record	KeeperRecord	Yes

Returns

Type: Promise<void>

Generate a Random Password

Generate Password

generatePassword(length, lowercase, uppercase, digits, specialCharacters)

Example Usage

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.

Returns

Type: String

Download a File

downloadFile(file: KeeperFile): ByteArray

Parameter	Type	Required	Default	Description
file	KeeperFile	Yes		File to download

Response

Type: Promise<Uint8Array

Bytes of file for download

Download a Thumbnail

downloadThumbnail(file: KeeperFile): ByteArray

Parameter	Type	Required	Default	Description
file	KeeperFile	Yes		File with thumbnail to download

Response

Type: Promise<Uint8Array>

Bytes of thumbnail for download

Upload a File

Upload File:

uploadFile = async (options: SecretManagerOptions, ownerRecord: KeeperRecord, file: KeeperFileUpload): Promise<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:

type KeeperFileUpload = {
    name: string
    title: string
    type?: string
    data: Uint8Array
}

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	Uint8Array	Yes	File data as bytes

Example Usage

// get record to attach file to
const {records} = await getSecrets({storage: storage}, ['XXX'])
const ownerRecord = records[0]

// get file data to upload
const fileData = fs.readFileSync('./assets/my-file.json')

// upload file to selected record
await uploadFile(options, ownerRecord, {
    name: 'my-file.json',
    title: 'Sample File',
    type: 'application/json',
    data: fileData
})

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

createSecret(options, folderUid, record)

Parameter	Type	Required	Default
options	SecretManagerOptions	Yes
folderUid	string	Yes
record	JSON Object	Yes

Create Record in Sub-folder

Login Record Example

Custom Type Example

Delete a Secret

The JavaScript KSM SDK can delete records in the Keeper Vault.

Delete Secret

deleteSecret(smOptions, recordUids);

Parameter	Type	Required
smOptions	SecretManagerOptions	Yes
recordUids	string[]	Yes

Example

Caching

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

Add queryFunction: cachingPostFunction to SecretManagerOptions

Example usage:

const options: SecretManagerOptions = {    
    storage: kvs,
    queryFunction: cachingPostFunction // Import `cachingPostFunction`
}

Browser Secure Storage

In the browser, secureStorage(dbName) provides a storage backend that encrypts KSM credentials at rest in IndexedDB using a non-extractable AES-256-GCM key. The key is generated in the browser and can never be exported, so stored credentials are never held in extractable form.

secureStorage is asynchronous, await it to get the storage instance. It is available only in the browser build. Importing it outside a browser bundle (Node.js, SSR) yields undefined. It is not present in the node entry point.

import { secureStorage, getSecrets, initializeStorage } from '@keeper-security/secrets-manager-core'

const storage = await secureStorage('ksm-secure')

await initializeStorage(storage, '<One Time Access Token>')
const { records } = await getSecrets({ storage })

Folders

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

Read Folders

Downloads full folder hierarchy.

getFolders = async (options: SecretManagerOptions): Promise<KeeperFolder[]>

Response

Type: KeeperFolder[]

Example Usage

const storage = localConfigStorage("ksm-config.json")
const folders = await getFolders({storage: storage})

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 = async (options: SecretManagerOptions, createOptions: CreateOptions, folderName: string): Promise<string>

Parameter	Type	Required	Description
options	SecretsManagerOptions	Yes	Preconfigured options
createOptions	CreateOptions	Yes	The parent and sub-folder UIDs
folderName	string	Yes	The Folder name

type CreateOptions = {
    folderUid: string
    subFolderUid?: string
}

Example Usage

const storage = localConfigStorage("ksm-config.json")
const folderUid = await createFolder({storage: storage}, {folderUid: "[PARENT_SHARED_FOLDER_UID]"}, "new_folder")

Update a Folder

Updates the folder metadata - currently folder name only.

updateFolder = async (options: SecretManagerOptions, folderUid: string, folderName: string): Promise<void>

Parameter	Type	Required	Description
options	SecretsManagerOptions	Yes	Preconfigured options
folderUid	string	Yes	The folder UID
folderName	string	Yes	The new folder name

Example Usage

const storage = localConfigStorage("ksm-config.json")
await updateFolder({storage: storage}, "[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 = async (options: SecretManagerOptions, folderUids: string[], forceDeletion?: boolean): Promise<SecretsManagerDeleteResponse>

Parameter	Type	Required	Default	Description
options	SecretsManagerOptions	Yes		Preconfigured options
folderUids	string[]	Yes		The folder UID list
forceDeletion	bool	No	false	Force deletion of non-empty folders

Example Usage

const storage = localConfigStorage("ksm-config.json")
await deleteFolder({storage: storage}, ["[FOLDER_UID1]", "[FOLDER_UID2]"], true)

Custom Server Public Key

For isolated or private deployments where the server's public key is not provisioned with the SDK, you can supply it yourself. Set serverPublicKey (and optionally serverPublicKeyId) on the options object passed to getSecrets:

const options = {
    storage: localConfigStorage("ksm-config.json"),
    serverPublicKey: "<base64-encoded server public key>",
    serverPublicKeyId: "<key id>"
}

const { records } = await getSecrets(options)

The same serverPublicKey / serverPublicKeyId values may instead be stored as fields in the configuration. While a custom server public key is configured, the SDK keeps using it and ignores server-pushed key-rotation hints. If the server rejects the configured key, getSecrets throws a plain Error (not KeeperError; see Error Handling) with the rejection reason in e.message. Wrap the call to surface the mismatch explicitly:

try {
    const { records } = await getSecrets(options)
} catch (e) {
    // key was rejected by the server — update serverPublicKey / serverPublicKeyId
    throw e
}

Proxy Support

In order to use proxy, you need to install and set a proxy agent using setCustomProxyAgent from @keeper-security/secrets-manager-core

Example Usage

const {
    getSecrets,
    initializeStorage,
    localConfigStorage,
    setCustomProxyAgent
} = require('@keeper-security/secrets-manager-core')
const { HttpsProxyAgent } = require('https-proxy-agent')

const getKeeperRecords = async () => {
    // Set you proxy URL
    setCustomProxyAgent(new HttpsProxyAgent('http://user:password@127.0.0.1:3128'))

    const storage = localConfigStorage("config.json")
    
    await initializeStorage(storage, 'US:EXAMPLE_ONE_TIME_TOKEN', 'keepersecurity.com')
    const {records} = await getSecrets({storage: storage})

    console.log(records)
}

setCustomProxyAgent works only in NodeJs environment and is not supported in browser.

Error Handling

The SDK exports a KeeperError base class for the errors it raises. Catch it to distinguish SDK-originated errors from unexpected runtime failures. KeeperError extends the built-in Error, so existing instanceof Error handling continues to work.

const { getSecrets, localConfigStorage, KeeperError, KeeperThrottleError } = require('@keeper-security/secrets-manager-core')

try {
    const { records } = await getSecrets({ storage: localConfigStorage("ksm-config.json") })
} catch (e) {
    if (e instanceof KeeperThrottleError) {
        // request was throttled and automatic retries were exhausted
    } else if (e instanceof KeeperError) {
        // base class for SDK-raised errors; check e.message for details
    } else {
        throw e
    }
}

In v17.5.0, KeeperThrottleError is the only error the SDK raises through the KeeperError hierarchy. Configuration and setup errors (missing fields, bad token, etc.) throw plain Error — they are caught by the else branch above, not instanceof KeeperError.

When the Keeper backend throttles a request (HTTP 403), the SDK automatically retries up to 5 times. When the server includes a retry_after value, the SDK uses that delay; otherwise it falls back to exponential backoff (~11, 22, 44, 88, and 176 seconds, each with jitter). If all retries are exhausted, it throws KeeperThrottleError. No caller changes are required to benefit from the automatic retry.