Introduction

The following sections will guide you in how to use the Integration Services SDK. The Integration Services SDK makes it easy to manage decentralized identities and secure channels (Audit Trail).

You should have a basic understanding of decentralized identities to get the most out of the following examples.

Install

Java

Build from source:

git clone git@github.com:albydeca/iota-is-sdk.git
cd iota-is-sdk
mvn clean install

or download JAR from MVNRepository

or simply add to your POM:

<!-- https://mvnrepository.com/artifact/net.gradbase/iota.is.sdk -->
<dependency>
    <groupId>net.gradbase</groupId>
    <artifactId>iota.is.sdk</artifactId>
    <version>0.0.1</version>
</dependency>

Node.js

You can install the Integration Services Client using [npm](https://npmjs.com/) or [yarn](https://yarnpkg.com/).

npm

npm install @iota/is-client

Yarn

yarn add @iota/is-client

Clients

The Integration Services SDK has two different clients you can use:

IdentityClient

You can use IdentityClient to manage decentralized identities. This includes, but is not limited to:

• Creating an identity and verifiable credentials
• Updating users
• Deleting users
• Adding Trusted Authorities

info

You can test your implementation on our public API which is connected to the IOTA Mainnet.

• URL: https://demo-integration-services.iota.cafe/
• API key: b85e51a2-9981-11ec-8770-4b8f01948e9b :::

ChannelClient

You can use the ChannelClient to access Audit Trail features. These include, but are not limited to:

• Creating a channel
• Subscribing or approving access to a channel
• Reading and Writing on a channel

Java

You can import and configure these clients using a env.properties object which will populate the BaseClient class:

 api-key=XXXXXXX
 api-version=vX.X
 api-url=XXXXXXX
 identity-file=adminIdentity.json

Node.js

You can import and configure these clients using a ClientConfig object:

import { ClientConfig, IdentityClient, ChannelClient } from '@iota/is-client';

const config: ClientConfig = {
    isGatewayUrl: process.env.IS_GATEWAY_URL,   // used in production
    ssiBridgeUrl: process.env.SSI_BRIDGE_URL,   // used in local development
    auditTrailUrl: process.env.AUDIT_TRAIL_URL, // used in local development
    useGatewayUrl: process.env.USE_GATEWAY_URL === 'true' || false,
    apiKey: process.env.API_KEY,                // can be setup in the API to restrict access
    apiVersionAuditTrail: ApiVersion.v0_1,      // API version of the audit trail
    apiVersionSsiBridge: ApiVersion.v0_2        // API version of the ssi bridge
};

...
const identityClient = new IdentityClient(config);
...

...
const channelClient = new ChannelClient(config);
...

Authorization

In order to work with Integration Services API, you will need to be authenticated with a decentralized identity.

The Integration Services use a JWT token based authorization mechanism which behaves in the following manner:

1. The client gets a nonce from the API and returns it signed by the identity's private key.
2. The API returns a JWT token to authorize any subsequent requests.

You can get an identity using the following script (no auth required):

Java

  IdentityClient client = new IdentityClient();
  JSONObject jsonClaim = new JSONObject().put("type", "Person").put("name", "randomName");

  Claim claim = new Claim(jsonClaim);

  final String randomUsername = Utils.getRandomUsernameOfLength(5);
  System.out.println("username: " + randomUsername);
  JSONObject newUserIdentity = client.create(randomUsername, claim);
  System.out.println("created new user " + newUserIdentity);

Node.js

const identity = await identityClient.create('User');

The generated identity is stored on the IOTA Tangle and follows did-core specifications. It is a JSON file like the following:

{
  "id": "did:iota:Dr1kbpAUMtmXV7oNBsqdt2bkFrt72fmvzGNxhgU939ne",
  "keys": {
    "sign": {
      "public": "EWcf94eLQsikKwWeVjKKb5nC38iiTgUz97oSDEzxBvzu",
      "private": "CBNAydKtSUQ3voeyMHiBngrGsKSSenohRE6CGqzuHGHA",
      "type": "ed25519",
      "encoding": "base58"
    },
    "encrypt": {
      "public": "CKfWWbRr8JkfZ3fZAYiDcFqTiHDyRiBGurxAMYkXLX7j",
      "private": "84fewtiBLvsenyA4LoDBn8WzGZiknXopsYuGWT6GvzPG",
      "type": "x25519",
      "encoding": "base58"
    }
  }
}

If you have a JSON Identity, you can authorize your client as follows:

Java

  String id = newUserIdentity.getJSONObject("doc").getString("id");
  String pubKey = newUserIdentity.getJSONObject("key").getString("public");
  String privKey = newUserIdentity.getJSONObject("key").getString("secret");
  client.authenticate(id, pubKey, privKey);

Node.js

const identity = // ... did-core json object ...
  await identityClient.authenticate(identity.id, identity.keys.sign.private);