API Client

class covata.delta.ApiClient(key_store)[source]

The Delta API Client is an abstraction over the Delta API for execution of requests and responses.

Constructs a new Delta API client with the given configuration.

Parameters:key_store (DeltaKeyStore) – the DeltaKeyStore object
create_secret(requestor_id, content, encryption_details)[source]

Creates a new secret in Delta. The key used for encryption should be encrypted with the key of the authenticating identity.

It is the responsibility of the caller to ensure that the contents and key material in the encryption details are properly represented in a suitable string encoding (such as base64).

Parameters:
  • requestor_id (str) – the authenticating identity id
  • content (str) – the contents of the secret
  • encryption_details (dict[str, str]) – the encryption details
Returns:

the created base secret

Return type:

dict[str, str]

delete_secret(requestor_id, secret_id)[source]

Deletes the secret with the given secret id.

Parameters:
  • requestor_id (str) – the authenticating identity id
  • secret_id (str) – the secret id to be deleted
get_events(requestor_id, secret_id=None, rsa_key_owner_id=None)[source]

Gets a list of events associated filtered by secret id or RSA key owner or both secret id and RSA key owner.

Parameters:
  • requestor_id (str) – the authenticating identity id
  • secret_id (str | None) – the secret id of interest
  • rsa_key_owner_id (str | None) – the rsa key owner id of interest
Returns:

a list of audit events

Return type:

list[dict[str, any]]

get_identities_by_metadata(requestor_id, metadata, page=None, page_size=None)[source]

Gets a list of identities matching the given metadata key and value pairs, bound by the pagination parameters.

Parameters:
  • requestor_id (str) – the authenticating identity id
  • metadata (dict[str, str]) – the metadata key and value pairs to filter
  • page (int | None) – the page number
  • page_size (int | None) – the page size
Returns:

a list of identities satisfying the request

Return type:

list[dict[str, any]]

get_identity(requestor_id, identity_id)[source]

Gets the identity matching the given identity id.

Parameters:
  • requestor_id (str) – the authenticating identity id
  • identity_id (str) – the identity id to retrieve
Returns:

the retrieved identity

Return type:

dict[str, any]

get_secret(requestor_id, secret_id)[source]

Gets the given secret. This does not include the metadata and contents, they need to be made as separate requests, get_secret_metadata() and get_secret_content() respectively.

Parameters:
  • requestor_id (str) – the authenticating identity id
  • secret_id (str) – the secret id to be retrieved
Returns:

the retrieved secret

Return type:

dict[str, any]

get_secret_content(requestor_id, secret_id)[source]

Gets the contents of the given secret.

Parameters:
  • requestor_id (str) – the authenticating identity id
  • secret_id (str) – the secret id to be retrieved
Returns:

the retrieved secret

Return type:

str

get_secret_metadata(requestor_id, secret_id)[source]

Gets the metadata key and value pairs for the given secret.

Parameters:
  • requestor_id (str) – the authenticating identity id
  • secret_id (str) – the secret id to be retrieved
Returns:

the retrieved secret metadata dictionary and version tuple

Return type:

(dict[str, str], int)

get_secrets(requestor_id, base_secret_id=None, created_by=None, rsa_key_owner_id=None, metadata=None, lookup_type=<SecretLookupType.any: 3>, page=None, page_size=None)[source]

Gets a list of secrets based on the query parameters, bound by the pagination parameters.

Parameters:
  • requestor_id (str) – the authenticating identity id
  • base_secret_id (str | None) – the id of the base secret
  • created_by (str | None) – the id of the secret creator
  • rsa_key_owner_id (str | None) – the id of the RSA key owner
  • metadata (dict[str, str] | None) – the metadata associated with the secret
  • lookup_type (SecretLookupType) – the type of the lookup query
  • page (int | None) – the page number
  • page_size (int | None) – the page size
Returns:

a list of secrets satisfying the search criteria

Return type:

list[dict[str, any]]

register_identity(public_encryption_key, public_signing_key, external_id=None, metadata=None)[source]

Creates a new identity in Delta with the provided metadata and external id.

Parameters:
  • public_encryption_key (str) – the public encryption key to associate with the identity
  • public_signing_key (str) – the public signing key to associate with the identity
  • external_id (str | None) – the external id to associate with the identity
  • metadata (dict[str, str] | None) – the metadata to associate with the identity
Returns:

the id of the newly created identity

Return type:

str

share_secret(requestor_id, content, encryption_details, base_secret_id, rsa_key_owner_id)[source]

Shares the base secret with the specified target RSA key owner. The contents must be encrypted with the public encryption key of the RSA key owner, and the encrypted key and initialisation vector must be provided. This call will result in a new derived secret being created and returned as a response.

It is the responsibility of the caller to ensure that the contents and key material in the encryption details are properly represented in a suitable string encoding (such as base64).

Parameters:
  • requestor_id (str) – the authenticating identity id
  • content (str) – the contents of the secret
  • encryption_details (dict[str, str]) – the encryption details
  • base_secret_id (str) – the id of the base secret
  • rsa_key_owner_id (str) – the id of the rsa key owner
Returns:

the created derived secret

Return type:

dict[str, str]

signer(identity_id)[source]

Generates a request signer function for the the authorizing identity.

>>> signer = api_client.signer(authorizing_identity)
Parameters:identity_id (str) – the authorizing identity id
Returns:the request signer function
Return type:(PreparedRequest) -> PreparedRequest
update_identity_metadata(requestor_id, identity_id, metadata, version)[source]

Updates the metadata of the given identity given the version number. The version of an identity’s metadata can be obtained by calling get_identity().

An identity has an initial metadata version of 1.

Parameters:
  • requestor_id (str) – the authenticating identity id
  • identity_id (str) – the identity id to be updated
  • metadata (dict[str, str]) – metadata dictionary
  • version (int) – metadata version, required for optimistic locking
update_secret_metadata(requestor_id, secret_id, metadata, version)[source]

Updates the metadata of the given secret given the version number. The version of a secret’s metadata can be obtained by calling get_secret().

A newly created base secret has a metadata version of 1.

Parameters:
  • requestor_id (str) – the authenticating identity id
  • secret_id (str) – the secret id to be updated
  • metadata (dict[str, str]) – metadata dictionary
  • version (int) – metadata version, required for optimistic locking
class covata.delta.SecretLookupType[source]

Enumerates the applicable secret lookup types.

any = 3

Perform lookup on both base and derived secrets.

base = 1

Restricts lookup to base secrets.

derived = 2

Restricts lookup to derived secrets.