SDKs
Python SDK

Licensefile Setup and Usage

134min

Licensefile Setup

Key and IV setup

To use licensefile inside a python SDK you should first setup your key and IV. Key and IV are used inside Python SDK for encryption and decryption process inside licensefile. This process is only required once at the setup.

Python


Configuration setup

After you have successfully setup your key and IV you should setup your Configuration.

Python


Configuration attributes

  • product (str): product short code.
  • api_key (str): Your unique API key used for authentication with the licensing server.
  • shared_key (str): A shared secret key used alongside the API key for enhanced security during the license verification process.
  • file_key (str): The encryption key used for securing license files on the client side.
  • file_iv (str): The initialization vector for the encryption algorithm. This complements the file_key for encrypting and decrypting license files.
  • hardware_id_provider (object, optional): The provider class used for generating a unique hardware ID. This ID helps in binding the license to specific hardware. Defaults to HardwareIdProvider.
  • verify_license_signature (bool, optional): A boolean flag indicating whether the license's digital signature should be verified. Defaults to True for enhanced security.
  • signature_verifier (object, optional): The class responsible for verifying the digital signature of licenses. Defaults to SignatureVerifier.
  • api_domain (str, optional): The domain name of the API server with which the licensing operations are performed. Defaults to "api.licensespring.com".
  • api_version (str, optional): The version of the API to use for requests. This allows for compatibility with different versions of the licensing API. Defaults to "v4".
  • filename (str, optional): The default filename for saved license files. This can be customized as needed. Defaults to "License".
  • file_path (str, optional): The path where license files should be saved on the client system. If not specified, a default location is used.
  • grace_period_conf (int, optional): The number of hours to allow as a grace period for Defaults to 24 hours.
  • is_guard_file_enabled (bool): Enables guard protection for offline licenses if set to True.
  • air_gap_public_key (str, optional): Air gap public key

LicenseID

Represents a mechanism for license identification and activation, supporting both key-based and user-based activations.

Methods

  • from_key(cls, key) - Class method to create a LicenseID instance for key-based activation
  • from_user(cls, username, password) - Class method to create a LicenseID instance for user-based activation.

Key-based setup

Python


User-based setup

Python


LicenseManager

Manages license activations, supporting a variety of parameters to accommodate different licensing scenarios.

Python


Configuration parametres

  • conf (Configuration): A configuration object

Methods

activate_license

Activates a license with the license server and updates local license data.Returns an instance of the License

Key-based

Python


User-based

Python


There is optional unique_license_id which specifies license_id. It if prefered that given argument is used when activating user based licenses

load_license

Loads the license file and sets attributes for the LicenseData instance. Returns an instance of the License class reflecting the loaded license.

Python


current_config

Get current configuration

Python


Returns (dict): Current configuration

reconfigure

Change the current configuration

Python


is_license_file_corrupted

Checks if licensefile is corrupted

Python


Returns (bool): If the file is corrupted return True, otherwise False

clear_local_storage

Delete all files for given product

Python


data_location

Get licensefile location

Python


Returns (str): Licensefile location

set_data_location

Set data location

Parameters:

  • path (str): new data location path
Python


Return: None

license_file_name

Get licensefile name

Python


Returns (str): licensefile name

set_license_file_name

Set licensefile name

Parameters:

  • name (str): license file name
Python


Return: None

is_online

Checks if the licensing server is accessible.

Parameters:

  • throw_e: (bool,optional): If True throws exception, otherwise exception won't be raised.
Python


Returns: True if online, False otherwise.

create_offline_activation_file

Creates request file for offline activation.

Parameters:

  • license_id(LicenseID):
  • req_path(str): path where .req file is created
Python


Returns(str): path to request file

activate_license_offline

Activates the .lic file

Parameters:

  • ls_activation_path(str): path to .lic file
Python


Raises:

  • LicenseActivationException: Activation data is not valid
  • LicenseActivationException: Response file ID mismatch
  • LicenseActivationException: License does not belong to this device

Returns (License): License object

get_air_gap_activation_code

Get activation code for air gap license

Parameters:

  • initialization_code (str): initialization code
  • license_key (str): license key
Python


Return (str): activation code

activate_air_gap_license

Activates air gap license

Parameters:

  • confirmation_code (str): confirmation code
  • policy_path (str): policy path (file or folder)
  • license_key (str): license_key
  • policy_id (str): policy id
Python


Raises:

  • LicenseActivationException: Signature verification failed

Return (License): License

get_trial_license

Creates LiceseID for trial licenses

Parameters:

  • customer (Customer): Customer object
  • license_policy(str,optional): icense policy code. Defaults to None.
Python


Return(LicenseID): Returns a LicenseID object.

get_version_list

Get versions

Parameters:

  • license_id (LicenseID): license id object
  • bundle_code (str,optional): specify unique bundle_code of a bundle
  • unique_license_id (int,optional): A unique identifier for the license.
  • env (str,optional): Version of environment
Python


Return(list): List of versions

get_installation_file

Get installation file

Parameters:

  • license_id (LicenseID): An instance containing the license key or user credentials
  • bundle_code (str, optional): specify unique bundle_code of a bundle
  • unique_license_id (int, optional): A unique identifier for the license.
  • env (str, optional): Version of environment
  • version (str, optional): Versions
Python


Return (dict): installation file

get_customer_license_users

Get customer license users

Parameters:

  • customer (Customer): customer
Python


Return(dict): customer license user

get_user_licenses

Get user licenses

Parameters:

  • license_id (LicenseID): license_id
manager = LicenseManager(conf) license_id = LicenseID.from_user(username="[email protected]", password="d#2!17vi") response = manager.get_user_licenses(license_id)

Return(list): User licenses

License

Object responsible for license operations

Methods

is_floating_expired

Determines wheter the license floating period has expired

Python


Return (bool): True if floating expired otherwise False

floating_timeout

Retrieve license flaoting timeout

Python


Return (int): License floating timeout

is_floating

Check if license is floating (Floating Server or Floating Cloud)

Python


Return (bool): True if license if floating, otherwise False

floating_client_id

Get floating client id

Python


Return (str): Floating client id

is_controlled_by_floating_server

Check if license is controlled by Floating Server

Python


Return (bool): True if license is controlled by floating server, otherwise False

floating_in_use_devices

Number of floating devices in use

Python


Return (int): Number of floating devices in use

floating_end_date

Datetime when floating will be released

Python


Return (datetime): Datetime when device will be released

max_floating_users

Number of max floating users

Python


Return (int): Number of max floating users

is_validity_period_expired

Determines whether the license's validity period has expired

Python


Return (bool): True if license expired otherwise False

license_user

Gets the license user

Python


Return (dict): license user

is_grace_period_started

Checks if grace period has started

Python


Return (bool): True if grace period has started, otherwise False

grace_period_hours_remaining

Get remain hours of grace period

Python


Return (int): Number of hours left in grace period

validity_period

Gets the license validity period

Python


Return (datetime): Datetime in UTC

validity_with_grace_period

Gets the validity period with grace period of the license

Python


Return (datetime): Datetime in UTC

maintenance_days_remaining

Gets how many days are left until the maintenance ends

Python


Return (int): Maintenance days left

days_remaining

Gets how many days are left until the validity period ends

Python


Return (int): Validity period days left

customer_information

Gets customer information

Python


Return (dict): Customer information

id

Gets a license id

Python


Return (int): license id

max_transfers

Get a license max transfers

Python


Return (int): max transfers

transfer_count

Get the transfer count

Python


Return (int): transfer count

is_device_transfer_allowed

Get if a device transfer is allowed

Python


Return (bool): True if device transfer is allowed otherwise False

is_device_transfer_limited

Get if a device transfer is limited

Python


Return (bool): True if device transfer is limited otherwise False

days_since_last_check

Get how many days passed since the last check

Python


Return (int): How many days have passed since last check

start_date

Get a license start date

Python


Return (datetime): Datetime in UTC

maintenance_period

Get a license maintenance period

Python


Return (datetime): Datetime in UTC

is_maintence_period_expired

Checks if maintence period has expired

Python


Return (bool): If maintence period expired returns True otherwise False

last_check

Get when last check was performed

Python


Return (datetime): Datetime in UTC

last_usage

Gets a license last usage

Python


Return (datetime): Datetime in UTC

license_type

Gets the last license usage

Python


Return (str): license_type

max_activations

Gets the license max activations

Python


Return (int): max activations

metadata

Gets the license metadata

Python


Return (dict): metadata

allow_unlimited_activations

Check if unlimited activations are allowed

Python


Return (bool): If unlimited activations are allowed returns True otherwise False

allow_grace_subscription_period

Check if grace subscription period is allowed

Python


Return (bool): If grace subscription period is allowed returns True otherwise False

is_subscription_grace_period_started

Check if grace subscription period has started

Python


Return (bool): If grace subscription period has started returns True otherwise False

get_grace_period

Get grace period

Python


Return (int): Grace period

subscription_grace_period

Get subscription grace period

Python


Return (int): Subscription grace period

is_expired

Checks if a license validity has expired

Python


Return (bool): True if license has expired otherwise False

license_enabled

Checks if a license is enabled

Python


Return (bool): True if license is enabled otherwise False

license_active

Checks if a license is active

Python


Return (bool): True if license is active otherwise False

is_valid

Checks if the license is valid (license is active, enabled and didn't expired)

Python


Return (bool): True if a license is valid otherwise False

prevent_vm

Checks if a license prevents virtual machines

Python


Return (bool): True if license prevents VM's otherwise False

is_trial

Checks if a license is trial

Python


Return (bool): True if a license is trial otherwise False

expiry_date

Get the expiry date of a floating license

Python


Return (datetime): Expiry date in UTC

borrow_until

Get the date until a license is borrwed

Python


Return (datetime): borrow date in UTC

is_borrowed

Check if a license is borrowed

Python


Return (bool): True if license is borrowed otherwise False

local_consumptions

Get local consumptions

Python


Return (int): Local consumptions

max_consumptions

Get max consumptions

Python


Return (int): max consumptions

total_consumptions

Get total consumptions

Python


Return (int): total consumptions

max_overages

Get max overages

Python


Return (int): max overages

allow_unlimited_consumptions

Check if unlimited consumptions are allowed

Python


Return (bool): If unlimited consumptions allowed return True otherwise False

consumption_reset

Check if there is consumption reset

Python


Return (bool): If there is consumption reset returns True otherwise False

allow_overages

Check if overages are allowed

Python


Return (bool): If overages are allowed returns True otherwise False

consumption_period

Get consumption period

Python


Return (str): Consumption period

get_feature_data

Get feature data

Parameters:

  • feature_code (str): feature code
Python


Return (dict): Feature

check_license_status

Verifies the current status of the license. It raises exceptions if the license is not enabled, not active, or expired

Python


Raises:

LicenseStateException: Raised if the license fails one of the following checks:

  • License is not enabled.
  • License is not active.
  • License validity period has expired.

Return: None

check

Performs an online check to synchronize the license data with the backend. This includes syncing consumptions for consumption-based licenses.

Parameters:

  • include_expired_features (bool, optional): Includes expired license features in the check.
Python


Raises:

ClientError: Raised if there's an issue with the API client's request, such as invalid credentials or unauthorized access.

RequestException: Raised if there's a problem with the request to the licensing server, such as network issues or server unavailability.

Return (dict): The updated license cache.

deactivate

Deactivates the license and optionally deletes the local license file.

Parameters:

  • delete_license (bool, optional): If True, deletes the local license file upon deactivation.
Python


Return: None

local_check

This method ensures the integrity and consistency of the licensing information by comparing the data stored in the local license file with the predefined configurations in the Configuration object.

Python


Raises:

ConfigurationMismatch: Raised if the product code or hardware ID in the license file does not match the expected values provided in the Configuration

VMIsNotAllowedException: Raised if the license is used in a VM environment when the license explicitly disallows it.

TimeoutExpiredException: Raised if a floating license has expired. This is more relevant if is_floating_expired is later implemented to perform actual checks.

ClockTamperedException: Raised if there is evidence of tampering with the system's clock, detected by comparing the system's current time with the last usage time recorded in the license file.

Return: None

add_local_consumption

Adds local consumption records for consumption-based licenses.

Parameters:

  • consumptions (int, optional): The number of consumptions to add locally.
Python


Raises:

LicenseSpringTypeError: Raised if the license type does not support consumption (i.e., not a consumption-based license).

ConsumptionError: Raised if adding the specified number of consumptions would exceed the allowed maximum for the license.

Return: None

sync_consumption

Synchronizes local consumption data with the server, adjusting for overages if specified.

Parameters:

  • req_overages (int, optional): Specifies behavior for consumption overages.
Python


Raises:

RequestException: Raised if the request to synchronize consumption data with the server fails, for instance, due to network issues or server unavailability.

Return (bool): True if the consumption data was successfully synchronized; False otherwise.

is_grace_period

Determines if the current license state is within its grace period following a specific exception.

Parameters:

  • ex (Exception): Raised Exception
Python


Return (bool): True if the license is within its grace period, False otherwise

change_password

Changes password of a user

Python


Return (str): "password_changed"

add_local_feature_consumption

Adds local consumption to the feature.

Parameters:

  • feature (str): feature code.
  • consumptions (int,optional): Number of consumptions.
Python


Raises:

ItemNotFoundError: If the feature specified by `feature_code` does not exist.

LicenseSpringTypeError: If the identified feature is not of the "consumption" type.

ConsumptionError: If adding the specified number of consumptions would exceed the feature's consumption limits.

Return: None

sync_feature_consumption

Synchronizes local consumption data with the server.

Parameters:

  • feature (str): feature code.
Python


Raises:

RequestException: Raised if the request to synchronize consumption data with the server fails, for instance, due to network issues or server unavailability.

Return (bool): True if the consumption data was successfully synchronized; False otherwise.

floating_borrow

Attempts to borrow a floating license until the specified date.

Parameters:

  • borrow_until(str): A string representing the date until which the license should be borrowed.
Python


Return: None

floating_release

Releases a borrowed floating license and updates the license status accordingly.

Parameters:

  • throw_e(bool): A boolean indicating whether to raise an exception on failure.
Python


Raises:

Exception

Return: None

check_feature

Checks for a specific license feature and updates the license cache accordingly.

Parameters:

  • feature(str): feature code.
  • add_to_watchdog (bool,optional): A boolean indicating whether to add the feature check to a watchdog routine. Default is False



Python


Raises:

Exception

Return: None

release_feature

Releases a borrowed license feature and updates the license cache accordingly.

Parameters:

  • feature(str): feature code.
Python


Raises:

Exception

Return: None

update_offline

Updates license via refresh file

Parameters:

  • path (str): path of the refresh file
  • reset_consumption (bool): True resets consumption otherwise False
Python


Raises:

  • ConfigurationMismatch: The update file does not belong to this device
  • ConfigurationMismatch: The update file does not belong to this product

Return (bool): True if license was successfully updated otherwise False

deactivate_offline

Generates .req file for the offline deactivation

Parameters:

  • offline_path (str): path of the .req file
Python


Return (str): path of the deactivation file

get_deactivation_code

Get deactivation code for air gap licenses

Parameters:

  • initialization_code (str): initialization_code
Python


Return (str): deactivation code

deactivate_air_gap

Deactivate air gap license and clear storage

Parameters:

  • confirmation_code (str): confirmation_code
Python


Raises:

  • LicenseActivationException: VerificationError

Return: None

product_details

Update product details from LicenseSpring server

Parameters:

  • include_custom_fields(bool, optional): custom fields information. Defaults to False.
  • include_latest_version(bool, optional): Lateset version information. Defaults to False.
Python


Return(dict): response

get_product_details

Get product details from Licensefile

Python


Return(dict): Product details

get_device_variable

Get device variable if exists

Parameters:

  • variable_name(str): variable name
Python


Return(dict): variable dictionary

set_device_variables

Set device variables locally

Parameters:

  • variables(dict): variables dict
  • save(bool, optional): Save cache to licensefile. Defaults to True.
Python


Return: None

get_device_variables

Get device variables from server or locally

Parameters:

  • get_from_be(bool, optional): If True collects data from LicenseSpring server. Defaults to True.
Python


Return(list): List of device variables

send_device_variables

Send device variables to LicenseSpring server. Handles GracePeriod

Parameters:

  • variables(dict): variables dict
  • save(bool, optional): Save cache to licensefile. Defaults to True.
Python


Return(bool): True if new variables are sent to LicenseSpring server otherwise, False

custom_fields

Get custom fields from licensefile

Python


Return(list): Custom fields

Updated 17 Oct 2024
Doc contributor
Doc contributor
Did this page help you?
PREVIOUS
API Client Usage Examples
NEXT
Python Hardware (Device) IDs
Docs powered by Archbee