.NET SDK

Detailed .Net SDK docs for Keeper Secrets Manager
Download and Installation
Prerequisites
dotnet add package Keeper.SecretsManager
Source Code
Find the .Net 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.
SecretsManagerClient.InitializeStorage(storage: KeyValueStorage, clientKey: String? = null, hostName: String? = null)
Parameter
Type
Required
Default
Description
storage
KeyValueStorage
Yes
​
​
clientKey
String
Optional
null
​
hostName
String
Optional
null
​
Example Usage
var storage = new LocalConfigStorage("ksm-config.json");
SecretsManagerClient. InitializeStorage(storage, "[One Time Access Token]");
// Using token only to generate a config (for later usage)
// requires at least one access operation to bind the token
//var options = new SecretsManagerOptions(storage);
//await SecretsManagerClient.GetSecrets(options);
Retrieve Secrets
GetSecrets(options: SecretsManagerOptions, recordsFilter: List<String> = emptyList()): KeeperSecrets
Parameter
Type
Required
Default
Description
options
SecretsManagerOptions
Yes
​
Storage and query configuration
recordsFilter
List<String>
Optional
Empty List
Record search filters
Response
Type: KeeperSecrets
Object containing all Keeper records, or records that match the given filter criteria
Example Usage
Retrieve all Secrets
var options = new SecretsManagerOptions(storage, testPostFunction);
var secrets = GetSecrets(options);
​
Retrieve Secrets by Title
// get all matching records
async Task<IEnumerable<KeeperRecord>> GetSecretsByTitle(SecretsManagerOptions options, string recordTitle)
​
// get only the first matching record
async Task<KeeperRecord> GetSecretByTitle(SecretsManagerOptions options, string recordTitle)
Parameter
Type
Required
Description
options
SecretsManagerOptions
Yes
Preconfigured options
recordTitle
string
Yes
Record title to search for
Example Usage
using System;
using System.Threading.Tasks;
using SecretsManager;
​
private static async Task getOneIndividualSecret()
{
    var storage = new LocalConfigStorage("ksm-config.json");
    var options = new SecretsManagerOptions(storage);
    var records = (await SecretsManagerClient.GetSecretsByTitle(
            options, "My Credentials")
        ).Records;
    foreach (var record in records)
    {
        Console.WriteLine(record.RecordUid + " - " + record.Data.title);
        foreach (var field in record.Data.fields)
        {
            Console.WriteLine("\t" + field.label + " (" + field.type + "): [" + String.Join(", ", field.value) + "]");
        }
    }
}
​
Retrieve Values from a Secret
Retrieve a Password
Get Password
Example Usage
secret.FieldValue("password")
var storage = new LocalConfigStorage(configName);
Console.WriteLine($"Local Config Storage opened from the file {configName}");
if (clientKey != null)
    SecretsManagerClient.InitializeStorage(storage, "<One Time Access Token>");
}
var options = new SecretsManagerOptions(storage);
//get secrets
var secrets= (await SecretsManagerClient.GetSecrets(options)).Records;
​
// get the password from the first secret
var firstSecret= secrets[0];
var password = firstSecret.FieldValue("password").ToString();
Fields are found by type, for a list of field types see the Record Types documentation.
Retrieve Other Fields Using Keeper Notation
Get Value
Example Usage
GetValue(KeeperSecrets secrets, string notation)
var storage = new LocalConfigStorage(configName);
Console.WriteLine($"Local Config Storage opened from the file {configName}");
if (clientKey != null)
    SecretsManagerClient.InitializeStorage(storage, "<One Time Access Token>");
}
var options = new SecretsManagerOptions(storage);
//get secrets
var secrets (await SecretsManagerClient.GetSecrets(options)).Records;
​
// get login field value using dot notation
var password = Notation.GetValue(secrets, "BediNKCMG21ztm5xGYgNww/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
notation
string
Yes
​
Field query in dot notation format
Retrieve TOTP Code
Get TOTP Code
Example Usage
CryptoUtils.GetTotpCode(string url)
var storage = new LocalConfigStorage(configName);
Console.WriteLine($"Local Config Storage opened from the file {configName}");
if (clientKey != null)
    SecretsManagerClient.InitializeStorage(storage, "<One Time Access Token>");
}
var options = new SecretsManagerOptions(storage);
//get secrets
var secrets (await SecretsManagerClient.GetSecrets(options)).Records;
​
// get TOTP url from a record
var url = Notation.GetValue(secrets, "BediNKCMG21ztm5xGYgNww/field/OneTimeCode");
​
// get TOTP code
var totp = CryptoUtils.GetTotpCode(url);
Console.WriteLine(totp.Code);
Parameter
Type
Required
Default
Description
url
string
Yes
​
TOTP Url
Update Values in a Secret
Save Changes to a Secret
Update Secret
Example Usage
UpdateSecret(options: SecretsManagerOptions, record: KeeperRecord);
var options = SecretsManagerOptions(storage, testPostFunction)
updateSecret(options, secret)
Parameter
Type
Required
Default
Description
options
SecretsManagerOptions
Yes
​
Storage and query configuration
Use UpdateSecret to save changes made to a secret record.  Changes will not be reflected in the Keeper Vault until UpdateSecret is performed.
Update a Field Value
Update Field Value
Example Usage
UpdateFieldValue(string fieldType, object value)
var storage = new LocalConfigStorage(configName);
Console.WriteLine($"Local Config Storage opened from the file {configName}");
if (clientKey != null)
    SecretsManagerClient.InitializeStorage(storage, "<One Time Access Token>");
}
var options = new SecretsManagerOptions(storage);
//get secrets
var secrets= (await SecretsManagerClient.GetSecrets(options)).Records;
​
// get the password from the first secret
var firstSecret= secrets[0];
​
// update the login field
firstSecret.updateFieldValue("login", "My New Login");
​
// save changes
updateSecret(options, firstSecret);
​
Parameter
Type
Required
Default
Description
fieldType
string
Yes
​
The field to update
value
object
Yes
​
Value to set the field to
Generate a Random Password
Generate Password
Example Usage
CryptoUtils.GeneratePassword(int length, lowercase int, uppercase int, digits int, specialCharacters);
// generate a random password
var password = CryptoUtils.GeneratePassword();
// update a record with the new password
firstRecord.UpdateFieldValue("password", password);
await SecretsManagerClient.UpdateSecret(options, firstRecord);
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.
Download a File
DownloadFile(file: KeeperFile): ByteArray
Parameter
Type
Required
Default
Description
file
KeeperFile
Yes
​
File to download
Response
Type: ByteArray
ByteArray 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: ByteArray
ByteArray of thumbnail for download
Upload a File
Upload File:
UploadFile(SecretsManagerOptions options, KeeperRecord ownerRecord, KeeperFileUpload file)
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:
KeeperFileUpload(string name, string title, string type, byte[] data)
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
Yes
The mime type of data in the file.  'application/octet-stream' for example
data
byte[]
Yes
File data as bytes
Example Usage
using System;
using System.Threading.Tasks;
using SecretsManager;
​
private static async Task uploadFile()
{
    // initalize storage and options
    var storage = new LocalConfigStorage("ksm-config.json");
    var options = new SecretsManagerOptions(storage);
    
    // get a record to attach the file to
    var records = (await SecretsManagerClient.GetSecrets(
            options, new[] { "XXX" })
        ).Records;
        
    var ownerRecord = records[0];
    
    // get file data to upload
    var bytes = await File.ReadAllBytesAsync("my-file.json");
    var myFile = new KeeperFileUpload(
        "my-file1.json", 
        "My File", 
        null, 
        bytes
    );
       
    // upload file to selected record                     
    await SecretsManagerClient.UploadFile(options, firstRecord, myFile);
    
}
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
SecretsManagerClient.CreateSecret(options, folderUid, record)
Parameter
Type
Required
Defaut
options
SecretsManagerOptions
Yes
​
folderUid
string
Yes
​
record
KeeperRecordData
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.
var newRecord = new KeeperRecordData{type = "login", title = "Sample KSM Record: C#"};
​
newRecord.fields = new[]
{
    new KeeperRecordField { type = "login", value = new[] { "My Username" } },
    new KeeperRecordField { type = "password", value = new[] { CryptoUtils.GeneratePassword() } },
};
newRecord.notes = "This is a C# record creation example";
​
var recordUid = await SecretsManagerClient.CreateSecret(options, folderUid, newRecord);
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.
var newRecord = new KeeperRecordData();
newRecord.type = "Custom Login";
newRecord.title = "Sample Custom Type KSM Record: C#";
newRecord.fields = new[]
{
    new KeeperRecordField { 
        type = "host", 
        value = new[] 
        {
            new Dictionary<string, string>
            {
                { "hostName", "127.0.0.1"},
                { "port", "8080"}
            }
        },
        label = "My Custom Host lbl",
        required = true
    },
    
    new KeeperRecordField { 
        type = "login", 
        value = new[] { "[email protected]" }, 
        required = true, 
        label = "My Custom Login lbl"
    },
    
    new KeeperRecordField
    {
        type = "password", 
        value = new[] { CryptoUtils.GeneratePassword() }, 
        required = true, 
        label = "My Custom Password lbl"
    },
    
    new KeeperRecordField
    {
        type = "url",
        value = new[] { "http://localhost:8080/login" },
        label = "My Login Page",
        required = true
    },
    
    new KeeperRecordField { 
        type = "securityQuestion", 
        value = new[]
        {
            new Dictionary<string, string>
            {
                {"question", "What is one plus one (write just a number)"}, 
                { "answer", "2" }
            }
        }, 
        label = "My Question 1",
        required = true
    },
    
    new KeeperRecordField { 
        type = "phone", 
        value = new[]
        {
            new Dictionary<string,string>
            {
                { "region", "US" },
                { "number", "510-444-3333" },
                { "ext", "2345" },
                { "type", "Mobile" }
            }
        }, 
        label = "My Private Phone", 
        privacyScreen = true
    },
​
    new KeeperRecordField
    {
        type = "date", 
        value = new[] {(object) 1641934793000 }, 
        label = "My Date Lbl"
    },
    
    new KeeperRecordField { 
        type = "name", 
        value = new[]
        {
            new Dictionary<string, string>
            {
                {"first", "John"},
                {"middle", "Patrick"},
                {"last", "Smith"}
            }
        },
        required = true
    },
    new KeeperRecordField
    {
        type = "oneTimeCode", 
        value = new[]
        {
            "otpauth://totp/Example:a[email protected]?secret=JBSWY3DPEHPK3PXP&issuer=Example"
        }, 
        label = "My TOTP",
        required = true
    }
};
newRecord.notes = "\tThis custom type record was created\n\tvia Python SDK copied from https://docs.keeper.io/secrets-manager/secrets-manager/developer-sdk-library/.net-sdk";
​
var recordUid = await SecretsManagerClient.CreateSecret(options, "[FOLDER_UID]", newRecord);
​
Delete a Secret
The .Net KSM SDK can delete records in the Keeper Vault.
Delete Secret
Example
DeleteSecret(smOptions, recordsUids);
Parameter
Type
Required
smOptions
SecretsManagerOptions
Yes
recordsUids
string[]
Yes
using SecretsManager;
​
// setup secrets manager
var storage = new LocalConfigStorage("ksm-config.json");
//SecretsManagerClient.InitializeStorage(storage, "<One Time Access Token>");
var smOptions = new SecretsManagerOptions(storage);
​
// delete a specific secret by record UID
await SecretsManagerClient.DeleteSecret(smOptions, new string[] {"EG6KdJaaLG7esRZbMnfbFA"});
Caching
To protect against losing access to your secrets when network access is lost, the .Net SDK allows caching of secrets to the local machine in an encrypted file.
Setup and Configure Cache
In order to setup caching in the .Net SDK, include a caching post function as the second argument when instantiating aSecretsManagerOptions object.
The .Net SDK includes a default caching function cachingPostFunction which stores cached queries to a file.
var options = new SecretsManagerOptions(storage, SecretsManagerClient.CachingPostFunction);
var secrets = await SecretsManagerClient.GetSecrets(options);
Folders
Folders have full CRUD support - create, read, update and delete operations.
Read Folders
Downloads full folder hierarchy.
Task<KeeperFolder[]> GetFolders(SecretsManagerOptions options)
Response
Type: KeeperFolder[]
Example Usage
using SecretsManager;
​
var options = new SecretsManagerOptions(new LocalConfigStorage("ksm-config.json"));
var folders = await SecretsManagerClient.GetFolders(options);
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, a 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.
Task<string> CreateFolder(SecretsManagerOptions options, CreateOptions createOptions, string folderName, KeeperFolder[] folders = null)
Parameter
Type
Required
Default
Description
options
SecretsManagerOptions
Yes
​
Preconfigured options
createOptions
CreateOptions
Yes
​
The parent and sub-folder UIDs
folderName
string
Yes
​
The Folder name
folders
KeeperFolder[]
No
null
List of folders to use in the search for parent and sub-folder from CreateOptions 
public class CreateOptions {
    public string FolderUid { get; }
    public string SubFolderUid { get; }
}
public class KeeperFolder {
        public byte[] FolderKey { get; }
        public string FolderUid { get; }
        public string ParentUid { get; }
        public string Name { get; }
}
Example Usage
using SecretsManager;
​
var options = new SecretsManagerOptions(new LocalConfigStorage("ksm-config.json"));
var co := new CreateOptions("[PARENT_SHARED_FOLDER_UID]");
var folderUid = await SecretsManagerClient.CreateFolder(options, co, "new_folder");
Update a Folder
Updates the folder metadata - currently folder name only.
Task UpdateFolder(SecretsManagerOptions options, string folderUid, string folderName, KeeperFolder[] folders = null)
Parameter
Type
Required
Default
Description
options
SecretsManagerOptions
Yes
Parameter	Type	Required	Default	Description
`storage`	`KeyValueStorage`	Yes
`clientKey`	String	Optional	null
`hostName`	String	Optional	null
Parameter	Type	Required	Description
`options`	SecretsManagerOptions	Yes	Preconfigured options
`recordTitle`	string	Yes	Record title to search for
Parameter	Type	Required	Default
length	`int`	Optional	64
lowercase	`int`	Optional	0
uppercase	`int`	Optional	0
digits	`int`	Optional	0
specialCharacters	`int`	Optional	0
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
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	Yes	The mime type of data in the file. 'application/octet-stream' for example
`data`	byte[]	Yes	File data as bytes
Parameter	Type	Required
`options`	`SecretsManagerOptions`	Yes
`folderUid`	`string`	Yes
`record`	`KeeperRecordData`	Yes
Parameter	Type	Required
`smOptions`	`SecretsManagerOptions`	Yes
`recordsUids`	`string[]`	Yes
.NET SDK

Download and Installation

Prerequisites

Source Code

Using the SDK

Initialize Storage

Example Usage

Retrieve Secrets

Retrieve Secrets by Title

​

Retrieve Values from a Secret

Update Values in a Secret

Save Changes to a Secret

Generate a Random Password

Download a File

Download a Thumbnail

Upload a File

Create a Secret

Prerequisites:

Delete a Secret

Caching

Folders

Read Folders

Create a Folder

Update a Folder
