Identity API and Credentials

This page covers how the IOTICS Identity API interacts with the IOTICSpace and walks you through our Identity Libraries.

Requirements to interact with IOTICSpace

The interaction between the IOTICS API and IOTICSpace happens due to our Decentralised Identity management system.

In this system, the IOTICS entities - Users, Agents and Twins - that need to interact need to identify themselves with each other and their IOTICSpace. The mechanism used to create and manage their unique identity is based on decentralised identifiers, or in short, DIDs.

In order to create and manage the IOTICS entities' credentials and to make sure the interactions are successful, some prior actions are required:

1. Create a User Identity
2. Create an Agent Identity
3. Set up an Authentication delegation from the User to the Agent, so any request made by the Agent to the IOTICS API can be linked to the User identity and verified.
   1. This is only required once, typically for every new agent or user identity.
4. Create a Twin Identity, for every new Twin the Agent wants to manage.
5. Set up a Control delegation from the Twin to the Agent so that the Agent can control the Twin.

For a general overview of how IOTICS handles identity, check out our Decentralised Identity page.

Identity - key concepts

Let's have a closer look at some Identity concepts.

Identity creation
To start creating a DID you'll need 2 values:

• A Seed, a random string of characters generated via the API.
• A Key Name, a string of characters that uniquely identifies the entity.

Together they generate a Key Pair consisting of a public and a private key which corresponds to the DID itself.
Both keys, Private and Public form the cryptographic key pair that ensures the correct entity authentication.

WARNING: The seed and key name are secret strings and must be stored securely and never shared with anyone. From the same seed string, one can create multiple keys with different names. In order to re-create the key pairs one needs to provide both seed and key name.

🚧

Warning

The Seed and Key Name secret strings and must be stored securely and never shared with anyone. From the same seed string, one can create multiple keys with different names. In order to re-create the key pairs one needs to provide both Seed and Key Name.

This process will happen to every entity created.

📘

The DID specifications can provide you with flexible and more forward ways to create identities and keys.

📘

Note

The Master Key is the initial key produced with Seed and Key Name for a new DID and DDO. This key can be used for authentication and delegation, but for best practises, it should only be used for DDO modifications. For the sake of simplicity, in this guide, we'll utilise the Master Key as the authentication and delegation method.

Identity storage
When a DID is created, it's stored into its related DDO, Decentralised Identity Document, which, along with the DID, contains some other important information for entity identification.
Each entity has its own DDO, and they are stored in the Resolver, a database for this type of document.

Delegation
Once the DIDs are created the Delegation can take place. Delegation is the process of granting another entity the ability to act on behalf of an identity owner.

In IOTICS the delegating entity is always a User or a Twin and the delegated entity is always the Agent. With this, we have two types of delegation:

• Authentication delegation
  A User delegates authorisation to an Agent so it can authenticate itself on an IOTICSpace on behalf of such User.
• Control delegation
  A Twin delegates control to an Agent to grant it the ability to perform operations on behalf of such Twin.

Identity API and Identity Libraries

The Identity API is used to manage the entities’ identities and their authentication within the IOTICSpace.
To facilitate the interaction with the Identity API, IOTICS provides 2 Identity Libraries split into 2 levels according to the user's needs:

1. [Identity Library] (https://github.com/Iotic-Labs/iotics-identity-py/blob/main/iotics/lib/identity/api/regular_api.py): individual functions for each feature, allowing greater control of the Identity management.
2. [High-level identity Library] (https://github.com/Iotic-Labs/iotics-identity-py/blob/main/iotics/lib/identity/api/high_level_api.py): set of basic features wrapped into complete functions, allowing quicker and easier interactions with the identities.

We provide Identity Libraries in several programming languages. Check below the library level available in each language.

Identity Library - key features:

• Create Seed
• Create User Identity
• Create Agent Identity
• Create Twin Identity
• User Delegates Authentication to Agent
• Twin Delegates Control to Agent
• Create Agent Authentication Token (JWT) - to be used in the headers alongside every action to perform against Digital Twins.

High level Identity Library - key features:

• Create User and Agent identities with Authentication Delegation
• Create Twin Identity with Control Delegation