Authorization

API uses the OAuth 2.0 protocol for authentication and authorization. Basic pattern follows four steps:

Basic steps

1. Obtain OAuth 2.0 credentials

To begin, obtain client credentials from the provider. Client credentials are:

• username: together with password identifies individual user in provider system
• password: together with username identifies individual user in provider system
• client_id: provider generated identifier for consumer application
• secret: secret phrase which is used by client and api to generate random hashed signature used for client authentication

2. Obtain an access token from the API authorization server

Before client can access API methods, it must obtain an access token that grants access. Client sends the token request to the API authorization server, which returns access token and refresh token. Client extracts tokens from the response, and stores them for later use.

Token request

Token response example

{  
"access_token":"6J3QE7m7Cb5F1FiuXo4LBV2fOfp04FdjoI...",
"token_type":"bearer",
"expires_in":3599,
"refresh_token":"1ec55c2b8a8f4503a99bf917ce5452c8",
".issued":"Tue, 08 Mar 2016 14:59:49 GMT",
".expires":"Tue, 08 Mar 2016 15:59:49 GMT"
}

2.2 Signature generation

Token request should be signed with hashed signature used for client authentication, provided in parameter "signature". Parameter "signature" value should be generated for every authorization request as base64 encoded string representation of SHA512 hash of composite key built using following pattern: {username}{salt}{secret}{password}{salt}{secret}{client_id}

IMPORTANT: Make sure to use random "salt" parameter for each authorization request.

IMPORTANT: Make sure to safely store and use "secret" parameter, as it should never be accessible to public.

Test case

Example code C#

using System;
using System.Security.Cryptography;
using System.Text;
string username = "UU";
string password = "PP";
string clientId = "CC";
string salt = "00";
string secret = "SS";
string compositeKey = username + salt + secret + password + salt + secret + clientId;
HashAlgorithm hashAlgorithm = new SHA512CryptoServiceProvider();
byte[] byteValue = Encoding.UTF8.GetBytes(compositeKey);
byte[] byteHash = hashAlgorithm.ComputeHash(byteValue);
string signature = Convert.ToBase64String(byteHash);

Example code Java

import java.security.MessageDigestSpi;
import org.apache.commons.lang3.StringUtils;
String username = "UU";
String password = "PP";
String clientId = "CC";
String salt = "00";
String secret = "SS";
String compositeKey = username + salt + secret + password + salt + secret + clientId;
MessageDigest md = MessageDigest.getInstance("SHA-512");
md.update(str.getBytes());
byte byteData[] = md.digest();
String signature = StringUtils.newStringUtf8(Base64.encodeBase64(byteData, false));

Example code PHP

$username = "UU";
$password = "PP";
$clientId = "CC";
$salt = "00000000";
$secret = "SS";
$compositeKey = $username.$salt.$secret.$password.$salt.$secret.$clientId;
$hash = hash("sha512" , $compositeKey, true);
$signature = base64_encode($hash);

2.2 Authorization error codes

Authorization server responds with error messages to invalid authorization requests. For security reasons, errors are not descriptive, but they contain error code. List of possible error codes with description is provided here:

• Error code: 1: missing parameter "client_id"
• Error code: 2: invalid parameter "client_id", means that client with provided "client_id" does not exist in provider system
• Error code: 3: client exist, but is currently disabled in provider system
• Error code: 4: missing parameter "signature"
• Error code: 5: missing parameter "salt"
• Error code: 6: invalid "salt" parameter length, allowed "salt" length range is 8 - 50
• Error code: 7: "signature" mismatch, provided "signature" is different than server generated value
• Error code: 9: unable to find user with provided "username" and "password"
• Error code: 11: missing parameter "username"
• Error code: 12: missing parameter "password"
• Error code: 13: user is inactive, please contact provider
• Error code: 14: partner is inactive, please contact provider

3. Send the access token to an API

Client sends access token to any of available API methods. Token is sent in an HTTP authorization header.

Authorization HTTP header

4. Refresh the access token, if necessary

The access token has a limited life time expectancy. The "expires_in" parameter passed along at the roken response stage provides tokens life time in seconds. If an expired token is used the API will respond with unauthorized response error (HTTP status 401). This means client should use the refresh token to generate new access token. If refresh token is no longer valid, the client repeats the process.

There is the possibility that a granted token might no longer work. A token might stop working for one of the following reasons:

• token life time has expired
• aditional unexpected conditions

Refresh token request