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
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 SecretsManagerfrom keeper_secrets_manager_core.storage import FileKeyValueStoragesecrets_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(uids=None)
from keeper_secrets_manager_core import SecretsManagerfrom keeper_secrets_manager_core.storage import FileKeyValueStorage# setup secrets mangersecrets_manager =SecretsManager( token='<One Time Access Token>', config=FileKeyValueStorage('ksm-config.json'))# get all recordsall_secrets = secrets_manager.get_secrets()# print out all recordsfor secret in all_secrets:print(secret.dict)
from keeper_secrets_manager_core import SecretsManagerfrom keeper_secrets_manager_core.storage import FileKeyValueStorage# setup secrets mangersecrets_manager =SecretsManager( token='<One Time Access Token>', config=FileKeyValueStorage('ksm-config.json'))# get a specific secret by record UIDsecret = secrets_manager.get_secrets(['EG6KdJaaLG7esRZbMnfbFA'])[0]# print out secretprint(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.
secret.field('password', single=True)
from keeper_secrets_manager_core import SecretsManagerfrom keeper_secrets_manager_core.storage import FileKeyValueStorage# setup secrets mangersecrets_manager =SecretsManager( token='<One Time Access Token>', config=FileKeyValueStorage('ksm-config.json'))# get a specific secret by record UIDsecret = secrets_manager.get_secrets(['<RECORD UID>'])[0]# get password from recordmy_secret_password = secret.field('password', single=True)
from keeper_secrets_manager_core import SecretsManagerfrom keeper_secrets_manager_core.storage import FileKeyValueStorage# setup secrets mangersecrets_manager =SecretsManager( token='<One Time Access Token>', config=FileKeyValueStorage('ksm-config.json'))# get a specific secret by record UIDsecret = secrets_manager.get_secrets(['<RECORD UID>'])[0]# get login field from the secretmy_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.
from keeper_secrets_manager_core import SecretsManagerfrom keeper_secrets_manager_core.storage import FileKeyValueStorage# setup secrets mangersecrets_manager =SecretsManager( token='<One Time Access Token>', config=FileKeyValueStorage('ksm-config.json'))# get a specific secret by UIDsecret = secrets_manager.get_secrets(['EG6KdJaaLG7esRZbMnfbFA'])[0]# Get a standard template fieldpassword = secret.field('password', single=True)# Get a custom field, e.g. API Keyapi_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:StringorString[]
the value or values of the field.Will be a single value only if the single=True option is passed.
Retrieve Secrets by Title
# get all matching recordsget_secrets_by_title(record_title)# get only the first matching recordget_secret_by_title(record_title)
from keeper_secrets_manager_core import SecretsManagerfrom keeper_secrets_manager_core.storage import FileKeyValueStorage# setup secrets mangersecrets_manager =SecretsManager( config=FileKeyValueStorage('ksm-config.json'))# get the first secret matching the record titlesecret = secrets_manager.get_secret_by_title("My Credentials")# get all secrets matching the record titlesecrets = 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(query)
from keeper_secrets_manager_core import SecretsManagerfrom keeper_secrets_manager_core.storage import FileKeyValueStorage# setup secrets mangersecrets_manager =SecretsManager( token='<One Time Access Token>', config=FileKeyValueStorage('ksm-config.json'))# get a specific standard field with Keeper Notationpassword = secrets_manager.get_notation('EG6KdJaaLG7esRZbMnfbFA/field/password')[0]# get a specific custom field with Keeper Notationcustom_field_value = secrets_manager.get_notation('EG6KdJaaLG7esRZbMnfbFA/custom_field/my_field')
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(url)
from keeper_secrets_manager_core import SecretsManagerfrom keeper_secrets_manager_core.storage import FileKeyValueStoragefrom keeper_secrets_manager_core.utils import get_totp_code# setup secrets mangersecrets_manager =SecretsManager( token='<One Time Access Token>', config=FileKeyValueStorage('ksm-config.json'))# get TOTP url value from a recordurl = record.get_standard_field_value('oneTimeCode', True)# get code from TOTP urltotp =get_totp_code(url)print(totp.code)
Parameter
Type
Required
Default
Description
url
String
Yes
TOTP Url
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.
Save Changes to a Secret
save(record: KeeperRecord)
from keeper_secrets_manager_core import SecretsManagerfrom keeper_secrets_manager_core.storage import FileKeyValueStorage# setup secrets mangersecrets_manager =SecretsManager( token='<One Time Access Token>', config=FileKeyValueStorage('ksm-config.json'))# get a specific secret by UIDsecret_to_update = secrets_manager.get_secrets(['EG6KdJaaLG7esRZbMnfbFA'])[0]# update a field valuesecret_to_update.field('login', 'new login')secrets_manager.save(secret_to_update)
from keeper_secrets_manager_core import SecretsManagerfrom keeper_secrets_manager_core.storage import FileKeyValueStorage# setup secrets mangersecrets_manager =SecretsManager( config=FileKeyValueStorage('ksm-config.json'))# get a specific secret by UIDsecret = secrets_manager.get_secrets(['EG6KdJaaLG7esRZbMnfbFA'])[0]# rotate password on the recordsecret.field('password', 'new password')# start a transactionsecrets_manager.save(secret, 'rotation')# rotate password on remote hostsuccess =rotate_remote_ssh_password('new password')# complete the transaction - commit or rollbacksecrets_manager.complete_transaction(secret.uid, rollback=not success)
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.
from keeper_secrets_manager_core import SecretsManagerfrom keeper_secrets_manager_core.storage import FileKeyValueStorage# setup secrets mangersecrets_manager =SecretsManager( token='<One Time Access Token>', config=FileKeyValueStorage('ksm-config.json'))# get a specific secret by record UIDsecret = secrets_manager.get_secrets(['<RECORD UID>'])[0]# update loginsecret.field("login", single=True, "My New Login")# save secretsecrets_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.
from keeper_secrets_manager_core import SecretsManagerfrom keeper_secrets_manager_core.storage import FileKeyValueStorage# setup secrets mangersecrets_manager =SecretsManager( token='<One Time Access Token>', config=FileKeyValueStorage('ksm-config.json'))# get a specific secret by UIDsecret = secrets_manager.get_secrets(['EG6KdJaaLG7esRZbMnfbFA'])[0]# Get a standard template fieldpassword = 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 secretsecrets_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
from keeper_secrets_manager_core import SecretsManagerfrom keeper_secrets_manager_core.storage import FileKeyValueStoragefrom keeper_secrets_manager_core.utils import generate_password# setup secrets mangersecrets_manager =SecretsManager( token='<One Time Access Token>', config=FileKeyValueStorage('ksm-config.json'))# get a specific secret by UIDsecret = secrets_manager.get_secrets(['EG6KdJaaLG7esRZbMnfbFA'])[0]# generate a random passwordpassword =generate_password()# update a record with new passwordsecret.field('password', value=password)# Save changes to the secretsecrets_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
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)
from keeper_secrets_manager_core import SecretsManagerfrom keeper_secrets_manager_core.storage import FileKeyValueStoragefrom keeper_secrets_manager_core.core import KeeperFileUploadsecrets_manager =SecretsManager( config=FileKeyValueStorage('ksm-config.json'))# Get an individual secret by UID to attach the file toUID_FILTER ='XXX'owner_record= secrets_manager.get_secrets([UID_FILTER])[0]# Prepare file data for uploadmy_file = KeeperFileUpload.from_file("./myFile.json", "myfile.json", "My File")# Upload file attached to the owner record and get the file UIDfile_uid = secrets_manager.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
Returns
Type: string
The file UID of the attached file
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
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 recordnew_login_record =RecordCreate('login', "Sample KSM Record: Python")# fill in login and password fieldsnew_login_record.fields = [RecordField(field_type='login', value='username@email.com'),RecordField(field_type='password', value=generate_password())]# fill in notesnew_login_record.notes ='This is a Python record creation example'# create the new record and get its UIDrecord_uid = 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.
The Python KSM SDK can delete records in the Keeper Vault.
secrets_manager.delete_secret(record_uid)
Parameter
Type
Required
record_uid
string
Yes
from keeper_secrets_manager_core import SecretsManagerfrom keeper_secrets_manager_core.storage import FileKeyValueStorage# setup secrets mangersecrets_manager =SecretsManager( token='<One Time Access Token>', config=FileKeyValueStorage('ksm-config.json'))# delete a specific secret by record UIDsecret = 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 in KSMCache class which stores cached queries to a local file thus serving as a disaster recovery function (as long as there's network connectivity it always prefers network over cached data and will use cache only if web vault is inaccessible). You can create your own caching function using KSMCache as a starting point - ex. one that prefers local cache over network access and provide own cache management (ex. refresh cached data once every 5 min)
secrets_manager =SecretsManager( token='<One Time Access Token>', config=FileKeyValueStorage('ksm-config.json'), custom_post_function=KSMCache.caching_post_function)
The default caching function in KSMCache class always stores last request only - ex. filtered request on UID1 but on disconnect request UID2 from same cache will return empty response (although UID2 may be shared to the same KSM app but it was not cached)
Updating a record from cache (or creating new record) invalidates cached record data and consecutive updates of the same record will fail. Batch updates work as long as they modify different records. Always follow up cached record updates with a call to get_secrets function to refresh cache (and pull updated metadata from vault like the new record revision etc.)
Folders
Folders have full CRUD support - create, read, update and delete operations.
Read Folders
Downloads full folder hierarchy.
get_folders()
Response
Type:List[KeeperFolder]
Example Usage
from keeper_secrets_manager_core import SecretsManagerfrom keeper_secrets_manager_core.storage import FileKeyValueStoragesecrets_manager =SecretsManager(config=FileKeyValueStorage('ksm-config.json'))folders = secrets_manager.get_folders()
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.
List of folders to use in the search for parent folder
Example Usage
from keeper_secrets_manager_core import SecretsManagerfrom keeper_secrets_manager_core.storage import FileKeyValueStoragesecrets_manager =SecretsManager(config=FileKeyValueStorage('ksm-config.json'))secrets_manager.update_folder("[FOLDER_UID]", "new_folder_name")
Delete Folders
Removes a list of folders. Use force_deletion flag to remove non-empty folders.
When using force_deletion 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.
Any folders UIDs missing from the vault or not shared to the KSM Application will not result in error.