Detailed Javascript SDK docs for Keeper Secrets Manager
npm install @keeper-security/secrets-manager-core
Find the JavaScript source code in the GitHub repository
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)
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()
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)
// 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>
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 a Password
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
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')
}
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
Type: any
The value of the field at the location specified by the dot notation query if any, otherwise undefined.
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)
}
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
Type: any
The value of the field at the location specified by the dot notation query if any, otherwise undefined.
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.
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 and notes
recordToUpdate.data.title = 'New Title'
recordToUpdate.data.notes = "New Notes"
// save record changes
await updateSecret(options, recordToUpdate)
const {
getSecrets,
localConfigStorage,
updateSecret,
completeTransaction,
UpdateTransactionType,
SecretManagerOptions
} = require('@keeper-security/secrets-manager-core')
// get records
const options = { storage: localConfigStorage("ksm-config.json") }
const {records} = await getSecrets(options)
// rotate password on the first record
const secret = records[0]
const password = secret.data.fields.find(x => x.type === "password")
password.value[0] = "MyNewPassword"
//start a transaction to update record in vault
await updateSecret(options, secret, UpdateTransactionType.Rotation)
// rotate password on remote host
const success = rotateRemoteSshPassword("MyNewPassword");
// complete the transaction - commit or rollback
const rollback = !success
await completeTransaction(options, secret.recordUid, rollback)
Parameter
Type
Required
Default
Description
options
SecretManagerOptions
Yes
record
KeeperRecord
Yes
Returns
Type: Promise<void>
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)
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.
Type: String
downloadFile(file: KeeperFile): ByteArray
Parameter
Type
Required
Default
Description
file
KeeperFile
Yes
File to download
Response
Type: Promise<Uint8Array
Bytes of file for download
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 File:
uploadFile = async (options: SecretManagerOptions, ownerRecord: KeeperRecord, file: KeeperFileUpload): Promise<string>
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
}
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
})
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
createSecret(options, folderUid, record)
options
SecretManagerOptions
Yes
folderUid
string
Yes
record
JSON Object
Yes
createSecret2(options, createOptions, record)
options
SecretManagerOptions
Yes
createOptions
CreateOptions
Yes
record
JSON Object
Yes
This example creates a login type record with a login value and a generated password.
let newRec = {
"title": "Sample KSM Record: JavaScript",
"type": "login",
"fields": [
{ "type": "login", "value": [ "username@email.com" ] },
{ "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.
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": [ "login@email.com" ],
"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:alice@google.com?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)
The JavaScript KSM SDK can delete records in the Keeper Vault.
deleteSecret(smOptions, recordUids);
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"]);
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 have full CRUD support - create, read, update and delete operations.
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})
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>
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")
Updates the folder metadata - currently folder name only.
updateFolder = async (options: SecretManagerOptions, folderUid: string, folderName: string): Promise<void>
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")
Removes a list of folders. Use forceDeletion
flag to remove non-empty folders.
deleteFolder = async (options: SecretManagerOptions, folderUids: string[], forceDeletion?: boolean): Promise<SecretsManagerDeleteResponse>
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)