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 Identity system, IOTICS entities - Users, Agents and Twins - use credentials to interact with one another and with the IOTICSpace, they are identified with a DID, their unique Identity.

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

  • Create a User Identity
  • Create an Agent Identity
  • Set up an Authentication delegation from the User to the Agent, so the Agent can work on its behalf.
  • Create a Twin Identity
  • Set up a Control delegation from the Twin to the Agent, so 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, which can be obtained from the Identity API.

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

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

This process will happen to every entity created.


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 such as the Seed.
Each entity has its own DDO, and they are stored in the Resolver, a database for this type of document.


Once the DIDs are created the Delegation can take place.
Users delegate Authorisation to Agents so they act on their behalf.
Twin delegate Control to Agents so they can take actions against them.


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: individual functions for each feature, allowing greater control of the Identity management.
  2. High-level identity Library: 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.

Programming LanguageIdentity LibraryHigh-level Identity Library

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.

Try it

High level Identity Library - key features:

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

Try it