Skip to main content

Introduction

The following sections will guide you in how to use the Integration Services Client. The Integration Services Client 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​

You can install the Integration Services Client using npm or yarn.

npm install @iota/is-client

Clients​

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

IdentityClient​

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

ChannelClient​

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

info

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

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 
    apiKey: process.env.API_KEY,                // can be setup in the API to restrict access 
    apiVersion: ApiVersion.v01                  // API version (default: v0.1)
};

...
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):

import { IdentityJson } from '@iota/is-client';
...

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

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

{
  "doc": {
    "id": "did:iota:3q4mW831dfbbSP2j5Lf4FPTKXFjEv2ykyPjuVrd1FHss",
    "authentication": [
      {
        "id": "did:iota:3q4mW831dfbbSP2j5Lf4FPTKXFjEv2ykyPjuVrd1FHss#key",
        "controller": "did:iota:3q4mW831dfbbSP2j5Lf4FPTKXFjEv2ykyPjuVrd1FHss",
        "type": "Ed25519VerificationKey2018",
        "publicKeyBase58": "5LT5yjaykKeTqYuqmCELE7xUyN9z4WEN5CKxdWmrU5g5"
      }
    ],
    "created": "2021-12-20T10:43:00Z",
    "updated": "2021-12-20T10:43:00Z",
    "proof": {
      "type": "JcsEd25519Signature2020",
      "verificationMethod": "#key",
      "signatureValue": "ktusPiZd5whHTHsJJwSiSbfhmAGypdkTgLFQt4USvVg91WJLYNhEzshcBCvr9Cr42heyB249TvZHVrdGVAYds6s"
    }
  },
  "key": {
    "type": "ed25519",
    "public": "5LT5yjaykKeTqYuqmCELE7xUyN9z4WEN5CKxdWmrU5g5",
    "secret": "9Arv8HTAu3JjLvBhst6deMaULvBc3e7w2WiseEL4BESC",
    "encoding": "base58"
  }
}

If you have a JSON Identity, you can authorize your client with the script:

const identity = // ... did-core json object ...

await identityClient.authenticate(identity.doc.id, identity.key.secret);