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:

  1. Create OAuth*Credentials instance for particular grant.
  2. Create Authenticator instance passing it OAuth*Credentials instance generated in step 1.
  3. Invoke getToken() method from Authenticator class
  4. 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
  5. 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
fielddescriptiontypepossible 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
fielddescriptiontypepossible 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
fielddescriptiontypepossible 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

  1. wasExpiring(AccessToken accessToken) - The method to check whether key isn't expired. Returns true or false.
  2. set(String name, AccessToken accessToken) - The method to set authentication token as a cache item.
  3. 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 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);