Application Development Guide

---

Terms

JSON Web Token (JWT)
: An open, industry standard method for representing claims securely between two parties. IETF RFC 7519

AppKey
: The application identity key which is assigned to a specific application for authorization with GeoToolSuite services.

---

QA and Testing Reference

Please refer to the Quality Assurance and Testing Guide documentation for additional details about the service.

---

Creating a JSON Web Token (JWT) for Testing

Before running any tests, you must have a valid AppKey for testing. Please contact a GTS team member to get a test AppKey and the required JWT secret.

There are 2 easy ways to create a JWT token for testing:

Option 1: Create the token with jwt.io

Visit the jwt.io site and scroll down to the Debugger section.

The Header provided in their debugger does not need to change. It should already look like this:

{
  "alg": "HS256",
  "typ": "JWT"
}

The Payload section will need to be completely replaced with our payload section, which looks like this for a get_map_data request (without the OPTIONAL comment):

{ 
  "appkey": "insert-your-appkey-here",
  "resource": "get_map_data",
  "project_name": "tests",
  "map_name": "osm-tests-wms" // OPTIONAL key
}

The map_name key is optional. appkey, resource, and project_name are the only required keys.

The project_name key is a reference to the Maptimus 2 project name which contains one or more map files. The map_name key refers to the specific map file which is configured to serve specific geodata.

In the Verify Signature section, replace your-256-bit-secret in the provided text box with the secret value provided by the GTS team when you requested a testing AppKey.

Once you've completed replacing the Decoded values, you can copy the token from the Encoded section (it updates live) for use as the X-API-KEY header value in your Maptimus 2 test requests. It should look something like this:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhcHBrZXkiOiJpbnNlcnQteW91ci1hcHBrZXktaGVyZSIsInJlc291cmNlIjoiZ2V0X2luZm8ifQ.FGiv-HSIk-gfGhUgbNjtkYBS7PYOa9F1sJMTxDL8fKI

Option 2: Create the token with code

An example Python script using pyjwt to create a token on your client:

import jwt

my_resource = 'get_map_data'
my_appkey = 'insert-your-appkey-here'
my_secret = 'insert-the-secret-here'
my_algorithm = 'HS256'
my_project = 'tests'
my_map = 'osm-tests-wms' # OPTIONAL key

# function to create the token
def create_token(resource, appkey, secret, algorithm, project, mapname=None):
    """ create a JWT for use with the GeoToolSuite """
    # The mapname key is optional. appkey, resource, and project are the only required keys for the payload.
    payload = {'appkey': appkey, 'resource': resource, 'project_name': project, 'map_name': mapname}
    token = jwt.encode(payload, secret, algorithm)
    return token

# test the function
my_token = create_token(my_resource, my_appkey, my_secret, my_algorithm, my_project, my_map)
print(my_token)

You should replace insert-your-appkey-here with the AppKey provided by the GTS team and replace insert-the-secret-here with the secret key also provided by the GTS team.

The result will look something like:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhcHBrZXkiOiJpbnNlcnQteW91ci1hcHBrZXktaGVyZSIsInJlc291cmNlIjoiZ2V0X2luZm8ifQ.FGiv-HSIk-gfGhUgbNjtkYBS7PYOa9F1sJMTxDL8fKI