Archive - Prerequisites

❗️
Opps
This page has been deprecated, if you have found your way here please head back to the Welcome page!

This section ensures you have everything you need set up to follow the rest of the tutorials for the IOTICS WebAPI.

Dependencies and environment

Install the following dependencies:

pip install requests
pip install shortuuid

You'll need to have gone through the Identity API tutorial and created your Identity credentials.

Then initialise the environment for the given HOST:

host=Host("https://api01.demo02.space.iotics.com")

Create or reuse an existing seed as explained here. For these tutorials we expect a seed to be stored in .seed.

from iotic.lib.identity import Identifier
seed = None
try:
    seed = open('.seed', 'r').read()
except:
    # no file
    seed = Identifier.new_seed(256)
    f = open(".seed", "a")
    f.write(seed)
    f.close()

seed
#output: 'cee00ea402f872402e1932daffa5a4348c6a7c0158c138bfefc0284e560771f6'

For the purposes of this tutorial we will reuse the same seed, though we recommend you create different seeds for different purposes to increase security.

Create keys and identities for this user and agent; then set authentication delegation:

user_key = NamedECDSAKey(seed=seed, purpose="user", name="fred_at_gmail-0")
user_identity=IdentifiableEntity(named_key=user_key)
#output: Identity did:iotics:iotK1TzFHU3NAXa4D4keEQMVRjssx2seFjjv not found
#output: registered doc for NamedKey[p=user, id=did:iotics:iotK1TzFHU3NAXa4D4keEQMVRjssx2seFjjv, n=fred_at_gmail-0]

agent_key=NamedECDSAKey(seed=seed, purpose="agent", name="hb-mon-0")
agent_identity=IdentifiableEntity(named_key=agent_key)
#output: Identity did:iotics:iotDVFBFgrakWFFZjQGrtCPWvSBUEUqhJTBF not found
#output: registered doc for NamedKey[p=agent, id=did:iotics:iotDVFBFgrakWFFZjQGrtCPWvSBUEUqhJTBF, n=hb-mon-0]

agent_proof=agent_identity.document_manager.new_proof(did=user_key.id)
agent_issuer=agent_identity.document_manager.issuer()
user_identity.document_manager.add_auth_delegation(proof=agent_proof, authorizer_id=agent_issuer, name="agent_deleg_0")
#output: registered doc for NamedKey[p=user, id=did:iotics:iotK1TzFHU3NAXa4D4keEQMVRjssx2seFjjv, n=fred_at_gmail-0]
#output: True

For convenience we create a method that returns a set of HTTP headers used to communicate with the HOST:

import shortuuid

def iotics_headers(agent_identity: IdentifiableEntity, user_identity: IdentifiableEntity, host: str, duration: int = 120) -> dict:
  user_did = user_identity.document_manager.named_key.id
  token = agent_identity.document_manager.new_token(principal_did=user_did, duration=duration, audience=host)
  headers = {
     "accept": "application/json",
     "Iotics-ClientRef": f'd-poc-{shortuuid.random(8)}',
     "Iotics-ClientAppId": agent_identity.document_manager.named_key.id,
     "Authorization": f'Bearer {token}',
     "Content-Type": "application/json"
  }
  return headers

A brief explanation on the headers:

Iotics-ClientRef is a client specific reference value used for clients to reconcile one or more requests. The value is echoed back as supplied by the client. This is useful especially to reconcile async requests with their respective responses. In this tutorial we randomly generate the ref values.
Iotics-ClientAppId (DEPRECATED) is set to the value of the agent did - it’s deprecated as teh same value is available from the Authorization token
Authorization: a JWT token obtained by signing a claim stating that this agent is acting on behalf of the user whose DiD is in user_did. The token is by default valid only for 3s as per duration argument in line#5. Best practice is to have short lived tokens to reduce the possibility of a replay attack.

Test the headers creation by running:

iotics_headers(agent_identity=agent_identity, user_identity=user_identity, host=host.address)

#output: {  
#output:    'accept': 'application/json', 
#output:    'Iotics-ClientRef': 'd-poc-n8EDAer5', 
#output:    'Iotics-ClientAppId': 'did:iotics:iotDVFBFgrakWFFZjQGrtCPWvSBUEUqhJTBF', 
#output:    'Authorization': 'Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiJ9.eyJpc3MiOiJkaWQ6aW90aWNzOmlvdERWRkJGZ3Jha1dGRlpqUUdydENQV3ZTQlVFVXFoSlRCRiNhZ2VudF9rZXlfMCIsImF1ZCI6Imh0dHBzOi8vYXBpMDEuZGVtbzAxLnNwYWNlLmlvdGljcy5jb20iLCJzdWIiOiJkaWQ6aW90aWNzOmlvdEsxVHpGSFUzTkFYYTRENGtlRVFNVlJqc3N4MnNlRmpqdiIsImlhdCI6MTYxMzQzNDc5OSwiZXhwIjoxNjEzNDM0ODU5fQ.a9nievn3YyD57yLODmhNR-g18mi81uFRJjcd1uPpbrhzKFHSY_WoAJ9AFOkOnyju0VZmT3XDcXd_kMxe53Fa1A', 
#output:    'Content-Type': 'application/json'
#output: }

Bringing it all together

Make sure your environment includes the following dependencies:

pip install wheel
pip install iotic.lib.identity-0.2.post38
pip install requests
pip install shortuuid

For the following tutorials you may want to copy this into a file called iotics_tutorial.py. We will carry on progressively adding to the file at the end of each tutorial prepare for the next.

import shortuuid
from iotic.lib.identity import Identifier
from iotics_id import setup_resolver, NamedECDSAKey, DocumentManager, IdentifiableEntity

HOST = "https://api01.demo02.space.iotics.com"

setup_resolver(host=HOST)

seed = None
try:
    seed = open('.seed', 'r').read()
except:
    # no file
    seed = Identifier.new_seed(256)
    f = open(".seed", "a")
    f.write(seed)
    f.close()


user_key = NamedECDSAKey(seed=seed, purpose="user", name="fred_at_gmail-0")
user_identity = IdentifiableEntity(named_key=user_key)

agent_key = NamedECDSAKey(seed=seed, purpose="agent", name="hb-mon-0")
agent_identity = IdentifiableEntity(named_key=agent_key)
agent_proof = agent_identity.document_manager.new_proof(did=user_key.id)

agent_issuer = agent_identity.document_manager.issuer()

user_identity.document_manager.add_auth_delegation(proof=agent_proof, authorizer_id=agent_issuer, name="agent_deleg_0")


def iotics_headers(agent_identity: IdentifiableEntity, user_identity: IdentifiableEntity, host: str, duration: int = 120) -> dict:
    user_did = user_identity.document_manager.named_key.id
    token = agent_identity.document_manager.new_token(principal_did=user_did, duration=duration, audience=host)
    headers = {
        "accept": "application/json",
        "Iotics-ClientRef": f'd-poc-{shortuuid.random(8)}',
        "Iotics-ClientAppId": agent_identity.document_manager.named_key.id,
        "Authorization": f'Bearer {token}',
        "Content-Type": "application/json"
    }
    return headers

❗️Opps

Dependencies and environment

Bringing it all together

❗️
Opps