How to use our security – HLC API Documentation v3.0

Transport

To ensure each call is secured, all calls to the service must take place over a secured layer through TLS (via HTTPS).

Tokenization

Security will be provided through the use of tokens that are generated in the web store by the customers. Tokenized security provides a higher level of protection and allows the customers to control when the access tokens or login tokens need to be changed. It also allows them to change those tokens at will.

To access the token creation system, the user must log into the web store at www.hlc.bike and navigate to the User Settings screen (My Account > User Settings). From there, they need to expand the row of the desired user ID. In the External Services tab, they will be able to generate their tokens:

They can generate two types of tokens: an Access Token and a Login Token.

Getting started with Tokens

Within the web store, the customer may generate and manage their tokens from the User Settings page. To access this page, a customer must have the External Services tab enabled by a site administrator. Then, the customer should be able to navigate to their User Settings page (My Account > User Settings) and access their External Services tab. By default, no tokens will exist. They will need to be generated by the user.

To generate a token if one does not exist find the section for the token type you wish to manage (Access or Login), and press the ‘Generate Token’ button.

To remove an existing token, find the section for the token you wish to remove and press the ‘Clear Token’ button. Tokens that are removed are no longer valid and can no longer be used to connect to the API.

To generate a new token first clear the old token if it wasn’t already done, then generate a new token. (See previous steps.)

Using Access tokens

Every call made to the API requires an access token except the function “/System/Token”. The access token must be added to the request in the http authorization header with the key “ApiKey” as illustrated below:

Here is an example showing how to provide an authorization token to the request header.

  
using (var client = new HttpClient())
{
client.BaseAddress = new Uri(URL_HOST_API);
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("ApiKey", "123456456123456789");
…
}

In case you don’t directly want to use the access token, HL API offers a way to obtain the access token from basic authentication (UserName:Password). To do so, the function “/System/Token” must be used. This function requires the “Username:Password” to be added to the request in the http authorization header with the key “Basic” and it must be converted to Base64 as illustrated below:

Here is an example showing how to provide an authorization token to the request header.

  
using (var client = new HttpClient())
{
  client.BaseAddress = new Uri(URL_HOST_API);
  var byteArray = Encoding.ASCII.GetBytes("USERNAME:PASSWORD");
  client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", Convert.ToBase64String(byteArray));
  HttpResponseMessage response = await client.GetAsync("System/Token");

  if (response.IsSuccessStatusCode)
  {
   key = await response.Content.ReadAsAsync<string>();
  }
  else
  {
   // OH NO
  }
}

Note that the API accepts only access tokens to authenticate and authorize calls. If the basic authentication is used to gain access to the API, then it must always be run prior to any calls.

Using Login tokens

A Login Token is needed in order to use the Auto-login service. This feature will use the token to automatically log in with the Customer’s User ID/Password. It can also use the token to load a specific cart upon authentication. The token must be converted to Base64 .As illustrated bellow, it can be used if the client application wants to redirect its users without requiring them to log in: