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

Secrets Manager
Example Usage
SecretsManager(token, config)
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')
)
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 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
Keeper Record creation with the Secrets Manager SDKs does not support File attachments at this time
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',
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:[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 aSecretsManager 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=KSMCache
)