API

Public Functions description


Installation

All Optherium source codes are accessible by Client TOKEN. You should receive it from Optherium Sales Team. Just replace TOKEN in the lines below to clone the repository


You can clone repository
git clone TOKEN:x-oauth-basic@github.com/Optherium/optherium-sdk-integration-angular
Or install into your project using npm
npm i git+https://TOKEN:x-oauth-basic@github.com/Optherium/optherium-sdk.git#1.0.1 --save

Storage

Optherium SDK uses long term storage to store private keys, certificates, state data and other data required for its work. Storage realization should implement the securest way to store information as possible for a platform (KeyChain for iOS, encrypted storage for Android)

interface IStorage {
    setItem(key: string, value: string): Promise;
    removeItem(key: string): Promise;
    getItem(key: string): Promise;
    getKeys(): Promise;
}

Config

If you are running the cloud version of the platform just use a config file provided by Optherium Team. If you are running the decentralized version with a client infrastructure run on your end, you need to fill a config file with your settings. Read more information on the Network Manager section

The basic interface looks as follows:

interface IConfig {
    wsConnection: IWsConnectionConfig;
    authService: IAuthServiceConfig;
    appHost: string;
    dvsChunks: IDvsChunkConfig[];
}

Connection Options to publicly available Client API Gateway service, connected to the blockchain peers

interface IWsConnectionConfig {
    url: string;
    path: string;
    multiplex: boolean;
    ackTimeout: number;
}

Connection options to Authentification service, connected to CA

interface IAuthServiceConfig {
    host: string;
    loginPath: string;
    logoutPath: string;
    refreshPath: string;
}

Connection options to Data Vault for sensitive and personal information

interface IDvsChunkConfig {
  holderMSPID: string;
  holderAff: string;
  postUrl: string;
  getUrl: string;
}

Initialization

Code below initializes Optherium SDK and shows how it can be used. Remember that you should provide your realization of IStorage interface to the constructor. After inicialization you can call actions and subscribe on state change to receive a result of an operation and update user interface

import {SDKCore, FlowService, StateFlow} from 'optherium-sdk'

let sdk = new SDKCore(new Storage(), config)
sdk.init()
let flow = FlowService.submitPhone(phone)
sdk.state.subscribe(state => {
    switch (state.flow) {
        case StateFlow.REGISTRATION_PHONE_SUCCESS:
            //do something
            break;
    }
})

SDKCore

Singleton core instance encapsulating network communication


Function init()

Initialized all necessary components, generates CryptoSuit if needed, opens a WebSocket connection

Returns:

void


Function isInit()

Check whether library was initialized or not

Returns:

Boolean


Function logout()

Terminates user session, clean up Storage including credentials(CryptoSuit)

Returns:

void


Function generateFlowId()

Generates flow id that is used to identify the flow.

Returns:

String


Function getDevices()

Returns a list of devices bind to the identity

Returns:

Array<Device>


Function removeDevice()

Removes device from the list of authorized devices

Name Type Description
deviceId String id of the device to be removed
Returns:

void


Function getIdentityId()

Returns current identity id

Returns:

String


Function startSecureOperation(operationType, operationId)

Some operations requires additional authentication(Strong Customer Authentication for financial transactions). This method initiates additional authentication operation. Method returns operationRef that should be passed to the next step.

Name Type Description
operationType String phone/email/push
operationId String Id of operation that is supposed to be confirmed by secure operation
Returns:

String


Function confirmSecureOperation(operationRef, code)

Confirm secure operation with a code

Name Type Description
operationRef String Uniq operation id returned from startSecureOperation method
code String 4 or 6 digit verification code
Returns:

Boolean


Function getState()

Returns the last state of KYC procedure

Returns:

IState

Name Type Description
flow String name of the latest step completed.
data Object Contains additional information about the last step if it was successfully completed. Optional.
error Error If the last step was completed with an error. Optional.

Observable state

Stream of state updates

Returns:

Observable <IState>

Name Type Description
flow String name of the latest step completed.
data Object Contains additional information about the last step if it was successfully completed. Optional.
error Error If the last step was completed with an error. Optional.

Observable connectionState

Stream of the WebSocket connection status

Returns:

Observable <IState>


Name Type Description
state Boolean Indicates ss connection established
error Error Contains the reason of connection hang up. Optional.

FlowService

Contains methods to provide data required for registration and KYC procedure.


Phone Verification Flow

Function setPhone(uuid, phoneNumber)

Initiates phone verification procedure. Requests SMS code sending to provided phone number

Params:

Name Type Description
uuid String Unique id of operation generated by generateFlowId
phoneNumber String Phone number in E.164 format
mainDeviceInfo String Main device info stored in the phone asset. It should contain only common information about platform type and version.
additionalDeviceInfo String Additional device info stored in DataVault. It may contain personal and sensitive information.
Returns:

void


Function confirmPhone(uuid, code)

Submits verification code

Params:

Name Type Description
uuid String Id of operation submitted on the previous step
code String Digit verification code
Returns:

void


Function retrySendPhoneCode(uuid)

Request verification code one more time. User has 3 attempts. On the third attempt user should receive a voice call.

Params:

Name Type Description
uuid String Id of operation submitted on the previous step
Returns:

void


Email Verification Flow

Function setEmail(uuid, emailAddress, isAgree)

Initiates email verification procedure. Requests code sending to provided email address

Params:

Name Type Description
uuid String Unique id of operation generated by generateFlowId
emailAddress String Email address
isAgree Boolean Indicates is used agreed to receive news and notifications from the service
Returns:

void


Function approveEmail(uuid)

Initiates email approval flow. It's used to prove ownership of the email during recovery process.

Params:

Name Type Description
uuid String Unique id of operation generated by generateFlowId
emailAddress String Email address
isAgree Boolean Indicates is used agreed to receive news and notifications from the service
Returns:

void


Function confirmEmail(uuid, code)

Submits verification code

Params:

Name Type Description
uuid String Id of operation submitted on the previous step
code String Digit verification code
Returns:

void


Function retrySendEmailCode(uuid)

Request verification code one more time. User has 3 attempts.

Params:

Name Type Description
uuid String Id of operation submitted on the previous step
Returns:

void


Document Verification Flow

Function uploadDocument(uuid, documentType, frontImageFile, backImageFile, faceImageFile)

Submits document images with user's selfie to verification.

Params:

Name Type Description
uuid String Unique id of operation generated by generateFlowId
documentType String One of the following values: passport, driver_license, id_card
frontImageFile Buffer(JS), ByteArray(Android) Image of the front page of a document. Maximum size - 5mb. More about image requirements you can read here
backImageFile Buffer(JS), ByteArray(Android) Image of the back page of a document. Required for driver_license, id_card types. Otherwise can be empty array. Maximum size - 5mb. More about image requirements you can read here
faceImageFile Buffer(JS), ByteArray(Android) User's selfie image. Maximum size - 5mb. More about image requirements you can read here
Returns:

void


Function approveDocument(uuid, documentType, frontImageFile, backImageFile, faceImageFile)

Initiates documents approval flow. It's used to prove ownership of the document during recovery process.

Params:

Name Type Description
uuid String Unique id of operation generated by generateFlowId
documentType String One of the following values: passport, driver_license, id_card
frontImageFile Buffer(JS), ByteArray(Android) Image of the front page of a document. Maximum size - 5mb. More about image requirements you can read here
backImageFile Buffer(JS), ByteArray(Android) Image of the back page of a document. Required for driver_license, id_card types. Otherwise can be empty array. Maximum size - 5mb. More about image requirements you can read here
faceImageFile Buffer(JS), ByteArray(Android) User's selfie image. Maximum size - 5mb. More about image requirements you can read here
Returns:

void


Address Verification Flow

Function uploadAddress(addressData, addressImages):

Submits user's address information and images proofing ownership of this address

Params:

Name Type Description
addressData IAddress Text representation of user's address. Interface is described below.
addressImages Array<Buffer>(JS) , Array<ByteArray>(Android) An array of up to 4 images of document contained address and name of the user Maximum size - 5mb. More about image requirements you can read here
interface IAddress {
 country: String,
 city: String,
 region: String,
 street: String,
 streetType: String,
 buildingNumber: String,
 apartmentNumber: String,
 postalCode: String
}

Returns:

void


New Device Authorization Flow

Function deviсeAuthorizationRequest(uuid)

Sends device authorization request that can be approved or rejected from authorized device.

Name Type Description
uuid String Unique id of operation generated by generateFlowId
Returns:

void


Function handleDeviсeAuthorizationRequest(uuid, action)

Process incoming device authorization request.

Params:

Name Type Description
uuid String Id of the request
action Boolean Approve(true) or Reject(false)
Returns:

void


Recovery Flow

Function sendRecoveryRequest(uuid)

Sends recovery request.

Name Type Description
uuid String Id of the request
Returns:

void


Next