xq.api package

Module contents

class xq.api.XQAPI(api_key=None, dashboard_api_key=None, api_base_uri='xqmsg.net/v2/')

Bases: object

add_contact(firstName: str, lastName: str, email: str, title: str, role: int, notifications: int = 0, overflow: bool = False)

add_packet(encrypted_key_packet: bytes)

upload an encrypted key packet to XQ https://xq.stoplight.io/docs/xqmsg/b3A6NDE4NTY2NDE-add-a-new-key-packet

Parameters:

api (XQAPI) – XQAPI instance
encrypted_key_packet (bytes) – key packet to upload

Raises:

XQException – packet creation failed

Returns:

locator token to access key later

Return type:

string

api_delete(serviceEndpoint, subdomain)

static method for interacting with XQ API DELETE endpoints

Parameters:

serviceEndpoint (string) – uri service extension to hit
subdomain (string) – subdomain of uri to use, api specific

Returns:

status code, response

Return type:

tuple(int, string)

api_get(serviceEndpoint, subdomain, params={})

static method for interacting with the XQ API GET endpoints

Parameters:

serviceEndpoint (string) – uri service extension to hit
subdomain (string) – subdomain of uri to use, api specific
params (dict) – optional parameters to pass, defaults to {}
headers (dict) – optional headers to pass, defaults to {}

Returns:

requests obj

Return type:

requests response

api_patch(serviceEndpoint, subdomain, data=None, json=None)

static method for interacting with XQ API PATCH endpoints

Parameters:

serviceEndpoint (string) – uri service extension to hit
subdomain (string) – subdomain of uri to use, api specific
data (dict, optional) – optional parameters to pass, defaults to None
json (dict, optional) – optional parameters to pass, POSTS as json contenttype, defaults to None

Returns:

status code, response

Return type:

tuple(int, string)

api_post(serviceEndpoint, subdomain, json=None, data=None)

static method for interacting with XQ API POST endpoints

Parameters:

serviceEndpoint (string) – uri service extension to hit
subdomain (string) – subdomain of uri to use, api specific
json (dict, optional) – optional parameters to pass, POSTS as json contenttype, defaults to None
data (dict, optional) – optional parameters to pass, defaults to None

Returns:

status code, response

Return type:

tuple(int, string)

api_put(serviceEndpoint, subdomain, json=None, data=None)

static method for interacting with XQ API PUT endpoints

Parameters:

serviceEndpoint (string) – uri service extension to hit
subdomain (string) – subdomain of uri to use, api specific
json (dict, optional) – optional parameters to pass, POSTS as json contenttype, defaults to None
data (dict, optional) – optional parameters to pass, defaults to None

Returns:

status code, response

Return type:

tuple(int, string)

authorize_alias(user_email: str, firstName: str, lastName: str)

request an access token for the given user information https://subscription.xqmsg.net/v2/authorizealias

Parameters:

api (XQAPI) – XQAPI instance
user_email (str) – email address of user requesting access token
firstName (str) – first name of user
lastName (str) – last name of user

Returns:

access token

Return type:

str

authorize_user(user_email: str, firstName: str, lastName: str, newsletter=False, notifications=0)

request pre-auth token for a given email address, this token will need to be exchanged for an access token https://xq.stoplight.io/docs/xqmsg/b3A6NDA5MDAxNDE-request-access-for-a-user

Parameters:

api (XQAPI) – XQAPI instance
user_email (str) – email address of user requesting access token
firstName (str) – first name of user
lastName (str) – last name of user
newsletter (bool, optional) – subscribe to newsletter, defaults to False
notifications (int, optional) – notification level: 0 = No Notifications, 1 = Receive Usage Reports, 2 = Receive Tutorials, 3 = Receive Both, defaults to 0

Returns:

pre-aut token, which can be exchanged for an access token

Return type:

str

code_validate(pin: int)

validate the provided 2FA pin https://xq.stoplight.io/docs/xqmsg/b3A6NDA5MjQ1MjM-validate-access-request-with-a-pin

Parameters:

api (XQAPI) – XQAPI instance
pin (int) – 2FA code

Raises:

XQException – invalid pin

Returns:

isvalid? boolean response

Return type:

bool

create_and_store_packet(recipients: list, expires_hours: int = 24, key: bytes | None = None, type: int = 2, subject: str | None = None)

creates an encrypted packet from a secret key https://xq.stoplight.io/docs/xqmsg/1f9bc1713a7cd-create-and-save-a-new-key-packet

Parameters:

api (XQAPI) – XQAPI instance
recipients (list) – list of emails to grant access to
expires_hours (int, optional) – packet validation time in hours, defaults to 24
key (bytes, optional) – secret key to encrypt, defaults to None

Raises:

XQException – failed packet creation

Returns:

api response, the encrypted packet

Return type:

text

create_and_store_packets(recipients: list, expires_hours: int = 24, keys: list | None = None, type: int = 5, subject: str | None = None, meta: str | None = None)

creates an encrypted packet from a secret key https://xq.stoplight.io/docs/xqmsg/1f9bc1713a7cd-create-and-save-a-new-key-packet

Parameters:

api (XQAPI) – XQAPI instance
recipients (list) – list of emails to grant access to
expires_hours (int, optional) – packet validation time in hours, defaults to 24
key (bytes, optional) – secret key to encrypt, defaults to None

Raises:

XQException – failed packet creation

Returns:

api response, the encrypted packet

Return type:

text

create_packet(recipients: list, expires_hours: int = 24, key: bytes | None = None, type: int = 3, subject: str | None = None)

creates an encrypted packet from a secret key https://xq.stoplight.io/docs/xqmsg/b3A6NDA5MDQ5MTY-create-a-new-key-packet

Parameters:

api (XQAPI) – XQAPI instance
recipients (list) – list of emails to grant access to
expires_hours (int, optional) – packet validation time in hours, defaults to 24
key (bytes, optional) – secret key to encrypt, defaults to None

Raises:

XQException – failed packet creation

Returns:

api response, the encrypted packet

Return type:

text

create_usergroup(name: str, members: List[str])

create a usergroup

Parameters:

api (XQAPI) – XQAPI instance
name (str) – name of usergroup
members (List[str]) – list of member emails to add to group

Raises:

XQException – error creating usergroup

Returns:

usergroup

Return type:

dict

dashboard_login(password: str, email: str | None = None, method: int = 1, workspace: str | None = None)

log a given user into their dashboard account https://xq.stoplight.io/docs/xqmsg/b3A6NDEyMDYwMDM-login-to-the-dashboard

Parameters:

api (XQAPI) – XQAPI instance
email (str, optional) – email address of authenticating user, defaults to None
password (str) – password or magic link for user account
method (int, optional) – authentication method (0 = user/password, 1 = OAuth Token), defaults to 0
workspace (string, optional - DEPRECATED) – the account workspace. This field is deprecated and should not be used., defaults to None

Raises:

XQException – authentication error with request

Returns:

user access token

Return type:

string

dashboard_signup(email: str, password: str | None = None, emailOptIn=True)

register a new user for XQ Dashboard access https://xq.stoplight.io/docs/xqmsg/b3A6NDEyMDYwMDI-self-sign-up

Parameters:

api (XQAPI) – XQAPI instance
email (str) – email address of registering user
password (str, optional) – optional password, used for authenticating without email 2FA, defaults to None
emailOptIn (bool, optional) – opt in to email notifications, defaults to True

delete_usergroup(usergroup_id: int)

delete a usergroup by id WARNING: DELETE not supported by API

Parameters:

api (XQAPI) – XQAPI instance
usergroup_id (int) – id number of usergroup

Raises:

XQException – error deleting usergroup

Returns:

success

Return type:

boolean

exchange_key(business_id: str | None = None)

exchange pre-auth token for an access token, and update headers accordingly https://xq.stoplight.io/docs/xqmsg/b3A6NDA5Mzc1NjA-exchange-for-access-token

Parameters:: api (XQAPI) – XQAPI instance
Raises:: XQException – key exchange failure
Returns:: success? boolean
Return type:: bool

get_communication_by_locator_token(locator_token: str)

Get a single communication by its locator token. https://xq.stoplight.io/docs/xqmsg/005edb8a9ec2b-get-communication-by-its-locator-token

Parameters:: api (XQAPI) – XQAPI instance
Raises:: XQException – invalid access token
Returns:: validated
Return type:: boolean

get_entropy(entropy_bits=2)

Generate quantum entropy from XQ with the provided number of entropy bits, returns as decoded string https://xq.stoplight.io/docs/xqmsg/b3A6NDA5MDAxNDY-quantum-generator

Parameters:

api (XQAPI) – XQAPI instance
entropy_bits (int, optional) – number of entropy bits to fetch, defaults to 2

Raises:

SDKConfigurationException – exception for http errors

Returns:

entropy

Return type:

base64 string

get_packet(locator_token: str)

fetch key with provided locator token https://xq.stoplight.io/docs/xqmsg/b3A6NDA5NDY4ODE-retrieve-a-key-with-its-token

Parameters:

api (XQAPI) – XQAPI instance
locator_token (str) – url encoded locator token

Raises:

XQException – packet retrieval failed

Returns:

key

Return type:

string

get_packets(locator_tokens: List[str])

fetch keys with provided locator tokens https://xq.stoplight.io/docs/xqmsg/b3A6NDA5NDY4ODE-retrieve-a-key-with-its-token

Parameters:

api (XQAPI) – XQAPI instance
locator_tokens (List[str]) – url encoded locator tokens

Raises:

XQException – packet retrieval failed

Returns:

key

Return type:

string

get_usergroup(usergroup_id: int | None = None, groups: List[str] | None = None)

get a usergroup by id

Parameters:

api (XQAPI) – XQAPI instance
usergroup_id (int, optional) – id of usergroup, defaults to None
groups (List[str], optional) – _description_ TODO, defaults to None

Raises:

XQException – error getting usergroup

Returns:

usergroup(s)

Return type:

dict

grant_users(locator_token: str, recipients: List[str], alias_access=False)

grant a list of recipients access to a given token https://xq.stoplight.io/docs/xqmsg/b3A6NDMzMTkyOTY-grant-a-user-access-to-a-key

Parameters:

api (XQAPI) – XQAPI instance
locator_token (str) – url encoded locator token
recipients (List[str]) – list of user emails to grant
alias_access (Boolean) – grant the user access for alias (non-MFA)

Raises:

XQException – access grant failed

Returns:

success

Return type:

boolean

login_verify()

verify a user’s login and exchange fake auth_token for a real auth_token

WARNING: this is not documented anyway. was found by reverse engineering the magic link auth flow

Parameters:: api (XQAPI) – XQAPI instance
Raises:: XQException – unable to verify login
Returns:: validated
Return type:: boolean

revoke_packet(locator_token: str)

revoke a key packet with the provided locator token https://xq.stoplight.io/docs/xqmsg/b3A6NDA5NDY4ODI-revoke-access-to-a-key

Parameters:

api (XQAPI) – XQAPI instance
locator_token (str) – url encoded locator token

Raises:

XQException – packet revokation failed

Returns:

success

Return type:

bool

revoke_users(locator_token: str, recipients: List[str], alias_access=False)

revoke a list of recipents from accessing a given token https://xq.stoplight.io/docs/xqmsg/b3A6NDA5NDY4ODU-revoke-user-access

Parameters:

api (XQAPI) – XQAPI instance
locator_token (str) – url encoded locator token
recipients (List[str]) – list of user emails to revoke
alias_access (Boolean) – grant the user access for alias (non-MFA)

Raises:

XQException – acces revoke failed

Returns:

success

Return type:

boolean

send_login_link(email: str, host: str | None = None)

send login magic link to a users email for Dashboard authentication https://xq.stoplight.io/docs/xqmsg/5cde236a164ba-send-login-magic-link-to-a-user

Parameters:

api (XQAPI) – XQAPI instance
email (str) – email address of authenticating user
host (str, optional) – the host domain that login links will target. if not provided, the default will be used, defaults to None

Raises:

XQException – error sending magic link

Returns:

success

Return type:

boolean

update_usergroup(usergroup_id: int, name: str, members: List[str])

update a usergroup by id WARNING: PATCH and PUT not supported by API

Parameters:

api (XQAPI) – XQAPI instance
usergroup_id (int) – id of usergroup
name (str) – new name of usergroup
members (List[str]) – new usergroup members

Raises:

XQException – error updating usergroup

Returns:

updated usergroup

Return type:

object

validate_access_token()

validate that the set access_token is valid for the dashboard https://xq.stoplight.io/docs/xqmsg/f260b4a8eb1ea-validate-an-access-token

Parameters:: api (XQAPI) – XQAPI instance
Raises:: XQException – invalid access token
Returns:: validated
Return type:: boolean

validate_api_key()

static method for validating provided API keys https://xq.stoplight.io/docs/xqmsg/b3A6NDExNDU1MDg-check-if-valid-api-key

Parameters:

api (XQAPI) – XQAPI instance

Raises:

SDKConfigurationException – exception for invalid keys
SDKConfigurationException – exception for http errors

Returns:

api response

Return type:

str OR json

xq.api package

Subpackages

Module contents