The SpatialKey embedded client API provides the ability to launch SpatialKey and log users directly into the application bypassing the login screen.  This allows SpatialKey to be integrated into existing applications within an iFrame or launching in a separate browser window without requiring them to log into a separate system. When launching the SpatialKey client you have the option to launch directly to the home screen, into a saved dashboard, or use a dashboard template to launch with datasets of your choosing.

The embedded client API is a secure way to launch the client allowing you to use unique credentials for every user or a single set of credentials if you are using a single user account to expose a shared dashboard to multiple users.  The API utilizes OAuth v2 to create a JSON Web Token (JWT) that is passed in the URL (or as form elements in a POST) to launch the client combined with additional parameters to determine how the client functions.

The sections in this document will help you manage and/or create your own Embedded Client API.


To launch the client you must first create an OAuth v2 JSON Web Token (JWT).  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.

OAuth parameter needed for user authentication

The following table lists the OAuth parameter that need to be passed to the SpatialKey client to authenticate the user. To use the Embedded Client API, you must create an OAuth JSON Web Token. To do this, first obtain the API Keys, then generate the OAuth JSON Web Token.

Authentication Parameter Description
oAuthToken={jwt token} JWT (assertion) parameter 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.

Parameters to control the SpatialKey client

In addition to the parameters listed above there other parameters that can be used to control the behavior of the SpatialKey client. At least one of these parameters are required. There are examples below explaining how these parameters are used. The oAuthToken and all parameters below can be passed as HTML form fields (via POST) or as URL query string attributes (via GET).

Parameter Default Description
dashboardID Dashboard ID to be launched. Can be saved dashboard or saved dashboard template.
allowMoreDatasets false Allow more datasets to be added in the dashboard. This will load all the datasets that the authenticated user has access to and make them available to be added to the dashboard.
allowSave false Allow saving (or save as) from within a dashboard. If enabled dashboards will be saved as the current logged in user authenticated through the API
allowHome false Allow access to the home interface
datasetIDs IDs of the datasets to load into the dashboard template or the new dashboard. For example: datasetIDs=8a808c483f52ae51013f537dd5ec034f,8ace0afb38e8ff600138f9d748530618 (In the format dataset1, dataset2, datasetX…etc. as seen in the dashboard template screen)

If you are using the API to upload your datasets you can also pass in the Upload ID instead of a Dataset ID, which you receive when you start a new upload. This allows you to kick off loading SpatialKey before your upload is fully complete. Put “upload-” before the upload ID to use this feature. For example: datasetIDs=upload-768adc883f72ae51013f537dd5ec0a12

You can also mix and match Upload IDs and Dataset IDs. The following example references one Dataset ID and one Upload ID: datasetIDs=8a808c483f52ae51013f537dd5ec034f,upload-768adc883f72ae51013f537dd5ec0a12

appID If launching a new unsaved dashboard, you can initialize an app with data by setting the appID and the datasetIDs
Map Analyst = mapanalyst
Blank Canvas = blankcanvas

There are additional parameters you can use if you are launching the Underwriting App. See below for a full list of Underwriting parameters.

Token Validation

Use the following URL to run a simple validation on your token.

https://{spatialkey server}/?testtoken=1&oAuthToken={jwt token}

Here is an example with the server and authtoken plugged in:


The following are examples of what the Embedded Client API can be set up to do.  There is a Embedded Client URL for each of these examples – in the following section, you will learn how to build these examples.

Loading the client to the home interface

This example will authenticate a user and will take them straight to the home interface where apps and datasets are listed.


Loading a saved dashboard with full dashboard functionality

This example loads a saved dashboard and allows users to add new datasets, save a new version of the dashboard and close the dashboard to return to the home interface. Performance note: loading all datasets up front will result in a longer initial load time. The next example, which does not allow adding more datasets to a dashboard, will initialize faster.


Loading a saved dashboard with restricted functionality

This example loads a saved dashboard but restricts users from adding new datasets, saving updates or a new version of the dashboard and does not allow them to close the dashboard to return to the home interface. This is the most locked down example and perfect if you just want to embed a dashboard within your system.


Loading an app with a dataset

This example opens the Map Analyst app with a dataset. The defaults for all other parameters apply (allowSave=false, allowHome=false, allowMoreDatasets=false..etc) unless you specifically override them.


Loading a dashboard template

Dashboard templates allow you to create common dashboards that can be used across different datasets without creating the dashboard from scratch each time. In the example below we are loading the saved dashboard template with the ID  8a808c483f52ae51013f537dd5ec034f  Within this dashboard we are loading two datasets with the IDs 8a808c483f52ae51013f537dd5ec034f and 8a808c483f52ae51013f537dd5ec029g. These two datasets must  be of the same type (point or shape) and have the same field names as the datasets used to create the dashboard template.  The dataset ID’s must be in the same order that they are listed in the template screen within the SpatialKey client.


Underwriting App Parameters

The Underwriting App has some special parameters (in addition to the parameters listed above). You can launch the app in a few different ways:

  • with an address that will be geocoded
  • with a latitude/longitude coordinate
  • with a schedule of locations
Launching the Underwriting App with an address:
Parameter Description
appID appID should be passed in as ‘underwriting’
street The street address to geocode, including number and street name. Example: 123 Main St.
city The city to geocode. Example: San Francisco
postal The postal code to use for geocoding. Example: 94118
state The state to use for geocoding. Example: CA
country The country to use for geocoding. Example: USA
geocoder If your organization licenses multiple geocoders you can specify which one to use. Possible options are: tomtom, mapquest, mqpremium, skusa. This is optional, and if not passed in your organization’s default geocoder will be used.
datasetID If you are launching with an exiting portfolio, you can optionally pass in the portfolio dataset ID. This should be the ID of an existing dataset in SpatialKey.
Launching the Underwriting App with latitude/longitude:
Parameter Description
appID appID should be passed in as ‘underwriting’
lat The latitude of the location.
lng The longitude of the location
datasetID If you are launching with an exiting portfolio, you can optionally pass in the portfolio dataset ID. This should be the ID of an existing dataset in SpatialKey.
Launching the Underwriting App with a schedule of locations:
Parameter Description
appID appID should be passed in as ‘underwriting’
datasetIDs The schedule ID can be either an existing dataset ID in SpatialKey, or a new upload ID retrieved when kicking off an API upload. Upload IDs should be prepended with “upload-“, so a sample might look like: upload-768adc883f72ae51013f537dd5ec0a12. If launching with both a schedule and a portfolio, you should use the single datasetIDs parameter and pass in both the IDs of the schedule and the portfolio, separated by a comma. The schedule should always come first, followed by the portfolio. The following example uses an upload ID for the schedule and a dataset ID for the portfolio: datasetIDs=8a808c483f52ae51013f537dd5ec034f,upload-768adc883f72ae51013f537dd5ec0a12