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)
// 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>
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
secret.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
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
getTotpCode(url: string): string
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
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)
Parameter
Type
Required
Default
Description
options
SecretManagerOptions
Yes
record
KeeperRecord
Yes
Returns
Type: Promise<void>
Generate a Random Password
generatePassword(length, lowercase, uppercase, digits, specialCharacters)
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>
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
})
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
createSecret(options, folderUid, record)
options
SecretManagerOptions
Yes
folderUid
string
Yes
record
JSON Object
Yes
Delete a Secret
The JavaScript KSM SDK can delete records in the Keeper Vault.
deleteSecret(smOptions, recordUids);
smOptions
SecretManagerOptions
Yes
recordUids
string[]
Yes
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>
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>
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.
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)
Last updated
Was this helpful?