Python SDK | KeeperPAM and Secrets Manager | Keeper Documentation Portal

Python SDK

Detailed Python SDK docs for Keeper Secrets Manager

Download and Installation

Install with PIP

pip3 install -U keeper-secrets-manager-core

Python Requirements: Python 3.9 or higher

For more information, see https://pypi.org/project/keeper-secrets-manager-core/

Source Code

Find the Python source code in the GitHub repository

Related Packages:

Using the SDK

Initialize

One-Time Token behavior: The token is consumed on first use, including on failed attempts. If initialization fails, the SDK (v17.3.0+) automatically removes the incomplete config file (file-based storage only). Generate a new One-Time Token from your KSM Application and retry.

At least one API call (e.g. get_secrets()) must follow initialization to complete token binding and fully populate the config file. Subsequent runs without a token use the config file directly.

SecretsManager(token, config)
# At least one API call is required to complete token binding
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')
)
# Required: completes token binding and populates the config file
secrets_manager.get_secrets()

Parameter

Type

Required

Default

Description

token

str

Optional

None

One-time access token. Required on first run to bind the application; omit once config is bound

config

KeyValueStorage

Optional

FileKeyValueStorage()

Storage backend. Defaults to client-config.json in the current directory if not provided

hostname

str

Optional

None

Override the server hostname. Required when using a bare token without a region prefix

verify_ssl_certs

bool

Optional

True

Verify SSL certificates on outbound requests

Configuration files are automatically created with secure permissions (0600 on Unix-based systems) in v17.1.0+.

Binding Lifecycle

The one-time token is redeemed on the first get_secrets() 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.

from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.storage import FileKeyValueStorage

# First run: provide a one-time token and a persistent storage path.
sm = SecretsManager(
    token="US:BASE64_ONE_TIME_TOKEN",
    config=FileKeyValueStorage("ksm-config.json")
)
records = sm.get_secrets()  # Token is redeemed here; ksm-config.json is updated.

# Subsequent runs: omit the token. Stored credentials are used directly.
sm = SecretsManager(config=FileKeyValueStorage("ksm-config.json"))
records = sm.get_secrets()

Retrieve Secrets

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

List[str]

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

secret.field(field_type, value=None, single=False)

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

str

Yes

Field type to get

value

str or List[str]

Optional

None

If passed, set the value of the field to the given value

single

bool

Optional

False

Return only the first value

Field types are based on the Keeper Record Type. For a detailed list of available fields based on the Keeper Record Type, see the record-type-info command in Keeper Commander.

Retrieve Custom Fields

secret.custom_field(label, field_type=None, value=None, single=False)

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

str

Yes

Label of the custom field

field_type

str

Optional

None

Field type to get

value

str or List[str]

Optional

None

If passed, set the value of the field to the given value

single

bool

Optional

False

Return only the first value

Custom fields are any field that is not part of the record type definition, but can be added by users.

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: str or List[str]

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

str

Yes

Record title to search for

Retrieve Values using Keeper Notation

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')

# 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

Description

query

str

Yes

Keeper Notation query for getting a value from a specified field

Returns

Type: str or List[str]

The value of the queried field

Retrieve a TOTP Code

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 manager
secrets_manager = SecretsManager(
    token='<One Time Access Token>',
    config=FileKeyValueStorage('ksm-config.json')
)

# get a specific secret by record UID
record = secrets_manager.get_secrets(['<RECORD UID>'])[0]

# get TOTP url value from the 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

Description

url

str

Yes

TOTP URI in otpauth:// format. Raises ValueError if the URI scheme is not otpauth

PAM Record Types

Use record.type to identify PAM records returned by the SDK.

for record in records:
    if record.type == "pamMachine":
        host = record.field("pamHostname")[0]  # {"hostName": ..., "port": ...}
    elif record.type == "pamUser":
        login = record.field("login")[0]
    elif record.type == "pamDatabase":
        db_type = record.field("databaseType")[0]

For field schemas of all 11 PAM record types, see PAM Record Types.

Linked Credentials

PAM records can carry links to credential records. Links are not included in get_secrets() responses by default. Request them via get_secrets_with_options() with request_links=True, then call record.get_links() to access them as typed KeeperRecordLink objects.

from keeper_secrets_manager_core.dto.payload import QueryOptions

query_options = QueryOptions(
    records_filter=['<RECORD UID>'],
    folders_filter=None,
    request_links=True
)
records = secrets_manager.get_secrets_with_options(query_options)

for link in records[0].get_links():
    print(link.record_uid)   # UID of the linked record
    print(link.path)         # None = credential link; "meta" = PAM settings

from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.storage import FileKeyValueStorage
from keeper_secrets_manager_core.dto.payload import QueryOptions

secrets_manager = SecretsManager(
    config=FileKeyValueStorage('ksm-config.json')
)

query_options = QueryOptions(
    records_filter=['<RECORD UID>'],
    folders_filter=None,
    request_links=True
)
records = secrets_manager.get_secrets_with_options(query_options)

for link in records[0].get_links():
    print(f"Linked record: {link.record_uid}  path: {link.path}")

    # Credential link flags (path is None)
    if link.path is None:
        print(f"  Admin user:         {link.is_admin_user()}")
        print(f"  Launch credential:  {link.is_launch_credential()}")
        print(f"  IAM user:           {link.is_iam_user()}")

    # PAM settings flags (path == "meta")
    if link.path == "meta":
        print(f"  Allows rotation:     {link.allows_rotation()}")
        print(f"  Allows connections:  {link.allows_connections()}")

KeeperRecordLink attributes

Attribute

Type

Description

record_uid

str

UID of the linked record

path

str or None

Link type discriminator. None = credential link to another record; "meta" = PAM settings self-link; "ai_settings" / "jit_settings" = encrypted settings self-links

data

str or None

Raw base64 link payload. Use accessor methods instead of reading this directly

KeeperRecordLink methods

Method

Returns

Description

is_admin_user()

bool

Linked credential is an admin user

is_launch_credential()

bool

Link is a launch credential

is_iam_user()

bool

Linked credential is an IAM user

belongs_to()

bool

Linked credential belongs to the record

allows_rotation()

bool

Rotation is permitted (credential or meta link)

allows_connections()

bool

Connections are permitted

allows_port_forwards()

bool

Port forwarding is permitted

allows_session_recording()

bool

Session recording is enabled

get_rotation_settings()

dict or None

Rotation schedule and complexity settings

get_meta_data()

dict or None

Full PAM settings payload (path == "meta")

get_link_data()

dict or None

Complete parsed link payload for any path

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 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', value='new login')

# update non-field values
secret_to_update.title = "New Title"
secret_to_update.notes = "New Notes"

# save updated secret
secrets_manager.save(secret_to_update)

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 a specific secret by UID
secret = secrets_manager.get_secrets(['EG6KdJaaLG7esRZbMnfbFA'])[0]

# rotate password on the record
secret.field('password', value='new password')
# start a transaction
secrets_manager.save(secret, 'rotation')
# rotate password on remote host
success = rotate_remote_ssh_password('new password')
# complete the transaction - commit or rollback
secrets_manager.complete_transaction(secret.uid, rollback=not success)

record

KeeperRecord

Yes

Record to save

Set field values using the field method. For a detailed list of available fields based on the Keeper Record Type, see the record-type-info command in Keeper Commander. Some fields have multiple values, in these cases the value can be set to a list.

Update a Standard Field Value

secret.field(field_type, value=None, single=False)

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", value="My New Login")

# save secret
secrets_manager.save(secret)

Parameter

Type

Required

Default

Description

field_type

str

Yes

Field type to get

value

str or List[str]

Optional

None

If passed, set the value of the field to the given value

single

bool

Optional

False

Return only the first value

Update a Custom Field Value

secret.custom_field(label, field_type=None, value=None, single=False)

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', value=my_new_api_key)

# Save changes to the secret
secrets_manager.save(secret)

Parameter

Type

Required

Default

Description

label

str

Yes

Label of the custom field

field_type

str

Optional

None

Field type to get

value

str or List[str]

Optional

None

If passed, set the value of the field to the given value

single

bool

Optional

False

Return only the first value

Generate a Random Password

generate_password(length, lowercase, uppercase, digits, special_characters, special_characterset)

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(special_characterset="@!#$%^&*<>?")
# update a record with new password
secret.field('password', value=password)

# Save changes to the secret
secrets_manager.save(secret)

Parameter

Type

Required

Default

Description

length

int

Optional

Minimum total password length

lowercase

int

Optional

None

Minimum lowercase chars (positive), exact count (zero or negative), or unconstrained (None)

uppercase

int

Optional

None

Minimum uppercase chars (positive), exact count (zero or negative), or unconstrained (None)

digits

int

Optional

None

Minimum digit chars (positive), exact count (zero or negative), or unconstrained (None)

special_characters

int

Optional

None

Minimum special chars (positive), exact count (zero or negative), or unconstrained (None)

special_characterset

str

Optional

"!@#$%()+;<>=?[]{}^.,

Custom set of characters to draw from when generating the special character portion

Each character-class parameter sets the minimum count if positive, an exact count if zero or negative, or is unconstrained if None (the default). When all four groups are None, or when the total of all exact counts is less than length, the remaining positions are filled from all enabled groups uniformly at random.

Download a File

file.save_file(file_path, create_folders=False)

Parameter

Type

Required

Default

Description

file_path

str

Yes

Path to save file to

create_folders

bool

False

Create folders in the file_path if not present

Upload a File

Upload File:

upload_file(owner_record, file: KeeperFileUpload)

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 and get the file UID
file_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

str

Yes

Path to the file to upload

file_name

str

None

What the name of the file will be in Keeper once uploaded

file_title

str

None

What the title of the file will be in Keeper once uploaded

mime_type

str

None

The type of data in the file. If none is provided, 'application/octet-stream' will be used

Returns

Type: str

The file UID of the attached file

Remove File Attachments

secrets_manager.save(record, links_to_remove=['<FILE_UID>'])

from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.storage import FileKeyValueStorage

secrets_manager = SecretsManager(
    config=FileKeyValueStorage('ksm-config.json')
)

# Get a secret by UID
secret = secrets_manager.get_secrets(['<RECORD_UID>'])[0]

# Get file UIDs from the record
file_uids = [file.file_uid for file in secret.files]
print(f"Files to remove: {file_uids}")

# Remove specific files by UID
secrets_manager.save(secret, links_to_remove=file_uids)

from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.storage import FileKeyValueStorage

secrets_manager = SecretsManager(
    config=FileKeyValueStorage('ksm-config.json')
)

# Get a secret by UID
secret = secrets_manager.get_secrets(['<RECORD_UID>'])[0]

# Remove multiple specific files
files_to_remove = ['<FILE_UID_1>', '<FILE_UID_2>']
secrets_manager.save(secret, links_to_remove=files_to_remove)

# Or remove all files
all_file_uids = [file.file_uid for file in secret.files]
secrets_manager.save(secret, links_to_remove=all_file_uids)

Parameter

Type

Required

Description

record

KeeperRecord

Yes

The record to update

links_to_remove

str or List[str]

File UID(s) to remove from the record

After removing files, make sure to reload the record with get_secrets() if you plan to make additional updates, as the record revision will have changed.

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

from keeper_secrets_manager_core.dto.dtos import RecordCreate,RecordField

record = RecordCreate(record_type='login', title='test_KSM')
record.fields = [ 
    RecordField(field_type='login',value='test_login'),
    RecordField(field_type='password',value='test_pwd') 
]

secrets_manager.create_secret(folder_uid, record)

Parameter

Type

Required

Default

folder_uid

str

Yes

record

KeeperRecord

Yes

from keeper_secrets_manager_core.dto.dtos import RecordCreate,RecordField

record = RecordCreate(record_type='login', title='test_KSM')
record.fields = [ 
    RecordField(field_type='login',value='test_login'),
    RecordField(field_type='password',value='test_pwd') 
]

from keeper_secrets_manager_core.dto.payload import CreateOptions

create_options = CreateOptions(
    folder_uid='shared_folder_uid',
    subfolder_uid='user_folder_uid'
)

secrets_manager.create_secret_with_options(create_options, record)

Parameter

Type

Required

Default

create_options

CreateOptions

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='username@email.com'),
    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 and get its UID
record_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.

from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.storage import FileKeyValueStorage
from keeper_secrets_manager_core.dto.dtos import RecordCreate, RecordField
from keeper_secrets_manager_core.utils import generate_password

# setup secrets manger
secrets_manager = SecretsManager(
    # token='US:XXXXXX',
    config=FileKeyValueStorage('ksm-config.json')
)

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='login@email.com', 
                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:alice@google.com?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)

Returns

Type: str

The record UID of the new record

Delete a Secret

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

secrets_manager.delete_secret(record_uids)

Parameter

Type

Required

Description

record_uids

str or List[str]

Yes

UID or list of UIDs of records to delete

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
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 KSMCache stores only the most recent response. If you call get_secrets(['<uid>']) and then call get_secrets() without arguments while offline, the second call returns only the one cached record, not your full vault.

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

Creating your own caching function

For start create caching function with following arguments and call post_function

from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.core import KSMCache, KSMHttpResponse

def caching_post_function(
        url, transmission_key, encrypted_payload_and_signature, verify_ssl_certs=True, proxy_url=None
):
    ksm_rs = SecretsManager.post_function(
        url, transmission_key, encrypted_payload_and_signature, verify_ssl_certs
    )
    # Your custom caching logic here ...

    # Make sure to always return a KSMHttpResponse object
    return ksm_rs

Then you can implement any custom logic of caching using KSMCache. Full basic example:

from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.core import KSMCache, KSMHttpResponse
from keeper_secrets_manager_core.storage import FileKeyValueStorage
from http import HTTPStatus

def caching_post_function(
        url, transmission_key, encrypted_payload_and_signature, verify_ssl_certs=True, proxy_url=None
):
    ksm_rs = SecretsManager.post_function(
        url, transmission_key, encrypted_payload_and_signature, verify_ssl_certs
    )

    if ksm_rs.status_code < 400:
        KSMCache.save_cache(transmission_key.key + ksm_rs.data)
        return ksm_rs

    # KSMCache can be empty    
    cached_data = KSMCache.get_cached_data()
    cached_transmission_key = cached_data[:32]
    transmission_key.key = cached_transmission_key
    data = cached_data[32 : len(cached_data)]

    new_rs = KSMHttpResponse(HTTPStatus.OK, data, None)
    return new_rs


secrets_manager = SecretsManager(
    config=FileKeyValueStorage('ksm-config.json'),
    verify_ssl_certs=False,
    custom_post_function=caching_post_function
)

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 SecretsManager
from keeper_secrets_manager_core.storage import FileKeyValueStorage

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

create_folder(create_options: CreateOptions, folder_name: str, folders=None)

Parameter

Type

Required

Default

Description

create_options

CreateOptions

Yes

The parent and sub-folder UIDs

folder_name

str

Yes

The Folder name

folders

List[KeeperFolder]

None

List of folders to use in the search for parent and sub-folder from CreateOptions

Example Usage

from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.core import CreateOptions
from keeper_secrets_manager_core.storage import FileKeyValueStorage

secrets_manager = SecretsManager(config=FileKeyValueStorage('ksm-config.json'))
co = CreateOptions(folder_uid="[PARENT_SHARED_FOLDER_UID]", subfolder_uid="")
new_folder_uid = secrets_manager.create_folder(co, "new_folder")

Update a Folder

Updates the folder metadata - currently folder name only.

update_folder(folder_uid: str, folder_name: str, folders=None)

Parameter

Type

Required

Default

Description

folder_uid

str

Yes

The folder UID

folder_name

str

Yes

The new folder name

folders

List[KeeperFolder]

None

List of folders to use in the search for parent folder

Example Usage

from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.storage import FileKeyValueStorage

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

delete_folder(folder_uids: List[str], force_deletion: bool = False)

Parameter

Type

Required

Default

Description

folder_uids

List[str]

Yes

The folder UID list

force_deletion

bool

False

Force deletion of non-empty folders

Example Usage

from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.storage import FileKeyValueStorage

secrets_manager = SecretsManager(config=FileKeyValueStorage('ksm-config.json'))
secrets_manager.delete_folder(["[FOLDER_UID1]", "[FOLDER_UID2]"], True)

Proxy support

Environment variable

Keeper Secrets Manager SDK uses the requests library to support the HTTPS_PROXY environment variable by default

HTTPS_PROXY=https://yourproxy:8888 python main.py

Every request including Keeper Secrets Manager requests will go through declared proxy

Using environment variables for proxy settings is preferred because it keeps configuration out of code, ensures consistency across tools, and simplifies deployment.

SecretsManager parameter

Optionally, you can pass your proxy url to SecretsManager if you want proxy to be used only in SDK:

secrets_manager = SecretsManager(
    config=FileKeyValueStorage('ksm-config.json'),
    proxy_url="https://yourproxy:8888"
)

If your proxy has authentication, just pass your username and password in proxy url

https://username:pass@yourproxy:8888

Advanced Configuration

Custom Server Public Key

For isolated or private deployments where the SDK cannot ship with the server public key, supply an EC P-256 public key via either of two paths. Precedence is programmatic > pre-existing config.

Programmatic — pass server_public_key and server_public_key_id to SecretsManager():

from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.storage import FileKeyValueStorage

secrets_manager = SecretsManager(
    token='REGION:ONE_TIME_TOKEN',
    server_public_key='<url-safe-base64-EC-P256-public-key>',
    server_public_key_id='<numeric-key-id>',
    config=FileKeyValueStorage('ksm-config.json'),
)

Config file — add serverPublicKey and serverPublicKeyId to an existing bound ksm-config.json before the first call. These two fields supplement the bound configuration, they do not replace it:

{
  "serverPublicKey": "<url-safe-base64-EC-P256-public-key>",
  "serverPublicKeyId": "<key-id>"
}

PreviousKSM Developer SDKs NextJava/Kotlin SDK

Last updated 18 days ago

Sunbelt Computer Software

PL/B Language Development and Support

Good afternoon

Download and Installation

Install with PIP

Source Code

Using the SDK

Initialize

Binding Lifecycle

Retrieve Secrets

Retrieve Values From a Secret

Retrieve a Password

Retrieve Standard Fields

Retrieve Custom Fields

Retrieve Secrets by Title

Retrieve Values using Keeper Notation

Returns

Retrieve a TOTP Code

PAM Record Types

Linked Credentials

Update a Secret

Update a Standard Field Value

Update a Custom Field Value

Generate a Random Password

Download a File

Upload a File

Returns

Remove File Attachments

Create a Secret

Prerequisites:

Returns

Delete a Secret

Caching

Creating your own caching function

Folders

Read Folders

Create a Folder

Update a Folder

Delete Folders

Proxy support

Environment variable

SecretsManager parameter

Advanced Configuration

Custom Server Public Key