Skip to main content
Version: ADONIS 12/ADOIT 13/ADOGRC 11

Token Based Authentication

REST authentication is done using a security hash which is constructed using a public identifier of the client, a secret key of the client, a GUID, a timestamp of the request and the parameters sent with the request. This prevents unauthorized usage of the API and replay and other abuse of requests.

For prerequisites to use Token Based Authentication, see REST API section in the administration manual.

Request Headers

Each authenticated request to the REST API must contain the following four headers in the request:

NameDescription
x-axw-rest-identifierShared identifier of the secret key defined for this client in the Administration Toolkit of the ADOXX-based product.

Example Value:
boc.rest.key.mfb.StandardRESTfulServices
x-axw-rest-guidA GUID to ensure uniqueness of the request.

Generation Example:
final String sGUID = UUID.randomUUID ().toString ();
aMethod.addHeader ("x-axw-rest-guid", sGUID);

Example Value:
d5dfba69-fab6-4156-9294-0c73ac20c5af
x-axw-rest-timestampThe timestamp when the request was sent by the client. The header parameter 'x-axw-rest-timestamp' needs to be a UTC long value in milliseconds.

Generation Example:
final long nDate = new Date ().getTime ();
final String sDate = String.valueOf (nDate);
aMethod.addHeader ("x-axw-rest-timestamp", sDate);

Example Value:
1493365316885
x-axw-rest-tokenHashed security token to ensure validity of the request. For generation example, see details below table.

Example Value:
QIYqykxHA2x+96qYf+S0w1suXswgtRMIquNMg6P6F3LAvbpwEB+23DD8iK1LVDsL6f2fIwxg+DK/pImDtowpeQ==

The algorithm for calculating the hashed security token consists of the following steps:

  1. Get the secret key matching to the identifier sent via the x-axw-rest-identifier header.
  2. Take all request parameter names and put them into a collection.
  3. Take all request parameter values as strings and put them into the same collection.
  4. Take the header names x-axw-rest-identifier, x-axw-rest-guid and x-axw-rest-timestamp and put them into the collection.
  5. Take the values of the x-axw-rest-identifier, x-axw-rest-guid and x-axw-rest-timestamp headers as well as the secret key and put them into the collection.
  6. Sort this collection using Locale en_US.
  7. Convert each item of the collection into a byte array using UTF-8 encoding. (So in the end the whole collection should be converted from Collection <String> to Collection<byte[]>)
  8. Append all items of the byte array collection into a single byte array in the order of their sorting.
  9. Convert the secret key into a byte array using UTF-8 encoding.
  10. Create a new HMac instance using SHA-512 algorithm.
  11. Initialize the HMac instance using the secret key byte array.
  12. Finalize the HMac using the byte array containing all parameters and headers/parameters.
  13. Get the resulting byte array of the HMac.
  14. Convert the byte array into a Base64 encoded string using UTF-8 encoding.