Authentication

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

By default SDK will use file based cache to store tokens. If your application runs on multiple servers, you need to configure SDK with your cache solution.

SDK can work with any PSR-6 compliant cache system.

Authentication example

use \Secuconnect\Client\Configuration;
use \Secuconnect\Client\Authenticator;
use \Secuconnect\Client\OauthCredentials;

$clientId = '...';
$clientSecret = '...';

// If you use cache solution, and want SDK to store tokens through it
// Configuration::getDefaultConfiguration()->setCache($yourPSR6Cache);

// Creates authenticator object with OAuth authentication and obtains token
$auth = new Authenticator(OauthClientCredentials::from($clientId, $clientSecret));
$accessToken = $auth->getToken();

// Saves the token to the Swagger default configuration
Configuration::getDefaultConfiguration()->setAccessToken($accessToken);

// Your API calls follow ...

When calling $auth->getToken() an HTTPS request is sent. The HTTPS call will be similar to that below:

POST /api/v2/Auth/authorize?... HTTP/1.1
...

When successful the server will respond with something like that:

HTTP/1.1 200 OK
Content-Type: application/json
{
  "access_token": "eyJz93a...k4laUWw",
  "token_type":"Bearer",
  "expires_in":86400
}

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.