> For the complete documentation index, see [llms.txt](https://docs.keeper.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.keeper.io/keeperpam/secrets-manager/developer-sdk-library/javascript-sdk.md).

# JavaScript SDK

Detailed Javascript SDK docs for Keeper Secrets Manager

## Download and Installation

### **Install with NPM**

```bash
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](https://github.com/Keeper-Security/secrets-manager/tree/master/sdk/javascript)

## Using the SDK

### Initialize Storage

{% hint style="info" %}
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`
{% endhint %}

In order to retrieve secrets, you must first initialize the local storage on your machine.

```javascript
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**

```javascript
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](/keeperpam/secrets-manager/about/secrets-manager-configuration.md#binding-lifecycle).

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

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

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

### Retrieve Secrets by Title

```javascript
// 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>
```

<table><thead><tr><th width="178.10385756676556">Parameter</th><th width="150">Type</th><th width="150">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>options</code></td><td>SecretsManagerOptions</td><td>Yes</td><td>Preconfigured options</td></tr><tr><td><code>recordTitle</code></td><td>string</td><td>Yes</td><td>Record title to search for</td></tr></tbody></table>

**Example Usage**

```javascript
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**

{% tabs %}
{% tab title="Get Password" %}

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

{% endtab %}

{% tab title="Example Usage" %}

```javascript
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')
}
```

{% endtab %}
{% endtabs %}

Field types are based on the Keeper [Record Type](/enterprise-guide/record-types.md). For a detailed list of available fields based on the Keeper Record Type, see the [record-type-info](/keeperpam/commander-cli/command-reference/record-commands/record-type-commands.md) command in Keeper Commander.

**Retrieve other Fields with Keeper Notation**

{% tabs %}
{% tab title="Get Value" %}

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

{% endtab %}

{% tab title="Example Usage" %}

```javascript
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')
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
See [Keeper Notation documentation](/keeperpam/secrets-manager/about/keeper-notation.md) to learn about Keeper Notation format and capabilities
{% endhint %}

| 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**

{% tabs %}
{% tab title="Get TOTP Code" %}

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

{% endtab %}

{% tab title="Example" %}

```javascript
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 TOTP URI from record using notation
    const totpUri = getValue(secrets, 'RECORD_UID/field/oneTimeCode')

    // get TOTP code
    const totpResult = await getTotpCode(totpUri)

    if (totpResult) {
        console.log(`TOTP Code: ${totpResult.code}`)
        console.log(`Expires in: ${totpResult.timeLeft} seconds`)
        console.log(`Period: ${totpResult.period} seconds`)
    } else {
        console.log('Invalid TOTP URL')
    }
}

getKeeperRecords().finally()
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
See [Keeper Notation documentation](/keeperpam/secrets-manager/about/keeper-notation.md) to learn about Keeper Notation format and capabilities
{% endhint %}

| 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.

```typescript
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](/keeperpam/secrets-manager/about/pam-record-types.md).

### 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.

```typescript
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](/keeperpam/secrets-manager/about/linked-credentials.md).

### Update a Secret

{% hint style="warning" %}
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.
{% endhint %}

{% tabs %}
{% tab title="Update Secret" %}

```javascript
updateSecret(options, record)
```

{% endtab %}

{% tab title="Example Usage" %}

<pre class="language-javascript"><code class="lang-javascript"><strong>const { 
</strong>    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)
</code></pre>

{% endtab %}

{% tab title="Transactional updates" %}

<pre class="language-javascript"><code class="lang-javascript"><strong>const { 
</strong>    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)
</code></pre>

{% endtab %}
{% endtabs %}

<table data-header-hidden><thead><tr><th width="150">Parameter</th><th width="257">Type</th><th width="150">Required</th><th>Default</th><th>Description</th></tr></thead><tbody><tr><td>Parameter</td><td>Type</td><td>Required</td><td>Default</td><td>Description</td></tr><tr><td><code>options</code></td><td><code>SecretManagerOptions</code></td><td>Yes</td><td></td><td></td></tr><tr><td><code>record</code></td><td><code>KeeperRecord</code></td><td>Yes</td><td></td><td></td></tr></tbody></table>

**Returns**

**Type:** `Promise<void>`

### Generate a Random Password

{% tabs %}
{% tab title="Generate Password" %}

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

{% endtab %}

{% tab title="Example Usage" %}

```javascript
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)
```

{% endtab %}
{% endtabs %}

<table><thead><tr><th width="203.7142857142857">Parameter</th><th width="150">Type</th><th width="150">Required</th><th>Default</th></tr></thead><tbody><tr><td>length</td><td><code>int</code></td><td>Optional</td><td>64</td></tr><tr><td>lowercase</td><td><code>int</code></td><td>Optional</td><td>0</td></tr><tr><td>uppercase</td><td><code>int</code></td><td>Optional</td><td>0</td></tr><tr><td>digits</td><td><code>int</code></td><td>Optional</td><td>0</td></tr><tr><td>specialCharacters</td><td><code>int</code></td><td>Optional</td><td>0</td></tr></tbody></table>

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

```javascript
downloadFile(file: KeeperFile, timeoutMs?: number, options?: SecretManagerOptions): ByteArray
```

| Parameter   | Type                   | Required | Default | Description                                                                                    |
| ----------- | ---------------------- | -------- | ------- | ---------------------------------------------------------------------------------------------- |
| `file`      | `KeeperFile`           | Yes      |         | File to download                                                                               |
| `timeoutMs` | `number`               | Optional |         | Overrides `options.requestTimeoutMs` for this call (see [Request Timeouts](#request-timeouts)) |
| `options`   | `SecretManagerOptions` | Optional |         | Used for `options.requestTimeoutMs` when `timeoutMs` is not given                              |

**Response**

Type: `Promise<Uint8Array`

Bytes of file for download

### Download a **Thumbnail**

```javascript
downloadThumbnail(file: KeeperFile, timeoutMs?: number, options?: SecretManagerOptions): ByteArray
```

| Parameter   | Type                   | Required | Default | Description                                                                                    |
| ----------- | ---------------------- | -------- | ------- | ---------------------------------------------------------------------------------------------- |
| `file`      | `KeeperFile`           | Yes      |         | File with thumbnail to download                                                                |
| `timeoutMs` | `number`               | Optional |         | Overrides `options.requestTimeoutMs` for this call (see [Request Timeouts](#request-timeouts)) |
| `options`   | `SecretManagerOptions` | Optional |         | Used for `options.requestTimeoutMs` when `timeoutMs` is not given                              |

**Response**

Type: `Promise<Uint8Array>`

Bytes of thumbnail for download

### Upload a File

Upload File:

```javascript
uploadFile = async (options: SecretManagerOptions, ownerRecord: KeeperRecord, file: KeeperFileUpload, timeoutMs?: number): Promise<string>
```

<table><thead><tr><th width="184.14763231197773">Parameter</th><th width="246.99431983802478">Type</th><th width="150">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>options</code></td><td>SecretsManagerOptions</td><td>Yes</td><td>Storage and query configuration</td></tr><tr><td><code>ownerRecord</code></td><td>KeeperRecord</td><td>Yes</td><td>The record to attach the uploaded file to</td></tr><tr><td><code>file</code></td><td>KeeperFileUpload</td><td>Yes</td><td>The File to upload</td></tr><tr><td><code>timeoutMs</code></td><td>number</td><td>Optional</td><td>Overrides <code>options.requestTimeoutMs</code> for this call</td></tr></tbody></table>

Creating the Keeper File Upload Object:

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

<table><thead><tr><th width="169">Parameter</th><th width="150">Type</th><th width="150">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>name</code></td><td>string</td><td>Yes</td><td>What the name of the file will be in Keeper once uploaded</td></tr><tr><td><code>title</code></td><td>string</td><td>Yes</td><td>What the title of the file will be in Keeper once uploaded</td></tr><tr><td><code>type</code></td><td>string</td><td>Optional</td><td>The mime type of data in the file. 'application/octet-stream' will be used if nothing is given</td></tr><tr><td><code>data</code></td><td>Uint8Array</td><td>Yes</td><td>File data as bytes</td></tr></tbody></table>

**Example Usage**

```javascript
// 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](/enterprise-guide/record-types.md) 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](#upload-a-file)

{% tabs %}
{% tab title="Create a Record" %}

<pre class="language-javascript"><code class="lang-javascript"><strong>createSecret(options, folderUid, record)
</strong></code></pre>

<table><thead><tr><th width="166">Parameter</th><th width="226">Type</th><th>Required</th><th>Default</th></tr></thead><tbody><tr><td>options</td><td>SecretManagerOptions</td><td>Yes</td><td></td></tr><tr><td>folderUid</td><td>string</td><td>Yes</td><td></td></tr><tr><td>record</td><td>JSON Object</td><td>Yes</td><td></td></tr></tbody></table>
{% endtab %}

{% tab title="Create Record in Sub-folder" %}

<pre class="language-javascript"><code class="lang-javascript"><strong>createSecret2(options, createOptions, record)
</strong></code></pre>

<table><thead><tr><th width="166">Parameter</th><th width="226">Type</th><th>Required</th><th>Default</th></tr></thead><tbody><tr><td>options</td><td>SecretManagerOptions</td><td>Yes</td><td></td></tr><tr><td>createOptions</td><td>CreateOptions</td><td>Yes</td><td></td></tr><tr><td>record</td><td>JSON Object</td><td>Yes</td><td></td></tr></tbody></table>
{% endtab %}

{% tab title="Login Record Example" %}
This example creates a login type record with a login value and a generated password.

{% hint style="info" %}
Replace '`[FOLDER UID]`' in the example with the UID of a shared folder that your Secrets Manager has access to.
{% endhint %}

```javascript
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)
```

{% endtab %}

{% tab title="Custom Type Example" %}
This example creates a record with a custom record type.

{% hint style="info" %}
Replace '`[FOLDER UID]`' in the example with the UID of a shared folder that your Secrets Manager has access to.
{% endhint %}

```javascript
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)
```

{% endtab %}
{% endtabs %}

### Delete a Secret

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

{% tabs %}
{% tab title="Delete Secret" %}

```javascript
deleteSecret(smOptions, recordUids): Promise<SecretsManagerDeleteResponse>;
```

<table><thead><tr><th>Parameter</th><th width="250.66666666666666">Type</th><th align="center">Required</th></tr></thead><tbody><tr><td><code>smOptions</code></td><td><code>SecretManagerOptions</code></td><td align="center">Yes</td></tr><tr><td><code>recordUids</code></td><td><code>string[]</code></td><td align="center">Yes</td></tr></tbody></table>
{% endtab %}

{% tab title="Example" %}

<pre class="language-javascript"><code class="lang-javascript">// setup secrets manager
const smOptions = { storage: localConfigStorage("ksm-config.json") 

// delete a specific secret by record UID
<strong>const response = await deleteSecret(smOptions, ["EG6KdJaaLG7esRZbMnfbFA"]);
</strong></code></pre>

{% endtab %}
{% endtabs %}

**Response**

Type: `SecretsManagerDeleteResponse`

```javascript
type SecretsManagerDeleteResponse = {
    records: { recordUid: string, responseCode: string, errorMessage: string }[]
    folders: { folderUid: string, responseCode: string, errorMessage: string }[]
}
```

The call resolves even when the server rejects some of the requested UIDs. Check each item's `responseCode` — anything other than `'ok'` means that record was not deleted, with the reason in `errorMessage`. The SDK also logs a `console.error` line for each failed item, but does not throw on a partial failure. [Delete Folders](#delete-folders) returns the same response shape, in its `folders` array.

### 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.

{% hint style="warning" %}
Starting in 17.6.0, the standalone `cachingPostFunction` (Node) is replaced by `createCachingFunction(storage, options?)`. The old function stored its cache key in plaintext beside the data it protected, in a fixed path relative to the process's working directory, with no integrity check on restore. If you called `cachingPostFunction` directly, delete the old cache file in your working directory after upgrading — it is not removed automatically.
{% endhint %}

Add `queryFunction: createCachingFunction(storage)` to `SecretManagerOptions`. Reading the cache requires the same config the SDK is already using (the cache key is derived from the app key), so a stolen cache file alone is not enough to read secrets from it. The cache is authenticated: a tampered or corrupted file is rejected instead of silently trusted.

**Node — options object:**

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

const storage = localConfigStorage("ksm-config.json")
const options = {
    storage,
    queryFunction: createCachingFunction(storage, {
        cachePath: '/custom/path/ksm-cache.dat', // optional, defaults to ~/.keeper/ksm-cache.dat
        maxCacheAgeMs: 12 * 60 * 60 * 1000        // optional, defaults to 24h
    })
}
```

**Browser — positional `maxCacheAgeMs`:**

```javascript
import { createCachingFunction, localConfigStorage } from '@keeper-security/secrets-manager-core'

const storage = localConfigStorage("ksm-config.json")
const options = {
    storage,
    queryFunction: createCachingFunction(storage, 12 * 60 * 60 * 1000) // optional, defaults to 24h
}
```

{% hint style="info" %}
Node and browser take this second argument differently — an options object on Node, a plain `maxCacheAgeMs` number on the browser. There is no `cachePath` option in the browser; caching there uses IndexedDB.
{% endhint %}

On a network failure, a cached response is served if one exists and is still within the freshness window, and a warning is logged since the response may be stale. A deliberate client-side timeout ([Request Timeouts](#request-timeouts)) is never served from cache — it propagates to the caller as a real error instead of a synthetic stale success. The very first (bind) call is never cached, since caching requires an app key that the bind call itself establishes.

### 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.

```javascript
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.

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

**Response**

Type: `KeeperFolder[]`

**Example Usage**

```javascript
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.

```javascript
createFolder = async (options: SecretManagerOptions, createOptions: CreateOptions, folderName: string): Promise<string>
```

<table><thead><tr><th width="181.85161529417937">Parameter</th><th width="242.99431983802478">Type</th><th width="102">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>options</code></td><td><code>SecretsManagerOptions</code></td><td>Yes</td><td>Preconfigured options</td></tr><tr><td><code>createOptions</code></td><td><code>CreateOptions</code></td><td>Yes</td><td>The parent and sub-folder UIDs</td></tr><tr><td><code>folderName</code></td><td><code>string</code></td><td>Yes</td><td>The Folder name</td></tr></tbody></table>

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

**Example Usage**

```javascript
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.

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

<table><thead><tr><th width="154.85161529417937">Parameter</th><th width="243.99431983802478">Type</th><th width="100">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>options</code></td><td><code>SecretsManagerOptions</code></td><td>Yes</td><td>Preconfigured options</td></tr><tr><td><code>folderUid</code></td><td><code>string</code></td><td>Yes</td><td>The folder UID</td></tr><tr><td><code>folderName</code></td><td><code>string</code></td><td>Yes</td><td>The new folder name</td></tr></tbody></table>

**Example Usage**

```javascript
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.

{% hint style="info" %}
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.
{% endhint %}

{% hint style="info" %}
Any folders UIDs missing from the vault or not shared to the KSM Application will not result in error.
{% endhint %}

```javascript
deleteFolder = async (options: SecretManagerOptions, folderUids: string[], forceDeletion?: boolean): Promise<SecretsManagerDeleteResponse>
```

<table><thead><tr><th width="180.85161529417937">Parameter</th><th width="242.99431983802478">Type</th><th width="100">Required</th><th width="89">Default</th><th>Description</th></tr></thead><tbody><tr><td><code>options</code></td><td><code>SecretsManagerOptions</code></td><td>Yes</td><td></td><td>Preconfigured options</td></tr><tr><td><code>folderUids</code></td><td><code>string[]</code></td><td>Yes</td><td></td><td>The folder UID list</td></tr><tr><td><code>forceDeletion</code></td><td><code>bool</code></td><td>No</td><td><code>false</code></td><td>Force deletion of non-empty folders</td></tr></tbody></table>

**Example Usage**

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

**Response**

Same shape as [Delete a Secret](#delete-a-secret)'s response, in the `folders` array — the call resolves even when the server rejects some UIDs, so check each item's `responseCode` rather than assuming success.

### 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 `serverPublicKeyId` together on the options object passed to `getSecrets` — `serverPublicKeyId` is required whenever `serverPublicKey` is set, and must be a positive integer:

```javascript
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; as of 17.6.0, once pinned, both fields must be supplied together to change either one — supplying `serverPublicKeyId` alone no longer changes a pinned custom key's id. If the server rejects the configured key, or if `serverPublicKey`/`serverPublicKeyId` are misconfigured (missing pair, non-integer id, unsupported bundled id), `getSecrets` throws a `KeeperError` (see [Error Handling](#error-handling)) with the reason in `e.message`. Wrap the call to surface the mismatch explicitly:

```javascript
try {
    const { records } = await getSecrets(options)
} catch (e) {
    // key was rejected by the server, or serverPublicKey/serverPublicKeyId were misconfigured
    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**

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

{% hint style="danger" %}
`setCustomProxyAgent` works only in NodeJs environment and is not supported in browser.
{% endhint %}

### Request Timeouts

Set `requestTimeoutMs` on `SecretManagerOptions` to bound how long the SDK waits for a single network exchange. Defaults to 30 seconds. Applies to `getSecrets`, `updateSecret`, and every other call that goes through the main request path, as well as the [caching](#caching) fallback.

```javascript
const options = {
    storage: localConfigStorage("ksm-config.json"),
    requestTimeoutMs: 10000 // 10 seconds
}
```

`downloadFile`, `downloadThumbnail`, and `uploadFile` each also accept their own optional `timeoutMs`, which wins over `requestTimeoutMs` for that one call:

```javascript
await downloadFile(file, 60000, options) // this download gets 60s regardless of options.requestTimeoutMs
```

On timeout, the call rejects with a `KeeperError` naming the timeout that was actually applied. `requestTimeoutMs` bounds each individual attempt, not an entire call — a request retried under server-side throttling can still take longer than the configured value in total, since the wait between retries is separate and not counted against `requestTimeoutMs`; across all retries that adds up to a large but bounded amount of time (see the backoff schedule in Error Handling below).

{% hint style="info" %}
A value of `0`, a negative number, `NaN`, or `Infinity` throws a plain `Error` (not `KeeperError`) immediately, before any request is attempted.
{% endhint %}

### 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.

```javascript
const { getSecrets, localConfigStorage, KeeperError, KeeperThrottleError, KeeperStorageError, KeeperCryptoError } = 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 KeeperStorageError) {
        // failure reading or writing the local config/cache file; e.code carries the fs errno (EACCES, ENOSPC, ...) when one exists
    } else if (e instanceof KeeperCryptoError) {
        // a specific folder could not be decrypted; e.failure classifies why, e.uid identifies the item
    } else if (e instanceof KeeperError) {
        // base class for SDK-raised errors; check e.message for details
    } else {
        throw e
    }
}
```

As of 17.6.0, the SDK raises four errors through the `KeeperError` hierarchy: `KeeperThrottleError`, `KeeperStorageError`, `KeeperCryptoError`, and `KeeperError` itself for other SDK-raised failures (including a misconfigured `serverPublicKey`/`serverPublicKeyId`; see [Custom Server Public Key](#custom-server-public-key)). Caller-input validation mistakes that fail before any request is attempted — an unusable `requestTimeoutMs` (see [Request Timeouts](#request-timeouts)), for instance — still throw a plain `Error`, not `KeeperError`, since these represent a bad argument rather than a failed interaction with Keeper's backend. `KeeperStorageError` is Node-only: a storage failure in the browser (`localConfigStorage` or `secureStorage`, both backed by IndexedDB) rejects with a plain `KeeperError` instead, not this subtype. Check `instanceof KeeperError` rather than `instanceof KeeperStorageError` if the same handler needs to catch a storage failure on either platform.

To react to a decryption failure on a specific folder instead of only seeing it omitted from a partial result, pass `onDecryptionError` on `SecretManagerOptions` when calling `getFolders()`:

```javascript
const options = {
    storage: localConfigStorage("ksm-config.json"),
    onDecryptionError: (info) => {
        console.error(`Failed to decrypt ${info.uid}: ${info.failure} — ${info.message}`)
        // throw here instead to abort the call rather than return a partial result
    }
}
```

When the Keeper backend throttles a request (HTTP 403 or HTTP 429), 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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.keeper.io/keeperpam/secrets-manager/developer-sdk-library/javascript-sdk.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.