Authentication

Every API call exposed through SDK require authenticated caller. Credentials are checked once with OAuth2(https://oauth.net/2/) and client is granted authentication token that must be passed with following calls to API.

SDK encapsulates authentication requests in Authenticator class and:

OAuthClientCredentials,
OAuthDeviceCredentials,
OAuthApplicationUserCredentials.

OAuth*Credentials are used to provide grant/flow specific credentials. Depending on credentials used to authenticate, generated token will be associated with different privileges. If multiple credentials are needed to support use case, appropriate token can be generated and regenerated before calls that require it

Authentication steps

Authentication is a process where client will send correct credentials, for which server will return token that can be used to authorize further calls to API.

There are 4 steps necessary to acquire such token:

Create OAuth*Credentials for particular grant.
Create Authenticator instance passing it credentials instance.
Invoke getToken()
Save result in ApiClient

Please consult documentation on specific API section to find required grant. For each grant there is associated OAuth*Credentials described below. If multiple API sections require same grant, single token is enough to authorize them all. If different grants are required, you will need to generate tokens for each of grant types.

Authentication token storage

In JavaScript exists a cache solution using to store authentication token in cache. The cache solution consists of SDKCache abstract class with three important methods. If you would like to store authentication token in cache you must extend the SDKCache abstract class and then implement all their methods. By default SDK uses a file based cache to store tokens and implementation is made in FileCache class.

SDKCache abstract class methods

exists(key) - The method to check whether key exists and isn't expired. Returns true or false.
getItem(key) - The method to get cache item for given key. Returns authentication token object.
setItem(key, value) - The method to set authentication token as a cache item.

Accepted Credentials

Authentication endpoint accepts 3 credential types (grants), each requiring different set of parameters. Choose one by invoking it's from prototype method. Below you can find lists of expected parameters

OAuthClientCredentials
Represents credentials required for client grant
property	description	type	possible value
client_id	Client identifier	string	hexadecimal value or key
client_secret	Client secret	string	hexadecimal value or key

OAuthDeviceCredentails
Represents credentials required for device grant
property	description	type	possible value
client_id	Client identifier	string	hexadecimal value or key
client_secret	Client secret	string	hexadecimal value or key
uuid	Unique, universal identifier of device	string	/vendor/unknown/cashier/dotnettest1

OAuthApplicationUserCredentials
Represents credentials required for application grant
property	description	type	possible value
client_id	Client identifier	string	hexadecimal value or key
client_secret	Client secret	string	hexadecimal value or key
username	User identifier	string
password	User password	string
device	Identifier of device from which user is connecting	string
deviceinfo[name]	Name of device from which user is connecting	string

Authentication example

JavaScript authentication example

var clientId = '...';
var clientSecret = '...';
 
var authenticator = new SecuConnectApi.Authenticator(
    SecuConnectApi.OAuthClientCredentials.from(
        '...',
        '...'
    ));
 
var api = new SecuConnectApi.PaymentCustomersApi();
api.apiClient.authentications.oauth_token.accessToken = authenticator.getToken(); // Creates authenticator object with OAuth authentication and obtains token
 
// Your API calls follow ...

Explanation:

At line 1 & 2 we set clientId and clientSecret to correct values
At line 4 we create Authenticator instance providing it OAuth*Credentials corresponding to grant required for particular API
At line 5 we provide Authenticator instance with OAuthClientCredentials created by providing credentials to static from function
At line 10 we create instance of specific API
At line 11 we configure API with token (internally authenticator.getToken() will return Promise that will resolve to token)

HTTP request and response for code example

Request

Promise authenticator.getToken() will resolve on an HTTPS request to authentication endpoint. The HTTPS call will be similar to that below:

HTTP request

POST /oauth/token HTTP/1.1
{
  "grant_type": "client_credentials",
  "client_id": '...',
  "client_secret": '...'
}

POST payload to /oauth/token depends on grant_type, and will be generated based on OAuth*Credentials provided to Authenticator. It's ok if payload looks differently for other grants.

Response

When successful the server will respond with something like that:

HTTP response when successful

HTTP/1.1 200 OK
Content-Type: application/json
{
  "access_token": "jpv7fb.......me5m80bo81",
    "expires_in": 1200,
    "token_type": "bearer",
    "scope": "https://scope.secucard.com/e/api"
}

The returned access token is valid for as many seconds as signalized in the "expires_in" field. You will see it in a HTTP request header Authenticate: Bearer "eyJz93a...k4laUWw" of the subsequent calls.

Usually you have not to deal with HTTPS directly, but for debugging it might be helpful to understand what's happening behind the scenes.