Python SDK

Detailed Python SDK docs for Keeper Secrets Manager
Download and Installation
Install with PIP
pip3 install -U keeper-secrets-manager-core
Source Code
Find the Python source code in the GitHub repository​
Using the SDK
Initialize
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
Secrets Manager
Example Usage
SecretsManager(token, config)
# Using token, only to generate a config (for later usage),
# requires at least one access operation to bind the token
#get_secrets(uids=None)
from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.storage import FileKeyValueStorage
​
secrets_manager = SecretsManager(
    token='<One Time Access Token>',
    config=FileKeyValueStorage('ksm-config.json')
)
# Using token only to generate the config 
# requires at least one access operation to bind the token
#secrets_manager.get_secrets(uids=None)
Parameter
Required
Description
Type
token
Yes
One Time Access Token
String
config
Yes
Storage Configuration
KeyValueStorage
Retrieve Secrets
Get Secrets
Example: Get All Secrets
Example: Get Secrets With a Filter
get_secrets(uids=None)
from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.storage import FileKeyValueStorage
​
# setup secrets manger
secrets_manager = SecretsManager(
    token='<One Time Access Token>',
    config=FileKeyValueStorage('ksm-config.json')
)
​
# get all records
all_secrets = secrets_manager.get_secrets()
​
# print out all records
for secret in all_secrets:
    print(secret.dict)
from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.storage import FileKeyValueStorage
​
# setup secrets manger
secrets_manager = SecretsManager(
    token='<One Time Access Token>',
    config=FileKeyValueStorage('ksm-config.json')
)
​
# get a specific secret by record UID
secret = secrets_manager.get_secrets(['EG6KdJaaLG7esRZbMnfbFA'])[0]
​
# print out secret
print(secret.dict)
Parameter
Type
Required
Default
Description
uids
String[]
Optional
None
Record UIDs to fetch
Response
Type: Record[]
All Keeper records, or records with the given UIDs
​
Retrieve Values From a Secret
Retrieve a Password
This shortcut gets the password of a secret once that secret has been retrieved from Keeper Secrets Manager.
Get Password
Example Usage
secret.field('password', single=True)
from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.storage import FileKeyValueStorage
​
# setup secrets manger
secrets_manager = SecretsManager(
    token='<One Time Access Token>',
    config=FileKeyValueStorage('ksm-config.json')
)
​
# get a specific secret by record UID
secret = secrets_manager.get_secrets(['<RECORD UID>'])[0]
​
# get password from record
my_secret_password = secret.field('password', single=True)
Retrieve Standard Fields
Field
Example Usage
secret.field(field_type, single=False, value=None)
from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.storage import FileKeyValueStorage
​
# setup secrets manger
secrets_manager = SecretsManager(
    token='<One Time Access Token>',
    config=FileKeyValueStorage('ksm-config.json')
)
​
# get a specific secret by record UID
secret = secrets_manager.get_secrets(['<RECORD UID>'])[0]
​
# get login field from the secret
my_secret_login = secret.field("login", single=True)
Parameter
Type
Required
Default
Description
field_type
String
Yes
​
Field type to get
single
boolean
Optional
False
Return only the first value
value
String or String[]
Optional
None
If passed, set the value of the field to the given value
Fields are found by type, for a list of field types see the Record Types documentation.
Retrieve Custom Fields
Custom Field
Example Usage
secret.custom_field(label, field_type=None, single=False, value=None)
from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.storage import FileKeyValueStorage
​
# setup secrets manger
secrets_manager = SecretsManager(
    token='<One Time Access Token>',
    config=FileKeyValueStorage('ksm-config.json')
)
​
# get a specific secret by UID
secret = secrets_manager.get_secrets(['EG6KdJaaLG7esRZbMnfbFA'])[0]
​
# Get a standard template field
password = secret.field('password', single=True)
​
# Get a custom field, e.g. API Key
api_key = secret.custom_field('API Key', single=True)
Parameter
Type
Required
Default
Description
label
String
Yes
​
Label of the custom field
field_type
String
Yes
​
Field type to get
single
boolean
Optional
False
Return only the first value
value
String or String[]
Optional
None
If passed, set the value of the field to the given value
Custom fields are any field that is not part of the record type definition, but can be added by users.  For a list of fields in each standard record type, see the Record Types documentation.
It is possible for multiple fields of the same custom type to appear on a single record, to differentiate these fields, the field label is required.
Response
Type: String or String[]
the value or values of the field.  Will be a single value only if the single=True option is passed.
Retrieve Secrets by Title
Records by Title
Example Usage
# get all matching records
get_secrets_by_title(record_title)
​
# get only the first matching record
get_secret_by_title(record_title)
from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.storage import FileKeyValueStorage
​
# setup secrets manger
secrets_manager = SecretsManager(
    config=FileKeyValueStorage('ksm-config.json'))
​
# get the first secret matching the record title
secret = secrets_manager.get_secret_by_title("My Credentials")
​
# get all secrets matching the record title
secrets = secrets_manager.get_secrets_by_title("My Credentials")
Parameter
Type
Required
Description
record_title
String
Yes
Record title to search for
Retrieve Values using Keeper Notation
Get Notation
Example Usage
get_notation(query)
from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.storage import FileKeyValueStorage
​
# setup secrets manger
secrets_manager = SecretsManager(
    token='<One Time Access Token>',
    config=FileKeyValueStorage('ksm-config.json')
)
​
# get a specific standard field with Keeper Notation
password = secrets_manager.get_notation('EG6KdJaaLG7esRZbMnfbFA/field/password')[0]
​
# get a specific custom field with Keeper Notation
custom_field_value = secrets_manager.get_notation('EG6KdJaaLG7esRZbMnfbFA/custom_field/my_field')
See Keeper Notation documentation to learn about Keeper Notation format and capabilities
Parameter
Type
Required
Default
Description
query
String
Yes
​
Keeper Notation query for getting a value from a specified field
Returns
Type: string or string[]
The value of the queried field
Retrieve a TOTP Code
Get TOTP Code
Example Usage
get_totp_code(url)
from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.storage import FileKeyValueStorage
from keeper_secrets_manager_core.utils import get_totp_code
​
# setup secrets manger
secrets_manager = SecretsManager(
    token='<One Time Access Token>',
    config=FileKeyValueStorage('ksm-config.json')
)
​
# get TOTP url value from a record
url = record.get_standard_field_value('oneTimeCode', True)
​
# get code from TOTP url
totp = get_totp_code(url)
print(totp.code)
Parameter
Type
Required
Default
Description
url
String
Yes
​
TOTP Url
Update a Secret
Save Changes to a Secret
Save Secret
Example Usage
save(record: KeeperRecord)
from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.storage import FileKeyValueStorage
​
# setup secrets manger
secrets_manager = SecretsManager(
    token='<One Time Access Token>',
    config=FileKeyValueStorage('ksm-config.json')
)
​
# get a specific secret by UID
secret_to_update = secrets_manager.get_secrets(['EG6KdJaaLG7esRZbMnfbFA'])[0]
​
# update a field value
secret_to_update.field('login', 'new login')
​
secrets_manager.save(secret_to_update)
record
KeeperRecord
Yes
​
Storage and query configuration
Set field values using the field method.
Fields are found by type, for a list of field types see the Record Types documentation. Some fields have multiple values, in these cases the value can be set to a list.
Update a Standard Field Value
Field
Example Usage
secret.field(field_type, single=False, value=None)
from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.storage import FileKeyValueStorage
​
# setup secrets manger
secrets_manager = SecretsManager(
    token='<One Time Access Token>',
    config=FileKeyValueStorage('ksm-config.json')
)
​
# get a specific secret by record UID
secret = secrets_manager.get_secrets(['<RECORD UID>'])[0]
​
# update login
secret.field("login", single=True, "My New Login")
​
# save secret
secrets_manager.save(secret)
Parameter
Type
Required
Default
Description
field_type
String
Yes
​
Field type to get
single
boolean
Optional
False
Return only the first value
value
String or String[]
Optional
None
If passed, set the value of the field to the given value
Fields are found by type, for a list of field types see the Record Types documentation.
Update a Custom Field Value
Custom Field
Example Usage
secret.custom_field(label, field_type=None, single=False, value=None)
from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.storage import FileKeyValueStorage
​
# setup secrets manger
secrets_manager = SecretsManager(
    token='<One Time Access Token>',
    config=FileKeyValueStorage('ksm-config.json')
)
​
# get a specific secret by UID
secret = secrets_manager.get_secrets(['EG6KdJaaLG7esRZbMnfbFA'])[0]
​
# Get a standard template field
password = secret.field('password', single=True)
​
# Set custom field 'API Key'
my_new_api_key = "wKridl2ULt20qGuiP3IY"
secret.custom_field('API Key', single=True, my_new_api_key)
​
# Save changes to the secret
secrets_manager.save(secret)
Parameter
Type
Required
Default
Description
label
String
Yes
​
Label of the custom field
field_type
String
Yes
​
Field type to get
single
boolean
Optional
False
Return only the first value
value
String or String[]
Optional
None
If passed, set the value of the field to the given value
Generate a Random Password
Generate Password
Example Usage
generate_password(length, lowercase, uppercase, digits, specialCharacters)
from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.storage import FileKeyValueStorage
from keeper_secrets_manager_core.utils import generate_password
​
# setup secrets manger
secrets_manager = SecretsManager(
    token='<One Time Access Token>',
    config=FileKeyValueStorage('ksm-config.json')
)
​
# get a specific secret by UID
secret = secrets_manager.get_secrets(['EG6KdJaaLG7esRZbMnfbFA'])[0]
​
# generate a random password
password = generate_password()
# update a record with new password
secret.field('password', value=password)
​
# Save changes to the secret
secrets_manager.save(secret)
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
Save File
Example
file.save_file(file_path, create_folders=False)
# Save all files to a /tmp folder (create folder if does not exist)
for file in secret.files:
    print("file: %s" % file)
    file.save_file("/tmp/" + file.name, True)
Parameter
Type
Required
Default
Description
file_path
String
Yes
​
Path to save file to
create_folders
boolean
No
False
Create folders in the file_path if not present
Upload a File
Upload File
Example
Upload File:
upload_file(owner_record, file: my_file)
​
Creating the Keeper File Upload Object:
KeeperFileUpload.from_file(path, file_name=None, file_title=None, mime_type=None)
from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.storage import FileKeyValueStorage
from keeper_secrets_manager_core.core import KeeperFileUpload
​
secrets_manager = SecretsManager(
    config=FileKeyValueStorage('ksm-config.json')
)
​
# Get an individual secret by UID to attach the file to
UID_FILTER = 'XXX'
owner_record= secrets_manager.get_secrets([UID_FILTER])[0]
​
# Prepare file data for upload
my_file = KeeperFileUpload.from_file("./myFile.json", "myfile.json", "My File") 
​
# Upload file attached to the owner record
upload_file(owner_record, file: my_file)
Upload File
Parameter
Type
Required
Description
owner_record
KeeperRecord
Yes
The record to attach the uploaded file to
file
KeeperFileUpload
Yes
The File to upload
Keeper File Upload From File
Parameter
Type
Required
Default
Description
path
string
Yes
​
Path to the file to upload
file_name
string
No
None
What the name of the file will be in Keeper once uploaded
file_title
string
No
None
What the title of the file will be in Keeper once uploaded
mime_type
string
No
None
The type of data in the file.  If none is provided, 'application/octet-stream' will be used
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 upload_file​
Create a Record
Login Record Example
Custom Type Example
secrets_manager.create_secret(folder_uid, record)
Parameter
Type
Required
Default
folder_uid
String
Yes
​
record
KeeperRecord
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.
# create a new login record
new_login_record = RecordCreate('login', "Sample KSM Record: Python")
# fill in login and password fields
new_login_record.fields = [
    RecordField(field_type='login', value='[email protected]'),
    RecordField(field_type='password', value=generate_password())
]
# fill in notes
new_login_record.notes = 'This is a Python record creation example'
# create the new record 
secrets_manager.create_secret('[FOLDER UID]', new_login_record)
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.
custom_login = RecordCreate(record_type='Custom Login', title='Sample Custom Type KSM Record: Python')
custom_login.fields = [
    RecordField(field_type='host', 
                value={'hostName': '127.0.0.1', 'port': '8080'}, 
                label="My Custom Host lbl", 
                required=True),
    RecordField(field_type='login', 
                value='[email protected]', 
                label='My Custom Login lbl', 
                required=True),
    RecordField(field_type='password', 
                value=generate_password(), 
                label='My Custom Password lbl', 
                required=True),
    RecordField(field_type='url', 
                value='http://localhost:8080/login', 
                label='My Login Page', 
                required=True),
    RecordField(field_type='securityQuestion', 
                value={
                    'question': 'What is one plus one (write just a number)', 
                    'answer': '2'
                }, 
                label='My Question 1', 
                required=True),
    RecordField(field_type='phone', 
                value={
                  'region': 'US', 
                  'number': '510-444-3333', 
                  'ext': '2345', 
                  'type': 'Mobile'}, 
                label='My Phone Number'),
    RecordField(field_type='date', 
                value=1641934793000, 
                label='My Date Lbl', 
                required=True),
    RecordField(field_type='name', 
                value={
                  'first': 'John', 
                  'middle': 'Patrick', 
                  'last': 'Smith'}, 
                label="My Custom Name lbl", 
                required=True),
    RecordField(field_type='oneTimeCode', 
                value='otpauth://totp/Example:a[email protected]?secret=JBSWY3DPEHPK3PXP&issuer=Example', 
                label='My TOTP', 
                required=True)
]
​
custom_login.custom = [
    RecordField(field_type='phone', 
                value={'region': 'US', 'number': '510-222-5555', 'ext': '99887', 'type': 'Mobile'}, 
                label='My Custom Phone Lbl 1'),
    RecordField(field_type='phone', 
                value={'region': 'US', 'number': '510-111-3333', 'ext': '45674', 'type': 'Mobile'}, 
                label='My Custom Phone Lbl 2'),
]
​
custom_login.notes = "\tThis custom type record was created\n\tvia Python SDK copied from https://docs.keeper.io/secrets-manager/secrets-manager/developer-sdk-library/python-sdk"
​
record_uid = secrets_manager.create_secret('[FOLDER UID]', custom_login)
Delete a Secret
The Python KSM SDK can delete records in the Keeper Vault.
Delete Secret
Example
secrets_manager.delete_secret(record_uid)
​
Parameter
Type
Required
record_uid
string
Yes
from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.storage import FileKeyValueStorage
​
# setup secrets manger
secrets_manager = SecretsManager(
    token='<One Time Access Token>',
    config=FileKeyValueStorage('ksm-config.json')
)
​
# delete a specific secret by record UID
secret = secrets_manager.delete_secret('EG6KdJaaLG7esRZbMnfbFA')
Caching
To protect against losing access to your secrets when network access is lost, the Python SDK allows caching of secrets to the local machine in an encrypted file.
Setup and Configure Cache
In order to setup caching in the Python SDK, include a caching post function when creating a SecretsManager object.
The Python SDK includes a default caching function KSMCache which stores cached queries to a file.
secrets_manager = SecretsManager(
    token='<One Time Access Token>',
    config=FileKeyValueStorage('ksm-config.json')
    custom_post_function
Parameter	Required	Description	Type
token	Yes	One Time Access Token	String
config	Yes	Storage Configuration	`KeyValueStorage`
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
`owner_record`	KeeperRecord	Yes	The record to attach the uploaded file to
`file`	KeeperFileUpload	Yes	The File to upload
Parameter	Type	Required	Default	Description
`path`	string	Yes		Path to the file to upload
`file_name`	string	No	None	What the name of the file will be in Keeper once uploaded
`file_title`	string	No	None	What the title of the file will be in Keeper once uploaded
`mime_type`	string	No	None	The type of data in the file. If none is provided, 'application/octet-stream' will be used