A first step to using any of the SpatialKey APIs is authentication. You must prove that you have credentials to login and perform the action you will use the API to achieve.  Depending on what action you are taking through the API, the steps to authenticate are a bit different.

  • Data Management API Command Line Tool – authentication is done directly through keys inputted into the Command Line Tool XML
  • Embedded Client API – authentication requires the generation of an OAuth JSON Web Token (JWT)
  • Data Management API – authentication requires the generation of a OAuth JSON Web Token (JWT) and an additional call will generate the final OAuth Access Token that will be used in the API calls

The remainder of this document will step through each of the connective arrows and steps from the diagram above.

Obtaining the API Keys

Obtain the following three keys: You will need to be an Super Admin in SpatialKey to access the Organization API keys.

User API Key – Available in SpatialKey under the People tab.

Screen Shot 2015-01-24 at 1.08.07 AM

Organization API Keys – Available in SpatialKey under the Admin tab. Also available in the user tab above for Admin users.

Generating the OAuth JSON Web Token

This is an encrypted, time sensitive token that will contain the authentication keys to be passed over to the SpatialKey client representing the organization and user for authentication. The maximum amount of time a single created JWT can be valid is up to 1 hour from the current date and time (UTC).  This is a security feature ensuring that the JWT created for this authentication could not be stolen and used again at a future time as a new one would be needed to be created.

Using Java to create OAuth JSON Web Token

Note that this class requires the use of the Apache Commons Codec jar to work.  You can substitute another class that does Base 64 encoding or have the Apache Commons Codec jar on your classpath.  You can download sample Java code here.

Using the Java example you can simply take the string returned from this method and use it for the oAuthToken param.

  • userAPIKey – User API Key
  • orgAPIKey –  Organization API Key
  • orgSecretKey – Organization Secret Key
  • ttl – time in seconds before the authentication token expires (max of 3600)

Java method call (used to get OAuth Token):

public static String getOAuthToken(String userAPIKey, String orgAPIKey, String orgSecretKey, int ttl)

Using .NET to create OAuth JSON Web Token

You can download sample .NET code here.

Using other coding languages to create OAuth JSON Web Token

If using coding languages other than Java or .NET, the JWT will need to be constructed programmatically.

General JSON Web Token Format:

{Base 64 Encoded Header}.{Base 64 Encoded Claims Payload}.{Encrypted Header and Payload}

Example of a finished Web Token:

eyJhbGciOiJTSDI1NiJ9.eyJpc3MiOiAiMzU4MjE0OTQtYjFlNC00Y2M5LWJkZDQtM2NjMWQ4OTJkMjFmIiwgInBybiI6ICIzNTgyMTQ5NC1iMWU0LTRjYzktYmRkNC0zY2MxZDg5MmQyMWUiLCAiYXVkIjogImh0dHBzOi8vY2x1c3Rlclguc3BhdGlhbGtleS5jb20vb2F1dGgvdG9rZW4iLCAiZXhwIjogIjEzNzM1NjEwNTQiLCAiaWF0IjogIjEzNzM1NjA5OTQifQ.A6-YvHydhc4YVE3TwmhomrURlblJCMC90whzVwF5_sc

Notice that each section of the JWT is separated by a “.”.  Only the last section is encrypted using the secret key for the organization and that the secret key will never be sent as part of the JWT.

{Base 64 Encoded Header}

The JWT header contains information about the encryption used.  For this use case it will always be the Base 64 encoded version of this text:

{“alg”:”SH256”}

{Base 64 Encoded Claims Payload}

The JWT claims contains the important information about the use and organization needed to create a successful authentication.  This will also be a block of JSON text that will be Base 64 encoded.  The claim text contains the following signature:

{“iss”:“org key”,”prn”:”user key”,”aud”:”https://www.spatialkey.com”,”exp”:”time to live”,”iat”:”current time”}
  • iss: the organization API key
  • prn: the user API key
  • aud: the text “https://www.spatialkey.com”
  • exp: the time in seconds since January 1st 1970 UTC (also known as system time or UNIX epoch) plus the number of seconds before the JWT should expire (maximum of 1 hour into the future).  It is important that this time be UTC milliseconds based (divide by 1000 to get the seconds).
  • iat: the current time in seconds since January 1st 1970 UTC

{Encrypted Header and Payload}

After combining the Base 64 encoded versions of the JWT Header and JWT claims separated by a “.” the encryption can take place.  The required encryption is HmacSHA256.  The entire Base 64 encoded text of the {header}.{claims assertion} is encrypted and that result also Base 64 encoded.  The resulting encoded and encrypted text is added to the payload.

Generating the OAuth Access Token

Note that the OAuth Access Token is generated by the server. In order to trigger the generation of the OAuth Access Token, you must first generate the OAuth JSON Web Token (described in the section above). If the OAuth Access Token expires you will need to authenticate again and generate a new one.

The documentation below will walk through the steps to generate the OAuth Access Token. If you want to jump directly to all OAuth Access Token related calls, click here.

Required parameters for OAuth Access Token generation

  • grant_type: “urn:ietf:params:oauth:grant-type:jwt-bearer”
  • assertion: OAuth JSON Web Token

Generating the OAuth Access Token

HTTP Call: POST

https://[spatialkey URL]/SpatialKeyFramework/api/v2/oauth.json

Note: With the SpatialKey API you choose whether you want to use XML or JSON and you control this by ending the calls in either .json or .xml. In the authentication example above  we are using JSON.

Returns: access token

TokenResponse {
expires_in (int64): The number of seconds until the token expires,
token_type (string): The type of token. Currently Bearer,
access_token (string): The token to use in the URL of future calls. For example: /SpatialKeyFramework/api/v2/dataset?token=TOKEN
}

**In addition to the token returned there will be a cookie named “ROUTEID” that should be passed as a cookie in all subsequent calls after authenticating. This cookie will be in the format .c1f1. This is important since it will ensure that your session is sticky to a specific server.

Validating the OAuth Access Token

At times you may want to validate that your access token is still active prior to making a call.

Required parameters

  • token: OAuth Access Token generated from the POST call

Validating the OAuth Access Token

HTTP Call: GET

https://[spatialkeyURL]/SpatialKeyFramework/api/v2/oauth.json?token={access_token}

Note: With the SpatialKey API you choose whether you want to use XML or JSON and you control this by ending the calls in either .json or .xml. In the authentication example above  we are using JSON.

TokenResponse {
expires_in (int64): The number of seconds until the token expires,
token_type (string): The type of token. Currently Bearer,
access_token (string): The token to use in the URL of future calls. For example: /SpatialKeyFramework/api/v2/dataset?token=TOKEN
}