PowerAuth Networking JS SDK

Wultra PowerAuth Networking (WPN) is a high-level SDK built on top of our PowerAuth Mobile JS SDK that enables request signing and encryption.

[!NOTE] We currently support REACT NATIVE and APACHE CORDOVA development platforms.

Documentation Content

• SDK Integration
• Open Source Code
• Initialization and Configuration
• Endpoint Definition
• Creating an HTTP request
• Error Handling
• Language Configuration
• Logging
• Changelog

SDK Integration

Requirements

• React Native (0.73+) or Apache Cordova (>=12.0.0)
• PowerAuth Mobile JS SDK needs to be implemented in your project

PowerAuth JS SDK Dependency

The PowerAuth JS SDK is a required peer dependency of the SDK. You must install it in a compatible version.

Defining it as a peer dependency ensures that only a single instance of the PowerAuth SDK is used in your project, preventing issues with multiple npm clones.

• For React Native, install both react-native-powerauth-mobile-sdk and react-native-powerauth-networking using npm or yarn.
• For Cordova, add cordova-powerauth-networking using the cordova plugin add command. The cordova-powerauth-mobile-sdk will be automatically installed as a dependency.

Compatible PowerAuth Mobile JS SDK Versions

React Native Installation

Supported Platforms

The library is available for the following React Native (0.73+) platforms:

• Android 5.0 (API 21) and newer
• iOS 13.4 and newer

How To Install

1. Install packages via npm

# if not added yet, add powerauth mobile SDK first (compatible versions are at the top of this document)
npm i react-native-powerauth-mobile-sdk --save
npm i react-native-powerauth-networking --save

2. Install pods for iOS (if needed)

To make integration work with iOS, you might need to install Pods (needed for PowerAuth):

cd ios
pod install

Cordova Installation

Supported Platforms

The library is available for the following Apache Cordova (>=12.0.0) platforms:

• Android 7.0 (API 24) and newer (cordova-android version >=12.0.0)
• iOS 11.0 and newer (cordova-ios version >=7.0.0)

How To Install

1. Install plugin via the Cordova plugin installer

cordova plugin add cordova-powerauth-networking

2. Install pods for iOS (if needed)

To make integration work with iOS, you might need to install Pods (needed for PowerAuth):

cd platforms/ios
pod install

Open Source Code

The code of the library is open source, and you can freely browse it in our GitHub at https://github.com/wultra/networking-js

Initialization and Configuration

Everything you need is packed inside the single WPNNetworking class that provides all the necessary APIs for your networking.

To successfully create an instance of the service, you need only 2 things:

• configured PowerAuthSDK object
• configuration of the service (like endpoints base URL)

Example:

let pa: PowerAuth = ... // your PowerAuthSDK instance
let baseURL = "https://my.backend.com/api/v3" // whene undefined, powerauth url will be used
const networking = new WPNNetworking(pa, baseURL)

Endpoint Definition

Each endpoint you will target with your project must be defined for the service as a WPNEndpoint instance. There are several types of endpoints based on the PowerAuth signature that is required.

End To End Encryption

If the endpoint is end-to-end encrypted, you need to configure it accordingly. Default values are set to NOT_ENCRYPTED.

Possible values are:

/** Configuration for end-to-end encryption. */
export enum WPNE2EEConfiguration {
    /** Endpoint is encrypted with the application scope. */
    APPLICATION_SCOPE,
    /** Endpoint is encrypted with the activation scope. */
    ACTIVATION_SCOPE,
    /** Endpoint is not encrypted. */
    NOT_ENCRYPTED
}

Signed endpoint WPNEndpoint.signed()

For endpoints that are signed by a PowerAuth signature and can be end-to-end encrypted.

Example:

// signed endpoint with expected response data, not response config and end-to-end encryption disabled
const mySignedEndpoint: WPNEndpoint<MyRequest, MyResponse> = WPNEndpoint.signed("/path/to/the/signed/endpoint", "endpoint/identifier", undefined, WPNE2EEConfiguration.NOT_ENCRYPTED)

Signed endpoint with Token WPNEndpoint.signedWithToken()

For endpoints that are signed by token by PowerAuth signature and can be end-to-end encrypted.

More info for token-based authentication can be found here

Example:

// signed endpoint with token-based authentication with expected response data, not response config and end-to-end encryption disabled
const myTokenSignedEndpoint: WPNEndpoint<MyRequest, MyResponse> = WPNEndpoint.signedWithToken("/path/to/the/signed/endpoint", "tokenName", undefined, WPNE2EEConfiguration.NOT_ENCRYPTED)

// tokenName is the name of the token as stored in the PowerAuthSDK
// more info can be found in the PowerAuthSDK documentation
// https://github.com/wultra/powerauth-mobile-sdk/blob/develop/docs/PowerAuth-SDK-for-iOS.md#token-based-authentication

Basic endpoint (not signed) WPNEndpoint.unsigned

For endpoints that are not signed by PowerAuth signature but can be end-to-end encrypted.

Example:

// unsigned endpoint with expected response data, not response config and end-to-end encryption set to application scope
const myTokenSignedEndpoint: WPNEndpoint<MyRequest, MyResponse> = WPNEndpoint.unsigned("/path/to/the/signed/endpoint", undefined, WPNE2EEConfiguration.APPLICATION_SCOPE)

Creating an HTTP request

To create an HTTP request to your endpoint, you need to call the WPNNetworking.call method with the following parameters:

• endpoint - an endpoint that will be called
• requestData - request data that will be sent to the server
• authentication - PowerAuthAuthentication instance that will sign the request (if needed)
  • pass undefined for the basic unsigned endpoint
• requestProcessor - optional request processor that can modify the request before it is sent to the server

The method is asynchronous and returns a Promise with the response or an error.

Example:

// payload we will send to the server
interface MyRequest {
    userID: string
}

// response of the server
interface MyResponse {
    name: string
    email: string
}

// endpoint configuration
const endpoint: WPNEndpoint<MyRequest, MyResponse> = WPNEndpoint.signed("/path/to/the/signed/endpoint", "endpoint/identifier", undefined, WPNE2EEConfiguration.ACTIVATION_SCOPE)

// Authentication (for example purposes) expect user PIN 1111
const auth = PowerAuthAuthentication.password("1111")
            
// WPNNetworkingService instance call
const response = await networking.call(
    // specify endpoint
    endpoint,
    // specify request data
    { userID: "12345" },
    // specify authentication
    auth
)

if (response.status == "OK" && response.responseObject) {
    // success, use response.responseObject
    console.log(`User name is ${response.responseObject.name} and email is ${response.responseObject.email}`)
} else {
    // error, use response.error
    console.error(`Error: ${response.error}`)
}

We use fetch under the hood.

Server Errors

When a server returns an error, the WPNResponse object will contain the error information in the responseError property. The status property will be set to "ERROR".

The responseError object will contain a code and a message that can be used to identify the error.

This is a known server codes:

Language Configuration

Before using any methods from this SDK that call the backend, a proper language should be set. A properly translated content is served based on this configuration. The property that stores language settings does not persist. You need to set acceptLanguage every time that the application boots.

Format

The default value is always en. With other languages, we use values compliant with standard RFC Accept-Language.

Logging

You can set up logging for the library using the WPNLoggerConfig class.

Verbosity Level

You can limit the amount of logged information via the verbosity property.

Log Time

You can enable or disable time logging via the includeTime property. The default value is true.

Logger Listener

In case you want to process logs on your own (for example log into a file or some cloud service), you can set WPNLoggerConfig.listener.

Changelog

1.0.0

• Initial release