Keeper Secrets Manager
Search
⌃K

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

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

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
  • After record creation, you can upload file attachments using uploadFile​
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:a[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)

Delete a Secret

The JavaScript KSM SDK can delete records in the Keeper Vault.
Delete Secret
Example
deleteSecret(smOptions, recordUids);
Parameter
Type
Required
smOptions
SecretManagerOptions
Yes
recordUids
string[]
Yes
// setup secrets manager
const smOptions = { storage: localConfigStorage("ksm-config.json")
​
// delete a specific secret by record UID
await deleteSecret(smOptions, ["EG6KdJaaLG7esRZbMnfbFA"]);

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

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