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:

  • ,
  • ,
  • .

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:

  1. Create OAuth*Credentials for particular grant.
  2. Create Authenticator instance passing it credentials instance.
  3. Invoke getToken()
  4. 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

  1. exists(key) - The method to check whether key exists and isn't expired. Returns true or false.
  2. getItem(key) - The method to get cache item for given key. Returns authentication token object.
  3. 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
propertydescriptiontypepossible 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
propertydescriptiontypepossible 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
propertydescriptiontypepossible 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
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:

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/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.