JavaScript SDK

Detailed Javascript SDK docs for Keeper Secrets Manager

Download and Installation

Install with NPM

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

Source Code

Find the JavaScript source code in the GitHub repository

Using the SDK

Initialize Storage

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

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
val secrets = getSecrets(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
Example Usage
secret.data.fields.find(x => x.type === 'password')
const { getSecrets, initializeStorage, localConfigStorage } = require('@keeper-security/secrets-manager-core')
const getKeeperRecords = async () => {
const storage = localConfigStorage("ksm-config.json")
// get records
const {records} = await getSecrets({storage: storage})
// get password from first record
const firstRecord = records[0]
const firstRecordPassword = firstRecord.data.fields.find(x => x.type === 'password')
}
Fields are found by type, for a list of field types see the Record Types documentation.
Retrieve other Fields with Keeper Notation
Get Value
Example Usage
getValue(secrets: KeeperSecrets, query: string): any
const {
getSecrets,
localConfigStorage,
getValue
} = require('@keeper-security/secrets-manager-core')
const getKeeperRecords = async () => {
const options = { storage: localConfigStorage("ksm-config.json") }
// get secrets
const secrets = await getSecrets(options)
// get login with dot notation
const loginValue = getValue(secrets, 'RECORD_UID/field/login')
}
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
* 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: 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
Example
getTotpCode(url: string): string
const {
getSecrets,
localConfigStorage,
getTotpCode,
getValue} = require('@keeper-security/secrets-manager-core')
const getKeeperRecords = async () => {
const options = { storage: localConfigStorage("ksm-config.json") }
// get secrets
const secrets = await getSecrets(options)
// get login with dot notation
const totpUri = getValue(secrets,'RECORD_UID/field/oneTimeCode')
//get TOTP code
const totp = await getTotpCode(totpUri)
}
See Keeper Notation documentation to learn about Keeper Notation format and capabilities
Parameter
Type
Required
Default
Description
url
string
Yes
TOTP Url
* 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: any
The value of the field at the location specified by the dot notation query if any, otherwise undefined.

Update a Secret

Update Secret
Example Usage
updateSecret(options, record)
const {
getSecrets,
localConfigStorage,
updateSecret} = require('@keeper-security/secrets-manager-core')
const storage = localConfigStorage("ksm-config.json")
// get records
const {records} = await getSecrets({storage: storage})
// get the first record
const recordToUpdate = records[0]
// set new record title
recordToUpdate.data.title = 'New Title'
// save record changes
await updateSecret(options, recordToUpdate)
Parameter
Type
Required
Default
Description
options
SecretManagerOptions
Yes
record
KeeperRecord
Yes
Returns
Type: Promise<void>

Generate a Random Password

Generate Password
Example Usage
generatePassword(length, lowercase, uppercase, digits, specialCharacters)
const {
getSecrets,
localConfigStorage,
updateSecret,
generatePassword } = require('@keeper-security/secrets-manager-core')
// generate a random password
let newRandomPwd = await generatePassword()
const storage = localConfigStorage("ksm-config.json")
const {records} = await getSecrets({storage: storage})
// get the first record
const recordToUpdate = records[0]
// Find the field with the type "password"
const recordToUpdatePasswordField = recordToUpdate.data.fields.find(x => x.type === 'password')
// set new value to the password field
recordToUpdatePasswordField.value[0] = newRandomPwd
await updateSecret({storage: storage}, 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.

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
Keeper Record creation with the Secrets Manager SDKs does not support File attachments at this time
Create a Record
Login Record Example
Custom Type Example
createSecret(options, folderUid, record)
Parameter
Type
Required
Default
options
SecretManagerOptions
Yes
folderUid
string
Yes
record
JSON Object
Yes
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 has access to.
let newRec = {
"title": "Sample KSM Record: JavaScript",
"type": "login",
"fields": [
{ "type": "login", "value": [ "[email protected]" ] },
{ "type": "password", "value": [ await generatePassword() ] }
],
"notes": "This is a JavaScript record creation example"
}
let recordUid = await createSecret(options, folderUid, newRec)
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 has access to.
let newRec = {
"title": "Sample Custom Type KSM Record: JavaScript",
"type": "Custom Login",
"fields": [
{
"type": "host",
"label": "My Custom Host lbl",
"value": [ {"hostName": "127.0.0.1", "port": "8080"} ],
"required": true,
"privacyScreen": false
},
{
"type": "login",
"label": "My Custom Login lbl",
"value": [ "[email protected]" ],
"required": true,
"privacyScreen": false
},
{
"type": "password",
"label": "My Custom Password lbl",
"value": [ await generatePassword() ],
"required": true,
"privacyScreen": false
},
{
"type": "url",
"label": "My Login Page",
"value": [ "http://localhost:8080/login" ],
"required": true,
"privacyScreen": false
},
{
"type": "securityQuestion",
"label": "My Question 1",
"value": [ {
"question": "What is one plus one (write just a number)",
"answer": "2"
} ],
"required": true,
"privacyScreen": false
},
{
"type": "phone",
"value": [{
"region": "US",
"number": "510-444-3333",
"ext": "2345",
"type": "Mobile"
}],
"label": "My Phone Number"
},
{
"type": "date",
"value": [ 1641934793000 ],
"label": "My Date Lbl",
"required": true,
"privacyScreen": false
},
{
"type": "name",
"value": [{
"first": "John",
"middle": "Patrick",
"last": "Smith"
}],
"label": "My Custom Name lbl",
"required": true,
"privacyScreen": false
},
{
"type": "oneTimeCode",
"label": "My TOTP",
"value": ["otpauth://totp/Example:[email protected]?secret=JBSWY3DPEHPK3PXP&issuer=Example"],
"required": true,
"privacyScreen": false
}
],
"custom": [
{
"type": "phone",
"value": [{
"region": "US",
"number": "(510) 123-3456"
}],
"label": "My Custom Phone Lbl 1"
},
{
"type": "phone",
"value": [ {
"region": "US",
"number": "510-111-3333",
"ext": "45674",
"type": "Mobile" } ],
"label": "My Custom Phone Lbl 2"
}
],
"notes": "\tThis custom type record was created\n\tvia KSM Katacoda JavaScript Example"
}
let recordUid = await createSecret(options, "[FOLDER UID]", newRec)

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`
}