Third party keys
A third party key is an access key for an external service, such as Cesium Ion, Google or OpenAI, saved on your account. We call the record a Program Key. Each record holds one key and is named by a program ID, which tells the applications what the key is for.
You manage them in Operator's Third Party Keys panel, or through the API. Navigator, Operator and the API look keys up by program ID, so a key only takes effect when it is saved under the exact ID listed below.
This article will cover the Program Key record, the program IDs we read, and the requests that manage them. Each provider then has its own page on what the key powers and how to set it.
Data model
Below is the core data model for a Program Key. The program ID is the record's unique ID, so an account has at most one key per program ID.
Program IDs
These are the program IDs that Nextspace applications read. They are PascalCase. Write each one exactly as shown: the web Navigator and Operator compare the ID exactly, so a key saved as "cesiumion" is ignored by them.
Where one service has more than one ID, each ID is a separate record. Save the key under every ID whose features you want.
| Program ID | Service | Operator field | Used for |
|---|---|---|---|
| "CesiumIon" | Cesium Ion access token | Cesium Ion | Cesium World Terrain, Cesium Ion imagery and tilesets, location search, tileset generation. |
| "GoogleApi" | Google Maps Platform API key | Google API | The "Google address" search, "GoogleSearch" and "GoogleAirQuality" Menu Items, geocoding in Data Mappings. |
| "GooglePhotogrammetry" | Google Maps Platform API key | Google Photorealistic Tiles | Google Photorealistic 3D Tiles. |
| "ChatGPT" | OpenAI API key | ChatGPT | AI actions other than Ask Nextspace, such as AI suggested Data Transforms and Data Mappings, and Document View hot-spot detection. |
| "BingMaps" | Bing Maps key | Bing Maps | Bing Maps base maps, only when CesiumJS cannot load them from Cesium Ion. |
| "Mapbox" | Mapbox access token | Mapbox | Mapbox base maps in the web Navigator. |
| "StadiaMaps" | Stadia Maps API key | Stadia Maps | Stamen Water Color and Stamen Toner base maps. |
| "Thunderforest" | Thunderforest API key | Thunderforest | Thunderforest Cycle, Transport and Landscape base maps. |
| "OpenWeather" | OpenWeather API key | OpenWeather | Weather layers in the web Navigator. |
You can read about each provider in Cesium Ion, Google, OpenAI and Map layers and weather.
The "ProgramKey.EProgramId" enum in bruce-models names most of these IDs. It does not include "OpenWeather", so pass that one as a plain string.
The API and the Unreal Navigator match program IDs without regard to case when they read a key for a feature, but the web Navigator and Operator do not, so always save the exact ID.
Requesting keys
You can request every Program Key on the account, or one by its program ID. Requesting a program ID that has no record returns a 400 error with the code "NotFound", so request the list when you only want to check whether a key is set.
Get a list of Program Keys
Get Program Key by program ID
Set a key
You can create or update a key with one POST. The record is matched by "ProgramId": if the account has no record for it, one is created, otherwise the existing record is updated. Only the properties you include are changed. A body without "ProgramId" returns a 400 error with the code "MissingArgument".
Operator clears a key by saving an empty "Key", which every feature treats as not set. You can also delete the record, as described below.
Create or update Program Key
When you are given several keys, save each one under its program ID with its own request. Here is an example using bruce-models.
Delete a key
We don't provide any bulk deletion but you can delete by program ID. Deleting a program ID that has no record still succeeds.