Client#

class yc_lockbox.YandexLockboxFacade(credentials, *, auth_client=<class 'yc_lockbox._auth.YandexAuthClient'>, lockbox_base_url=None, payload_lockbox_base_url=None, enable_async=False)[source]#

Bases: object

A facade for encapsulating the logic of synchronous and asynchronous client operations, providing uniform methods.

property client: AbstractYandexLockboxClient#

Returns initialized Lockbox client.

class yc_lockbox.YandexLockboxClient(credentials, *, auth_client=<class 'yc_lockbox._auth.YandexAuthClient'>, adapter=<class 'yc_lockbox._adapters.HTTPAdapter'>, lockbox_base_url=None, payload_lockbox_base_url=None)[source]#

Bases: AbstractYandexLockboxClient

Yandex Lockbox secrets vault client.

Parameters:

  • credentials – Credentials for authenticate requests. Allowed types: service account key, OAuth token, IAM token.

  • auth_client (Optional[Type[AbstractYandexAuthClient]]) – Optional client implementation for authenticate requests. Defaults to YandexAuthClient.

  • adapter (Optional[Type[AbstractHTTPAdapter]]) – HTTP adapter for communicate with Yandex Cloud API.

  • lockbox_base_url (Optional[str]) – Lockbox base URL without resource path.

  • payload_lockbox_base_url (Optional[str]) – Lockbox payload base URL without resource path.

  • auth_base_url – IAM base URL without resource path.

Note

All the values of the secrets are masked, i.e. looks like ***********. To get the real value of the secret, you need to call the injected methods reveal_text_value() or reveal_binary_value().

Usage:

from yc_lockbox import YandexLockboxClient, Secret

lockbox = YandexLockboxClient("y0_AgAEXXXXXXXXXXXXXXXXXXXXXXXXX")  # OAuth or IAM token

secret: Secret = lockbox.get_secret("e6xxxxxxxxxxxxxxxx")
print(secret.name, secret.status, secret.description)

payload = secret.payload()

try:
    value = payload["mykey"]
    print(value.reveal_text_value())
except KeyError:
    print("Invalid key!")

print(payload.get("foo"))  # None if not exists without raising exception
entry = payload[0]  # similar to payload.entries[0]

Authenticate via service account key:

import json

# generate json key for your SA
# yc iam key create --service-account-name my-sa --output key.json

with open("./key.json", "r") as infile:
    credentials = json.load(infile)

lockbox = YandexLockboxClient(credentials)
activate_secret(secret_id, raise_for_status=True)[source]#

Activates the specified secret.

Parameters:

  • secret_id (str) – Secret indentifier.

  • raise_for_status (bool) – If set to False returns YandexCloudError instead throw exception. Defaults to True.

Return type:

Operation | YandexCloudError

add_secret_version(secret_id, version, raise_for_status=True)[source]#

Adds new version based on a previous one.

Parameters:

  • secret_id (str) – Secret indentifier.

  • version (INewSecretVersion) – A new version object.

  • raise_for_status (bool) – If set to False returns YandexCloudError instead throw exception. Defaults to True.

Return type:

Operation | YandexCloudError

property auth_headers: dict[str, str]#

Returns headers for authenticate.

cancel_secret_version_destruction(secret_id, version_id, raise_for_status=True)[source]#

Cancels previously scheduled version destruction, if the version hasn’t been destroyed yet.

Parameters:

  • secret_id (str) – Secret indentifier.

  • version_id (str) – Secret version id to cancel destruction.

  • raise_for_status (bool) – If set to False returns YandexCloudError instead throw exception. Defaults to True.

Return type:

Operation | YandexCloudError

create_secret(secret, raise_for_status=True)[source]#

Creates a secret in the specified folder.

Parameters:

  • secret (INewSecret) – A new secret object.

  • raise_for_status (bool) – If set to False returns YandexCloudError instead throw exception. Defaults to True.

Return type:

Operation | YandexCloudError

deactivate_secret(secret_id, raise_for_status=True)[source]#

Deactivate a secret.

Parameters:

  • secret_id (str) – Secret indentifier.

  • raise_for_status (bool) – If set to False returns YandexCloudError instead throw exception. Defaults to True.

Return type:

Operation | YandexCloudError

delete_secret(secret_id, raise_for_status=True)[source]#

Deletes the specified secret.

Parameters:

  • secret_id (str) – Secret indentifier.

  • raise_for_status (bool) – If set to False returns YandexCloudError instead throw exception. Defaults to True.

Return type:

Operation | YandexCloudError

get_secret(secret_id, raise_for_status=True)[source]#

Get lockbox secret by ID.

Parameters:

  • secret_id (str) – Secret identifier.

  • raise_for_status (bool) – If set to False returns YandexCloudError instead throw exception. Defaults to True.

Return type:

Secret | YandexCloudError

get_secret_payload(secret_id, version_id=None, raise_for_status=True)[source]#

Get lockbox secret payload by ID and optional version.

Parameters:

  • secret_id (str) – Secret identifier.

  • version_id (Optional[str]) – Secret version. Optional.

  • raise_for_status (bool) – If set to False returns YandexCloudError instead throw exception. Defaults to True.

Return type:

SecretPayload | YandexCloudError

list_secret_access_bindings(*args, **kwargs)[source]#

Not ready yet.

list_secret_operations(*args, **kwargs)[source]#

Not ready yet.

list_secret_versions(secret_id, page_size=100, page_token=None, raise_for_status=True, iterator=False)[source]#

Retrieves the list of versions of the specified secret.

Parameters:

  • secret_id (str) – Secret identifier.

  • page_size (int) – The maximum number of results per page to return. If the number of available results is larger than page_size, the service returns a next_page_token that can be used to get the next page of results in subsequent list requests. Default value: 100. The maximum value is 1000.

  • page_token (Optional[str]) – Page token. To get the next page of results, set page_token to the next_page_token returned by a previous list request.

  • iterator (bool) – Returns all data as iterator (generator) instead paginated result.

Return type:

Union[SecretVersionsList, Iterator[SecretVersion], YandexCloudError]

list_secrets(folder_id, page_size=100, page_token=None, raise_for_status=True, iterator=False)[source]#

Retrieves the list of secrets in the specified folder.

Parameters:

  • folder_id (str) – ID of the folder to list secrets in.

  • page_size (int) – The maximum number of results per page to return. If the number of available results is larger than page_size, the service returns a next_page_token that can be used to get the next page of results in subsequent list requests. Default value: 100. The maximum value is 1000.

  • page_token (Optional[str]) – Page token. To get the next page of results, set page_token to the next_page_token returned by a previous list request.

  • iterator (bool) – Returns all data as iterator (generator) instead paginated result.

Return type:

Union[SecretsList, Iterator[Secret], YandexCloudError]

schedule_secret_version_destruction(secret_id, version_id, pending_period=604800, raise_for_status=True)[source]#

Schedules the specified version for destruction. Scheduled destruction can be cancelled with the cancel_secret_version_destruction() method.

Parameters:

  • secret_id (str) – Secret indentifier.

  • version_id (str) – ID of the version to be destroyed.

  • pending_period (int) – Time interval in seconds between the version destruction request and actual destruction. Default value: 604800 (i.e. 7 days).

  • raise_for_status (bool) – If set to False returns YandexCloudError instead throw exception. Defaults to True.

Return type:

Operation | YandexCloudError

set_secret_access_bindings(*args, **kwargs)[source]#

Not ready yet.

update_secret(secret_id, data, raise_for_status=True)[source]#

Updates the specified secret.

Parameters:

  • secret_id (str) – Secret identifier.

  • data (IUpdateSecret) – A new data for the secret as object. Important. Field mask that specifies which attributes of the secret are going to be updated. A comma-separated names off ALL fields to be updated. Only the specified fields will be changed. The others will be left untouched. If the field is specified in updateMask and no value for that field was sent in the request, the field’s value will be reset to the default. The default value for most fields is null or 0. If updateMask is not sent in the request, all fields values will be updated. Fields specified in the request will be updated to provided values. The rest of the fields will be reset to the default.

  • raise_for_status (bool) – If set to False returns YandexCloudError instead throw exception. Defaults to True.

Return type:

Operation | YandexCloudError

update_secret_access_bindings(*args, **kwargs)[source]#

Not ready yet.

class yc_lockbox.AsyncYandexLockboxClient(credentials, *, auth_client=<class 'yc_lockbox._auth.YandexAuthClient'>, adapter=<class 'yc_lockbox._adapters.AsyncHTTPAdapter'>, lockbox_base_url=None, payload_lockbox_base_url=None)[source]#

Bases: AbstractYandexLockboxClient

Yandex Lockbox secrets vault client. The same as YandexLockboxClient but async.

Parameters:

  • credentials – Credentials for authenticate requests. Allowed types: service account key, OAuth token, IAM token.

  • auth_client (Optional[Type[AbstractYandexAuthClient]]) – Optional client implementation for authenticate requests. Defaults to YandexAuthClient.

  • adapter (Optional[Type[AbstractHTTPAdapter]]) – HTTP adapter for communicate with Yandex Cloud API.

  • lockbox_base_url (Optional[str]) – Lockbox base URL without resource path.

  • payload_lockbox_base_url (Optional[str]) – Lockbox payload base URL without resource path.

  • auth_base_url – IAM base URL without resource path.

Note

All the values of the secrets are masked, i.e. looks like ***********. To get the real value of the secret, you need to call the injected methods reveal_text_value() or reveal_binary_value().

Usage:

from yc_lockbox import AsyncYandexLockboxClient, Secret

lockbox = AsyncYandexLockboxClient("y0_AgAEXXXXXXXXXXXXXXXXXXXXXXXXX")  # OAuth or IAM token

secret: Secret = await lockbox.get_secret("e6xxxxxxxxxxxxxxxx")
print(secret.name, secret.status, secret.description)

secret_versions = await secret.list_versions()
async for version in secret_versions:
    print(version)
    if version.id != secret.current_version.id:
        await version.schedule_version_destruction()

payload = await secret.payload()

try:
    value = payload["mykey"]
    print(value.reveal_text_value())
except KeyError:
    print("Invalid key!")

print(payload.get("foo"))  # None if not exists without raising exception
entry = payload[0]  # similar to payload.entries[0]

Authenticate via service account key:

import json

# generate json key for your SA
# yc iam key create --service-account-name my-sa --output key.json

with open("./key.json", "r") as infile:
    credentials = json.load(infile)

lockbox = AsyncYandexLockboxClient(credentials)
async activate_secret(secret_id, raise_for_status=True)[source]#

Activates the specified secret.

Parameters:

  • secret_id (str) – Secret indentifier.

  • raise_for_status (bool) – If set to False returns YandexCloudError instead throw exception. Defaults to True.

Return type:

Coroutine[Any, Any, Operation | YandexCloudError]

async add_secret_version(secret_id, version, raise_for_status=True)[source]#

Adds new version based on a previous one.

Parameters:

  • secret_id (str) – Secret indentifier.

  • version (INewSecretVersion) – A new version object.

  • raise_for_status (bool) – If set to False returns YandexCloudError instead throw exception. Defaults to True.

Return type:

Coroutine[Any, Any, Operation | YandexCloudError]

property auth_headers: dict[str, str]#

Returns headers for authenticate.

async cancel_secret_version_destruction(secret_id, version_id, raise_for_status=True)[source]#

Cancels previously scheduled version destruction, if the version hasn’t been destroyed yet.

Parameters:

  • secret_id (str) – Secret indentifier.

  • version_id (str) – Secret version id to cancel destruction.

  • raise_for_status (bool) – If set to False returns YandexCloudError instead throw exception. Defaults to True.

Return type:

Coroutine[Any, Any, Operation | YandexCloudError]

async create_secret(secret, raise_for_status=True)[source]#

Creates a secret in the specified folder.

Parameters:

  • secret (INewSecret) – A new secret object.

  • raise_for_status (bool) – If set to False returns YandexCloudError instead throw exception. Defaults to True.

Return type:

Coroutine[Any, Any, Operation | YandexCloudError]

async deactivate_secret(secret_id, raise_for_status=True)[source]#

Deactivate a secret.

Parameters:

  • secret_id (str) – Secret indentifier.

  • raise_for_status (bool) – If set to False returns YandexCloudError instead throw exception. Defaults to True.

Return type:

Coroutine[Any, Any, Operation | YandexCloudError]

async delete_secret(secret_id, raise_for_status=True)[source]#

Deletes the specified secret.

Parameters:

  • secret_id (str) – Secret indentifier.

  • raise_for_status (bool) – If set to False returns YandexCloudError instead throw exception. Defaults to True.

Return type:

Coroutine[Any, Any, Operation | YandexCloudError]

enable_async = True#
async get_secret(secret_id, raise_for_status=True)[source]#

Get lockbox secret by ID.

Parameters:

  • secret_id (str) – Secret identifier.

  • raise_for_status (bool) – If set to False returns YandexCloudError instead throw exception. Defaults to True.

Return type:

Coroutine[Any, Any, Secret | YandexCloudError]

async get_secret_payload(secret_id, version_id=None, raise_for_status=True)[source]#

Get lockbox secret payload by ID and optional version.

Parameters:

  • secret_id (str) – Secret identifier.

  • version_id (Optional[str]) – Secret version. Optional.

  • raise_for_status (bool) – If set to False returns YandexCloudError instead throw exception. Defaults to True.

Return type:

Coroutine[Any, Any, SecretPayload | YandexCloudError]

async list_secret_access_bindings(*args, **kwargs)[source]#

Not ready yet.

async list_secret_operations(*args, **kwargs)[source]#

Not ready yet.

async list_secret_versions(secret_id, page_size=100, page_token=None, raise_for_status=True, iterator=False)[source]#

Retrieves the list of versions of the specified secret.

Parameters:

  • secret_id (str) – Secret identifier.

  • page_size (int) – The maximum number of results per page to return. If the number of available results is larger than page_size, the service returns a next_page_token that can be used to get the next page of results in subsequent list requests. Default value: 100. The maximum value is 1000.

  • page_token (Optional[str]) – Page token. To get the next page of results, set page_token to the next_page_token returned by a previous list request.

  • iterator (bool) – Returns all data as iterator (generator) instead paginated result.

Return type:

Union[Coroutine[Any, Any, SecretVersionsList | YandexCloudError], AsyncGenerator[Any, SecretVersion]]

async list_secrets(folder_id, page_size=100, page_token=None, raise_for_status=True, iterator=False)[source]#

Retrieves the list of secrets in the specified folder.

Parameters:

  • folder_id (str) – ID of the folder to list secrets in.

  • page_size (int) – The maximum number of results per page to return. If the number of available results is larger than page_size, the service returns a next_page_token that can be used to get the next page of results in subsequent list requests. Default value: 100. The maximum value is 1000.

  • page_token (Optional[str]) – Page token. To get the next page of results, set page_token to the next_page_token returned by a previous list request.

  • iterator (bool) – Returns all data as iterator (generator) instead paginated result.

Return type:

Union[Coroutine[Any, Any, SecretsList | YandexCloudError], AsyncGenerator[Any, Secret]]

async schedule_secret_version_destruction(secret_id, version_id, pending_period=604800, raise_for_status=True)[source]#

Schedules the specified version for destruction. Scheduled destruction can be cancelled with the cancel_secret_version_destruction() method.

Parameters:

  • secret_id (str) – Secret indentifier.

  • version_id (str) – ID of the version to be destroyed.

  • pending_period (int) – Time interval in seconds between the version destruction request and actual destruction. Default value: 604800 (i.e. 7 days).

  • raise_for_status (bool) – If set to False returns YandexCloudError instead throw exception. Defaults to True.

Return type:

Coroutine[Any, Any, Operation | YandexCloudError]

async set_secret_access_bindings(*args, **kwargs)[source]#

Not ready yet.

async update_secret(secret_id, data, raise_for_status=True)[source]#

Updates the specified secret.

Parameters:

  • secret_id (str) – Secret identifier.

  • data (IUpdateSecret) – A new data for the secret as object. Important. Field mask that specifies which attributes of the secret are going to be updated. A comma-separated names off ALL fields to be updated. Only the specified fields will be changed. The others will be left untouched. If the field is specified in updateMask and no value for that field was sent in the request, the field’s value will be reset to the default. The default value for most fields is null or 0. If updateMask is not sent in the request, all fields values will be updated. Fields specified in the request will be updated to provided values. The rest of the fields will be reset to the default.

  • raise_for_status (bool) – If set to False returns YandexCloudError instead throw exception. Defaults to True.

Return type:

Coroutine[Any, Any, Operation | YandexCloudError]

async update_secret_access_bindings(*args, **kwargs)[source]#

Not ready yet.

class yc_lockbox._auth.YandexAuthClient(credentials, *, auth_base_url=None, **kwargs)[source]#

Bases: AbstractYandexAuthClient

This is a simple client that allows you to get an up-to-date IAM token to make authenticated requests to Yandex Cloud. If you pass a IAM token as credentials, you need to take care of the freshness of the token yourself.

Parameters:

  • credentials (str | dict[str, str]) – Credentials for authenticate requests. Allowed types: service account key, OAuth token, IAM token.

  • auth_base_url (Optional[str]) – Base IAM url without resource path URL.

Note

Important. This client works only in synchronous mode for backward compatibility.

property adapter: HTTPAdapter#

Returns HTTP adapter for communicate with Yandex Cloud.

get_iam_token()[source]#

Cacheable (in-memory, per instance) method for get IAM token from Yandex Cloud.

Return type:

str