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