Basic Authentication

Basic Authentication

The Location Hub® Viewer API utilizes Basic Authentication for authorization and access of the services. Basic Authentication sends a Base64 encoded string that contains a user name and password for the client via HTTP headers. Base64 is not a form of encryption and should be considered the same as sending the user name and password in clear text. However, all traffic is encrypted and transmitted over a TLS v1.2 (Transport Layer Security) connection, and therefore the user name and password is protected during transmission.

The user credentials are sent using the HTTP Authorization header. The header is constructed as follows:

  • Concatenate username and password into a string with a colon between as shown: “username:password”
  • Encode the resulting string in a Base64 variant
  • Prefix the encoded string with “Basic ”; the space after Basic is required

These encoded credentials are then sent in the HTTP Authorization header with every Location Hub Viewer API request.



using System;
using System.Collections.Generic;
using System.Linq;
using System.Net;
using System.Text;
using System.Threading.Tasks;
namespace BasicAuthenticationTest
    class Program
        static void Main(string[] args)
            string requestURL = "https://the.service.url/v1/";
            string serviceMethod = "GetRequest";
            string username = "YourUserName";
            string password = "YourPassword!";
            Console.Out.WriteLine("Request Url: " + requestURL);
            WebRequest request = WebRequest.Create(requestURL + serviceMethod);
            WebResponse response = null;
                if (username != null)
                    string authInfo = username + ":" + password;
                    authInfo = Convert.ToBase64String(Encoding.Default.GetBytes(authInfo));
                    Console.Out.WriteLine("Base64 Encoded String: " + authInfo);
                    request.Headers["Authorization"] = "Basic " + authInfo;
                response = request.GetResponse();
                Console.Out.WriteLine("Response Header:");
                foreach (var header in response.Headers)
                    Console.Out.WriteLine("t" + header + " = " + response.Headers[header.ToString()]);
            catch (WebException ex)
                Console.Out.WriteLine("HTTP Status: " + ex.Message);
                if (response != null)
                    Console.Out.WriteLine("HTTP Status: " + ((HttpWebResponse)response).StatusCode);




Using OAuth 2.0 to access Location Hub

Location Hub uses Web Service authentication for authorization and access based on OAuth 2.0 protocol. All information transmitted to Location Hub services is encrypted using Secure Socket Layer (SSL) technology.

The Location Hub® Viewer API utilizes Basic Authentication for authorization and access of the services. Please refer to the Basic Authentication page for more details.

Basic Workflow

To summarize, the workflow is as follows:

  • Request an access token from the Authentication server using the client application’s credentials. Please contact your account executive to obtain your client credentials (client_id and client_secret).
  • Cache the authentication token for use in all requests until it expires.
  • Use the authentication token to make requests to Location Hub, until the authentication token expires. When the token has expired, the process should be repeated.

Requesting a Token

Tokens are retrieved using a simple HTTP POST request and then the token is appended to each service request in the “Authorization” HTTP header. The token request url is different for each Location Hub Service being accessed and requires the service name as part of the url. When requesting a token, the following url must be used:

Token Request url{service_name}/oauth2/token/

  • {service_name} – This is the specific Location Hub web service name that must be included in the token request url. Please contact your account executive to obtain your service name.

The POST request requires the following three parameters in the body of the request:

  • grant_type – This must be set to “client_credentials”
  • client_id – The unique Client ID provided by your account executive
  • client_secret – The unique Client Secret provided by your account executive

Sample HTTP POST Request

Accept-Encoding: gzip,deflate 
Content-Type: application/x-www-form-urlencoded 
Content-Length: 119 
Connection: Keep-Alive 
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)



Sample HTTP POST Response

    "token_type": "bearer",
    "access_token": "0BqfgTJC7wZ7C2KeekssswRu8E7x1GFGG",
    "expires_in": 28800 


 Sample Token Management Code (C#)

private string tokenRequestURL= "{service_name}/oauth2/token/";
private string clientSecret = "Client_Secret";
private string clientID = "Client_ID";
// {service_name} is the specific Location Hub web service name that must be included in the token request URL
Dictionary<string, KeyValuePair<string, DateTime>> tokens = new Dictionary<string, KeyValuePair<string, DateTime>>();
public string GetToken(string serviceName)
    lock (tokens)
        private string uriAddress = tokenRequestURL.Replace("{service_name}", serviceName); 
        KeyValuePair<string, DateTime> tokenPair;
        if (!tokens.TryGetValue(uriAddress, out tokenPair) || tokenPair.Value < DateTime.UtcNow)
            var tokenResponse = GetOAuthToken(uriAddress);
            if (tokenResponse != null)
                // the returned token must be preceded with "bearer "
                string authToken = string.Format("bearer {0}", tokenResponse.Value.Key);
                // request new token when we are at 20% from the expiration time
                DateTime tokenExpiry = DateTime.UtcNow.AddSeconds(tokenResponse.Value.Value * 4 / 5);
                tokenPair = new KeyValuePair<string, DateTime>(authToken, tokenExpiry);
                tokens[uriAddress] = tokenPair;
        return tokenPair.Key;
private KeyValuePair<string, int>? GetOAuthToken(string tokenRequestAddress)
    WebClient authClient = new WebClient();
    authClient.BaseAddress = tokenRequestAddress;
    NameValueCollection values = new NameValueCollection();
    values.Add("grant_type", "client_credentials");
    values.Add("client_id", clientSecret);
    values.Add("client_secret", clientID);
    byte[] tokenResponseInBytes = authClient.UploadValues(tokenRequestAddress, values);
    string tokenResponse = Encoding.UTF8.GetString(tokenResponseInBytes);
    dynamic token = JsonConvert.DeserializeObject(tokenResponse);
    string access_token = token["access_token"];
    int expiry = token["expires_in"];
    return new KeyValuePair<string, int>(access_token, expiry);


Using the Token

Once you have received the token and cached it, you can use the cached token in all calls to Location Hub by including it as the HTTP Authorization header. Attaching the token as the Authentication header can be done using the example below:

string serviceName = "recognition";
var token = GetToken(serviceName);
if (token != null)
        = token;


The HTTP POST request would look something like this:

Accept-Encoding: gzip,deflate
Content-Type: text/xml;charset=UTF-8
SOAPAction: "RecognizeFreeForm"
Authorization: bearer ***********************************
Content-Length: 1809
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)


Token Expiry

When a token is issued, the expires_in value in the response is the number of seconds from the time of issue that the token will be valid for. The default token expiry time is 8 hours form time of issue.

The token expiry is defined in the following response parameter:

  • expires_in: The number of seconds from the time of issue that the token will expire

It is recommended that you request a new token before the expiry time.