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,
OAuthApplicationUserCredentials,
OAuthDeviceCredentials.

OAuth*Credentials classes 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 instance for particular grant.
Create Authenticator instance passing it OAuth*Credentials instance generated in step 1.
Invoke getToken() method from Authenticator class
Result from step 3 is OAuth*Token instance, which contains more information about authentication token received from API like eg. how long token is active. In this step you must to call getAccessToken() method from returned OAuth*Token class instance
Save result from step 4 in ApiClient using setAccessToken(accessToken) method

Accepted Credentials

Authentication endpoint accepts 3 credential types (grants), each requiring different set of parameters. Below you can find lists of expected parameters when specific OAuth*Credentials is created.

OAuthClientCredentials class
Represents credentials required for client grant
field	description	type	possible value
clientId	Client identifier	String	hexadecimal value or key
clientSecret	Client secret	String	hexadecimal value or key

OAuthApplicationUserCredentials class
Represents credentials required for application grant
field	description	type	possible value
clientId	Client identifier	String	hexadecimal value or key
clientSecret	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
deviceName	Name of device from which user is connecting	String

OAuthDeviceCredentials class
Represents credentials required for device grant
field	description	type	possible value
clientId	Client identifier	String	hexadecimal value or key
clientSecret	Client secret	String	hexadecimal value or key
uuid	Unique, universal identifier of device	String	/vendor/unknown/cashier/dotnettest1

Received tokens

In Java SDK currently exist 3 types of tokens. Every token extends base class called AccessToken what means that when you'll create in the future new token type you also must extend this class.

Short introduction to existing token types in Java

Currently are implemented classes OAuthClientToken, OAuthApplicationUserToken and OAuthDeviceToken, which are a bit different what is shown below.

OAuthClientToken class has fields:

accessToken
tokenType
scope

OAuthApplicationUserToken class has fields:

accessToken
tokenType
scope
refreshToken

OAuthDeviceToken class has fields:

deviceCode
userCode
verificationUrl
interval

A base class for all above classes is AccessToken class, which has fields:

expiresIn
createdAt

Authentication token storage

In Java exists a cache solution using to store authentication token in cache. The cache solution consists of CacheItem abstract class with three important methods. If you would like to store authentication token in cache you must extend the CacheItem 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.

CacheItem abstract class methods

wasExpiring(AccessToken accessToken) - The method to check whether key isn't expired. Returns true or false.
set(String name, AccessToken accessToken) - The method to set authentication token as a cache item.
get(String name) - The method to get cache item for given name. Returns AccessToken class instance.

Authentication examples

Here are 3 code blocks examples. Only first code block example contains an explanation, because others examples are very similar to the first example and no needed to explain it.

Example for client credentials:

OAuthClientCredentials oAuthClientCredentials = new OAuthClientCredentials(
	"...",
	"..."
);
Authenticator authenticator = new Authenticator(oAuthClientCredentials);
OAuthClientToken accessToken = (OAuthClientToken) authenticator.getToken();
 
 
PaymentSecupayDebitsApi debitApi = new PaymentSecupayDebitsApi();
ApiClient debitApiClient = debitApi.getApiClient();
debitApiClient.setAccessToken(accessToken);

Explanation:

From line 1 to line 4 we pass clientId and clientSecret to OAuthClientCredentials constructor and we create a new object of this type
At line 5 we create Authenticator object providing it OAuth*Credentials object corresponding to grant required for particular API
At line 6 we call getToken() method from Authenticator and we save result in accessToken variable of type OAuthClientToken
At line 8 we create instance of specific API
At line 9 we get ApiClient object using getApiClient method from PaymentSecupayDebitsApi class
At line 10 we set accessToken to ApiClient

Example for application user credentials:

OAuthApplicationUserCredentials oAuthApplicationUserCredentials = new OAuthApplicationUserCredentials(
	"...",
	"...",
	"...",
	"...",
	"...",
	"..."
);
Authenticator authenticator = new Authenticator(oAuthApplicationUserCredentials);
OAuthApplicationUserToken accessToken = (OAuthApplicationUserToken) authenticator.getToken();
 
 
PaymentSecupayDebitsApi debitApi = new PaymentSecupayDebitsApi();
ApiClient debitApiClient = debitApi.getApiClient();
debitApiClient.setAccessToken(accessToken);

Example for device credentials:

OAuthDeviceCredentials oAuthDeviceCredentials = new OAuthDeviceCredentials(
	"...",
	"...",
	"..."
);
Authenticator authenticator = new Authenticator(oAuthDeviceCredentials);
OAuthDeviceToken accessToken = (OAuthDeviceToken) authenticator.getToken();
 
 
PaymentSecupayDebitsApi debitApi = new PaymentSecupayDebitsApi();
ApiClient debitApiClient = debitApi.getApiClient();
debitApiClient.setAccessToken(accessToken);