Location Hub (+)

Address Assert (+)

Address Recognition (+)

Address Suggest

Authentication (+)

Elevation Service

File Management Service

Flood Service (+)

Point in Polygon Service

Proximity Service

Reverse Geocode

Location Hub Viewer (+)

Authentication

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

https://dc1.spatialstream.com/ssapi/rest/v1/{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

POST https://dc1.spatialstream.com/ssapi/rest/v1/recognition/oauth2/token/ HTTP/1.1
Accept-Encoding: gzip,deflate 
Content-Type: application/x-www-form-urlencoded 
Content-Length: 119 
Host: dc1.spatialstream.com 
Connection: Keep-Alive 
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)

grant_type=client_credentials&client_id=clientIdrealValue&client_secret=topsecret

 

Sample HTTP POST Response

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

 

 Sample Token Management Code (C#)

private string tokenRequestURL= "https://dc1.spatialstream.com/ssapi/rest/v1/{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)
    WebOperationContext.Current.OutgoingRequest.Headers[HttpRequestHeader.Authorization]
        = token;

 

The HTTP POST request would look something like this:

POST https://lhrecognition.dmtispatial.com/services/recognition/v2.2 HTTP/1.1
Accept-Encoding: gzip,deflate
Content-Type: text/xml;charset=UTF-8
SOAPAction: "RecognizeFreeForm"
Authorization: bearer ***********************************
Content-Length: 1809
Host: lhrecognition.dmtispatial.com
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.

back to top