Archive - Identity API

❗️

Opps

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

This pages covers the the use of IOTICS Identity API with our Decentralized Identity Documents (DID) identity processes. You can find our Identity SDK on GitHub.

For a general overview of DID see the relevant Decentralized Identity Documents Key Concept page.

Identity API Overview

The identity API is used to manage identities and authentication in the IOTICS Host. The API is split in 2 levels according to the user needs:

• High level identity API: minimal set of features wrapped into complete functions allowing quicker and easier interaction with an IOTICS Host
• Identity API: individual functions for each feature, allowing greater control of the Identity process

High level Key concepts

An Identity is represented by a pair of secrets used to generate private and public keys.

A pair of secrets is composed of a secret seed (see how to generate below) and a key name (a string).

# Install iotics.lib.identity

# How to generate a seed using the code
[HighLevelIdentityApi or IdentityApi].create_seed()

# How to generate a seed using the command line
iotics-identity-create-seed

A Registered Identity of type TWIN, AGENT or USER is created from an Identity (or pair of secrets). When a Registered Identity is created, a Register document associated to this identity is also created and registered against the Resolver. The Registered Identity owns the document.

A Registered Identity can:

• Add new owners (an Identity public key) to a Register Document the Registered Identity owns
• Allow an other Identity (using its public key) to authenticate using the Register Document the Registered Identity owns
• Delegate Authentication to an other Registered Identity on a Register Document the Registered Identity owns, the other Registered Identity can authentication on behalf of the Registered Identity
• Delegate Control to an other Registered Identity on a Register Document the Registered Identity owns, the other Registered Identity can control the Register Document the Registered Identity owns

Requirements to interact with IOTICS Host

1. Authenticate with a token required by the Iotics Web API:
   • Create a USER Registered Identity
   • Create an AGENT Registered Identity
   • Setup an Authentication delegation from the USER to the AGENT (USER delegates to the AGENT so AGENT can work on behalf of the USER)
   • Create an authentication token
   • Use the token in the Iotics Web API headers
2. Create Iotics Twins using the Iotics Web API:

* Create a TWIN Registered Identity
* Setup a Control delegation from the TWIN to the AGENT (TWIN delegates to the AGENT so AGENT can control the TWIN)
* Use the twin decentralised identifier (registered_identity.did) to create the Iotics Twin using the Iotics Web API

See the High Level Identity API and Identity API sections below to easily comply with those requirements and start using Iotics.

High level Identity API

Minimal set of features to interact with Iotics Host.

Key features:

• Create USER and AGENT identities with authentication delegation: set of identities required to authenticate against Iotics Host
• Create an AGENT authentication token with duration: token required by the Iotics Host API for authentication
• Create TWIN identity with control delegation: create a Twin identity to enable the creation and update of an Iotics Twin

📘

Long Expiry Authentication Tokens

To help get started with IOTICS we can create Long Authentication Tokens that last 90 days.

Try it

Source: How to use the high level identity API.

🚧

Note:

To run this example you will need a resolver url and to set the following environment variable:

export RESOLVER=[resolver url]

Run it and have a look at the output:

export RESOLVER='http://localhost:5000'
VERSION=dev pip install .
python ./high_level_api.py

See the "code only" version of the how to use the high level identity API to have a look at the code usage without noise (without print).

Identity API

Set of features for basic identities management.

Key features:

• Create a user identity: needed to authenticate against the Iotics host
• Create an agent identity: needed to authenticate against the Iotics host
• User identity delegates Authentication to the Agent identity: Agent can authenticate on behalf of the user against the Iotics host.
• Create an AGENT authentication token with duration: token required by the Iotics Host API for authentication
• Create a twin identity: create a Twin identity to enable the creation of an Iotics Twin
• Twin delegates Control to Agent: enable Agent to control (update/delete/...) an Iotics Twin

📘

Long Expiry Authentication Tokens

To help get started with IOTICS we can create Long Authentication Tokens that last 90 days.

Try it

Source: How to use the identity API.

🚧

Note:

To run this example you will need a resolver url and to set the following environment variable:

export RESOLVER=[resolver url]

Run it and have a look at the output:

export RESOLVER='http://localhost:5000'
VERSION=dev pip install .
python ./regular_api.py

See the "code only" version of the how to use the identity API to have a look at the code usage without noise (without print).