The Account Server API

A module providing simplified assess to the Squonk2 Account Server API.

The API URL

The URL to the Account Server API is taken from the environment variable SQUONK2_ASAPI_URL if it exists. If you do not want to verify the SSL certificate you can also set SQUONK2_ASAPI_VERIFY_SSL_CERT to anything other than "yes", its default value.

If you haven’t set the API URL variables you need to set the Account Server API URL before you can use any API method.

url = 'https://example.com/account-server-api'
AsApi.set_api_url(url)

If the Account Server API is not secure (e.g. you’re developing locally) you can disable the automatic SSL authentication when you set the URL.

AsApi.set_api_url(url, verify_ssl_cert=False)

The API

Python utilities to simplify calls to some parts of the Account Server API that interact with Organisations, Units, Products and Assets.

Note

The URL to the DM API is automatically picked up from the environment variable SQUONK2_ASAPI_URL, expected to be of the form https://example.com/account-server-api. If the variable isn’t set the user must set it programmatically using AsApi.set_api_url().

class squonk2.as_api.AsApi

The AsApi class provides high-level, simplified access to the AS REST API. You can use the request module directly for finer control. This module provides a wrapper around the handling of the request, returning a simplified namedtuple response value ApiRv

classmethod add_user_to_organisation(access_token: str, *, org_id: str, username: str, timeout_s: int = 4) → ApiRv

Adds a User to an Organisation.

You will need admin privileges or be a member of the organisation to do this.

Parameters

access_token – A valid AS API access token
org_id – The Organisation ID
username – The user to add
timeout_s – The underlying request timeout

classmethod add_user_to_unit(access_token: str, *, unit_id: str, username: str, timeout_s: int = 4) → ApiRv

Adds a User to a Unit.

You will need admin privileges or be a member of the organisation or unit to do this.

Parameters

access_token – A valid AS API access token
unit_id – The Unit ID
username – The user to add
timeout_s – The underlying request timeout

classmethod alter_asset(access_token: str, *, asset_id: str, description: Optional[str] = None, content_string: Optional[str] = None, content_file: Optional[Path] = None, timeout_s: int = 4) → ApiRv: Alters an Asset. An asset’s value can be changed along with its description.

classmethod alter_organisation(access_token: str, *, org_id: str, name: Optional[str] = None, default_product_privacy: Optional[DefaultProductPrivacyEnum] = None, timeout_s: int = 4) → ApiRv: Alters an existing Organisation.

classmethod alter_product(access_token: str, *, product_id: str, product_name: Optional[str] = None, allowance: Optional[int] = None, limit: Optional[int] = None, timeout_s: int = 4) → ApiRv: Alters an existing Product.

classmethod alter_unit(access_token: str, *, unit_id: str, name: Optional[str] = None, default_product_privacy: Optional[DefaultProductPrivacyEnum] = None, timeout_s: int = 4) → ApiRv: Alters an existing Unit.

classmethod attach_asset(access_token: str, *, asset_id: str, m_id: int, timeout_s: int = 4) → ApiRv: Disables an existing asset

classmethod create_asset(access_token: str, *, name: str, description: str, scope: AssetScopeEnum, content_string: Optional[str] = None, content_file: Optional[Path] = None, scope_id: Optional[str] = None, is_secret: bool = False, timeout_s: int = 4) → ApiRv: Create an Asset from a string or file (not both).

classmethod create_event_stream(access_token: str, *, event_format: EventStreamFormat, timeout_s: int = 4) → ApiRv

Creates an Event Stream.

Parameters

access_token – A valid AS API access token
format – The event format enumeration
timeout_s – The underlying request timeout

classmethod create_organisation(access_token: str, *, org_name: str, org_owner: str, timeout_s: int = 4) → ApiRv

Creates an Organisation. You need to provide a name and an owner.

You will need admin privileges to do this.

Parameters

access_token – A valid AS API access token
org_name – The name to give the Organisation
org_owner – The Organisation owner
billing_day – A billing day (1..28)
timeout_s – The underlying request timeout

classmethod create_personal_unit(access_token: str, *, billing_day: int, timeout_s: int = 4) → ApiRv

Creates a Personal Unit

Parameters

access_token – A valid AS API access token
billing_day – A billing day (1..28)
timeout_s – The underlying request timeout

classmethod create_product(access_token: str, *, product_name: str, unit_id: str, product_type: str, allowance: int = 0, limit: int = 0, flavour: str = '', timeout_s: int = 4) → ApiRv

Creates a Product in a Unit.

You will need to be a member of the Organisation or Unit to use this method.

Parameters

access_token – A valid AS API access token
product_name – The name to assign to the Product
unit_id – The Unit UUID for the Product
product_type – The product type, e.g. “DATA_MANAGER_PROJECT_TIER_SUBSCRIPTION”
allowance – The coin allowance for the product
limit – The coin limit for the product
flavour – The product flavour (for products that support flavours)
timeout_s – The underlying request timeout

classmethod create_unit(access_token: str, *, unit_name: str, org_id: str, billing_day: int, timeout_s: int = 4) → ApiRv

Creates a Unit for a given an Organisation. You need to provide a name and billing day - a day in the month to bill all the subscription-based products created for the Unit.

You will need to be a member of the Organisation to use this method.

Parameters

access_token – A valid AS API access token
unit_name – The name to give the Unit
org_id – The Organisation UUID for the Unit
billing_day – A billing day (1..28)
timeout_s – The underlying request timeout

classmethod delete_asset(access_token: str, *, asset_id: str, timeout_s: int = 4) → ApiRv: Deletes an existing asset

classmethod delete_event_stream(access_token: str, *, event_stream_id: int, timeout_s: int = 4) → ApiRv

Creates an Event Stream.

Parameters

access_token – A valid AS API access token
format – The event format enumeration
timeout_s – The underlying request timeout

classmethod delete_organisation(access_token: str, *, org_id: str, timeout_s: int = 4) → ApiRv

Deletes an Organisation.

You will need admin privileges to do this.

Parameters

access_token – A valid AS API access token
org_id – The UUID of the organisation
timeout_s – The underlying request timeout

classmethod delete_personal_unit(access_token: str, *, timeout_s: int = 4) → ApiRv

Deletes a Personal Unit

Parameters

access_token – A valid AS API access token
timeout_s – The underlying request timeout

classmethod delete_product(access_token: str, *, product_id: str, timeout_s: int = 4) → ApiRv

Deletes a Product in a Unit.

You will need to be a member of the Organisation or Unit to use this method.

Parameters

access_token – A valid AS API access token
product_id – The Unit UUID for the Product
timeout_s – The underlying request timeout

classmethod delete_unit(access_token: str, *, unit_id: str, timeout_s: int = 4) → ApiRv

Deletes a Product in a Unit.

You will need to be a member of the Organisation or Unit to use this method.

Parameters

access_token – A valid AS API access token
unit_id – The Unit UUID for the Product
timeout_s – The underlying request timeout

classmethod detach_asset(access_token: str, *, asset_id: str, m_id: int, timeout_s: int = 4) → ApiRv: Disables an existing asset

classmethod disable_asset(access_token: str, *, asset_id: str, timeout_s: int = 4) → ApiRv: Disables an existing asset

classmethod enable_asset(access_token: str, *, asset_id: str, timeout_s: int = 4) → ApiRv: Disables an existing asset

classmethod get_account(access_token: str, *, timeout_s: int = 4) → ApiRv

Gets your User account.

You will need admin rights on the Account Server to use this method.

Parameters

access_token – A valid AS API access token
timeout_s – The underlying request timeout

classmethod get_api_url() → Tuple[str, bool]: Return the API URL and whether validating the SSL layer.

classmethod get_asset(access_token: str, *, asset_id: str, timeout_s: int = 4) → ApiRv: Disables an existing asset

classmethod get_available_assets(access_token: str, *, scope_id: Optional[str] = None, timeout_s: int = 4) → ApiRv

Returns Assets you have access to. If you provide a scope ID (a username or a product, unit or org UUID) only assets available in that scope will be returned.

Parameters

access_token – A valid AS API access token
scope_id – Optional scope identity (User or Product, Unit or Org UUID)
timeout_s – The underlying request timeout

classmethod get_available_products(access_token: str, *, timeout_s: int = 4) → ApiRv

Returns Products you have access to.

Parameters

access_token – A valid AS API access token
timeout_s – The underlying request timeout

classmethod get_available_units(access_token: str, *, timeout_s: int = 4) → ApiRv

Returns Units (and their Organisations) you have access to.

Parameters

access_token – A valid AS API access token
timeout_s – The underlying request timeout

classmethod get_default_organisation(access_token: str, *, timeout_s: int = 4) → ApiRv

Gets the Default Organisation.

Parameters

access_token – A valid AS API access token
timeout_s – The underlying request timeout

classmethod get_event_stream(access_token: str, *, timeout_s: int = 4) → ApiRv

Returns the AS-API Event Stream for a user (if there is one).

Parameters

access_token – A valid AS API access token
timeout_s – The underlying request timeout

classmethod get_event_stream_version(*, timeout_s: int = 4) → ApiRv

Returns the AS-API Event Stream Service version.

Parameters: timeout_s – The underlying request timeout

classmethod get_merchant(access_token: str, merchant_id: int, *, timeout_s: int = 4) → ApiRv

Returns the given Merchant.

Parameters

access_token – A valid AS API access token
merchant_id – A merchant ID
timeout_s – The underlying request timeout

classmethod get_merchants(access_token: str, *, timeout_s: int = 4) → ApiRv

Returns Merchants known (registered) with the Account Server.

Parameters

access_token – A valid AS API access token
timeout_s – The underlying request timeout

classmethod get_organisation(access_token: str, *, org_id: str, timeout_s: int = 4) → ApiRv

Gets an Organisation.

You will need to be a member of the Organisation to use this method.

Parameters

access_token – A valid AS API access token
org_id – The Organisation UUID
timeout_s – The underlying request timeout

classmethod get_organisation_charges(access_token: str, *, org_id: str, from_: Optional[date] = None, until: Optional[date] = None, pbp: Optional[int] = None, timeout_s: int = 4) → ApiRv

Returns charges for a given Organisation. If from and until are omitted charges for the current billing period are returned.

You will need admin rights on the Account Server to use this method.

Parameters

access_token – A valid AS API access token
org_id – The UUID of the Organisation
from – An optional date where charges are to start (inclusive)
until – An optional date where charges are to end (exclusive)
pbp – An optional prior billing period
timeout_s – The underlying request timeout

classmethod get_organisation_units(access_token: str, *, org_id: str, timeout_s: int = 4) → ApiRv

Gets all Units available to you for an organisation.

You will need to be a member of the Organisation or Unit to use this method.

Parameters

access_token – A valid AS API access token
org_id – The Organisation UUID for the Unit
timeout_s – The underlying request timeout

classmethod get_organisation_users(access_token: str, *, org_id: str, timeout_s: int = 4) → ApiRv

Gets users in an Organisation.

You will need admin rights on the Account Server to use this method.

Parameters

access_token – A valid AS API access token
org_id – The UUID of the Organisation
timeout_s – The underlying request timeout

classmethod get_organisations(access_token: str, *, org_name: Optional[str] = None, timeout_s: int = 4) → ApiRv

Gets all the Organisations you can see. if you provide a name the Organisation you name will be returned (if you are a member of it).

Parameters

access_token – A valid AS API access token
timeout_s – The underlying request timeout

classmethod get_personal_unit(access_token: str, *, timeout_s: int = 4) → ApiRv

Gets a Personal Unit

Parameters

access_token – A valid AS API access token
timeout_s – The underlying request timeout

classmethod get_product(access_token: str, *, product_id: str, timeout_s: int = 4) → ApiRv

Returns details for a given Product.

Parameters

access_token – A valid AS API access token
product_id – The UUID of the Product
timeout_s – The underlying request timeout

classmethod get_product_charges(access_token: str, *, product_id: str, from_: Optional[date] = None, until: Optional[date] = None, pbp: Optional[int] = None, timeout_s: int = 4) → ApiRv

Returns charges for a given Product. If from and until are omitted charges for the current billing period are returned.

You will need admin rights on the Account Server to use this method.

Parameters

access_token – A valid AS API access token
product_id – The UUID of the Product
from – An optional date where charges are to start (inclusive)
until – An optional date where charges are to end (exclusive)
pbp – An optional prior billing period
timeout_s – The underlying request timeout

classmethod get_product_default_storage_cost(access_token: str, *, timeout_s: int = 4) → ApiRv

Returns the default product storage.

Parameters

access_token – A valid AS API access token
timeout_s – The underlying request timeout

classmethod get_product_types(access_token: str, *, timeout_s: int = 4) → ApiRv

Returns known product types.

Parameters

access_token – A valid AS API access token
timeout_s – The underlying request timeout

classmethod get_products_for_organisation(access_token: str, *, org_id: str, timeout_s: int = 4) → ApiRv

Returns Products for a given Organisation.

Parameters

access_token – A valid AS API access token
org_id – The UUID of the Organisation
timeout_s – The underlying request timeout

classmethod get_products_for_unit(access_token: str, *, unit_id: str, timeout_s: int = 4) → ApiRv

Returns Products for a given Unit.

Parameters

access_token – A valid AS API access token
unit_id – The UUID of the Unit
timeout_s – The underlying request timeout

classmethod get_unit(access_token: str, *, unit_id: str, timeout_s: int = 4) → ApiRv

Gets a Unit.

You will need to be a member of the Organisation or Unit to use this method.

Parameters

access_token – A valid AS API access token
unit_id – The UUID for the Unit
timeout_s – The underlying request timeout

classmethod get_unit_charges(access_token: str, *, unit_id: str, from_: Optional[date] = None, until: Optional[date] = None, pbp: Optional[int] = None, timeout_s: int = 4) → ApiRv

Returns charges for a given Product. If from and until are omitted charges for the current billing period are returned.

You will need admin rights on the Account Server to use this method.

Parameters

access_token – A valid AS API access token
product_id – The UUID of the Product
from – An optional date where charges are to start (inclusive)
until – An optional date where charges are to end (exclusive)
pbp – An optional prior billing period
timeout_s – The underlying request timeout

classmethod get_unit_users(access_token: str, *, unit_id: str, timeout_s: int = 4) → ApiRv

Gets users in a Unit.

You will need admin rights on the Account Server to use this method.

Parameters

access_token – A valid AS API access token
unit_id – The UUID of the Unit
timeout_s – The underlying request timeout

classmethod get_units(access_token: str, *, unit_name: Optional[str] = None, timeout_s: int = 4) → ApiRv

Gets all Units available to you or by name.

You will need to be a member of the Organisation or Unit to use this method.

Parameters

access_token – A valid AS API access token
org_id – The Organisation UUID for the Unit
timeout_s – The underlying request timeout

classmethod get_version(*, timeout_s: int = 4) → ApiRv

Returns the AS-API service version.

Parameters: timeout_s – The underlying request timeout

classmethod ping(*, timeout_s: int = 4) → ApiRv

A handy API method that calls the AS API to ensure the server is responding.

Parameters: timeout_s – The underlying request timeout

classmethod remove_user_from_organisation(access_token: str, *, org_id: str, username: str, timeout_s: int = 4) → ApiRv

Removes a User from an Organisation.

You will need admin privileges or be a member of the organisation to do this.

Parameters

access_token – A valid AS API access token
org_id – The Organisation ID
username – The user to add
timeout_s – The underlying request timeout

classmethod remove_user_from_unit(access_token: str, *, unit_id: str, username: str, timeout_s: int = 4) → ApiRv

Removes a User from a Unit.

You will need admin privileges or be a member of the organisation or unit to do this.

Parameters

access_token – A valid AS API access token
unit_id – The Unit ID
username – The user to add
timeout_s – The underlying request timeout

classmethod set_api_url(url: str, *, verify_ssl_cert: bool = True) → None

Replaces the API URL value, which is otherwise set using the SQUONK2_ASAPI_URL environment variable.

Parameters

url – The API endpoint, typically https://example.com/account-server-api
verify_ssl_cert – Use False to avoid SSL verification in request calls

class squonk2.as_api.AssetScopeEnum(value): Enumeration of Asset scopes

class squonk2.as_api.DefaultProductPrivacyEnum(value): Enumeration of Default product Privacy

class squonk2.as_api.EventStreamFormat(value): Enumeration of EventStream formats