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.

interface IProgramKey {
    // The program ID, which says what the key is for. Limited to 60 characters.
    // See the program IDs section below for the values the applications read.
    ProgramId: string;
    // The access key itself. Limited to 240 characters.
    Key?: string;
    // True when the record has a non-empty key.
    // This is returned by the API and ignored when saving.
    Available?: boolean;
    // ISO 8601 date time strings, set by the API.
    Created?: string;
    Updated?: string;
}

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 IDServiceOperator fieldUsed for
"CesiumIon"Cesium Ion access tokenCesium IonCesium World Terrain, Cesium Ion imagery and tilesets, location search, tileset generation.
"GoogleApi"Google Maps Platform API keyGoogle APIThe "Google address" search, "GoogleSearch" and "GoogleAirQuality" Menu Items, geocoding in Data Mappings.
"GooglePhotogrammetry"Google Maps Platform API keyGoogle Photorealistic TilesGoogle Photorealistic 3D Tiles.
"ChatGPT"OpenAI API keyChatGPTAI actions other than Ask Nextspace, such as AI suggested Data Transforms and Data Mappings, and Document View hot-spot detection.
"BingMaps"Bing Maps keyBing MapsBing Maps base maps, only when CesiumJS cannot load them from Cesium Ion.
"Mapbox"Mapbox access tokenMapboxMapbox base maps in the web Navigator.
"StadiaMaps"Stadia Maps API keyStadia MapsStamen Water Color and Stamen Toner base maps.
"Thunderforest"Thunderforest API keyThunderforestThunderforest Cycle, Transport and Landscape base maps.
"OpenWeather"OpenWeather API keyOpenWeatherWeather 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

Response
interface IResponse {
    // Array of Program Key records, ordered by program ID.
    // See the data model above for the record structure.
    Items: IProgramKey[];
    // Number of records returned.
    TotalCount: number;
}
Javascript example

Get Program Key by program ID

Response
// The response is the Program Key record directly.
// See the data model above for the record structure.
Javascript example

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

Request body
// Body should be the Program Key JSON as specified at the top of the article.
// ProgramId and Key are the only values you need to send.
Response
// The response is the saved Program Key record.
// See the data model above for the record structure.
Javascript example

When you are given several keys, save each one under its program ID with its own request. Here is an example using bruce-models.

import { ProgramKey } from "bruce-models";

const keys = [
    { ProgramId: ProgramKey.EProgramId.CesiumIon, Key: "your-cesium-ion-access-token" },
    { ProgramId: ProgramKey.EProgramId.GoogleApi, Key: "your-google-api-key" },
    { ProgramId: ProgramKey.EProgramId.GooglePhotogrammetry, Key: "your-google-api-key" },
    { ProgramId: ProgramKey.EProgramId.ChatGPT, Key: "your-openai-api-key" },
    // Not in EProgramId, so it is passed as a string.
    { ProgramId: "OpenWeather", Key: "your-openweather-api-key" }
];

for (const programKey of keys) {
    await ProgramKey.Update({ programKey });
}

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.

Delete Program Key

Javascript example