---
title: "Third party keys"
section: "Third party keys"
route: /thirdpartykeys
account: {accountId}
bruce_api: https://{accountId}.api.nextspace.host
guardian_api: https://guardian.nextspace.host
---
# 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.

```typescript
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 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](/thirdpartykeyscesiumion), [Google](/thirdpartykeysgoogle), [OpenAI](/thirdpartykeysopenai) and [Map layers and weather](/thirdpartykeysmaplayers).

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

```http
GET https://{accountId}.api.nextspace.host/programkeys
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.
- Logged in user auth token: A token for an active user session on the account, sent as "Authorization: Bearer <token>".

| Parameter | In | Required | Description |
| --- | --- | --- | --- |
| `{accountId}` | path | yes | The account id of the account to perform the request on. |

**Response**

```typescript
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**

```javascript
const url = "https://{accountId}.api.nextspace.host/programkeys";
const method = "get";
const token = "your-token";
const body = null;

async function doRequest(type, url, body, token) {
    const headers = {
        "Authorization": `Bearer ${token}`,
        "Content-Type": "application/json"
    };
    const options = {
        method: type,
        headers: headers,
        body: body ? JSON.stringify(body) : null
    };
    const res = await fetch(url, options);
    const json = await res.json();
    return json;
}

doRequest(method, url, body, token).then((res) => {
    console.log(res);
}).catch((err) => {
    console.error(err);
});
```

### Get Program Key by program ID

```http
GET https://{accountId}.api.nextspace.host/programkey/{programId}
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.
- Logged in user auth token: A token for an active user session on the account, sent as "Authorization: Bearer <token>".

| Parameter | In | Required | Description |
| --- | --- | --- | --- |
| `{accountId}` | path | yes | The account id of the account to perform the request on. |
| `{programId}` | path | yes | The program ID of the key to get. Eg: CesiumIon. |

**Response**

```typescript
// The response is the Program Key record directly.
// See the data model above for the record structure.
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/programkey/{programId}";
const method = "get";
const token = "your-token";
const body = null;

async function doRequest(type, url, body, token) {
    const headers = {
        "Authorization": `Bearer ${token}`,
        "Content-Type": "application/json"
    };
    const options = {
        method: type,
        headers: headers,
        body: body ? JSON.stringify(body) : null
    };
    const res = await fetch(url, options);
    const json = await res.json();
    return json;
}

doRequest(method, url, body, token).then((res) => {
    console.log(res);
}).catch((err) => {
    console.error(err);
});
```

## 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

```http
POST https://{accountId}.api.nextspace.host/programkey
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.
- Logged in user auth token: A token for an active user session on the account, sent as "Authorization: Bearer <token>".

| Parameter | In | Required | Description |
| --- | --- | --- | --- |
| `{accountId}` | path | yes | The account id of the account to perform the request on. |

**Request body**

```typescript
// 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.
```

**Example request body**

```json
{
    "ProgramId": "CesiumIon",
    "Key": "your-cesium-ion-access-token"
}
```

**Response**

```typescript
// The response is the saved Program Key record.
// See the data model above for the record structure.
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/programkey";
const method = "post";
const token = "your-token";
const body = {
    "ProgramId": "CesiumIon",
    "Key": "your-cesium-ion-access-token"
};

async function doRequest(type, url, body, token) {
    const headers = {
        "Authorization": `Bearer ${token}`,
        "Content-Type": "application/json"
    };
    const options = {
        method: type,
        headers: headers,
        body: body ? JSON.stringify(body) : null
    };
    const res = await fetch(url, options);
    const json = await res.json();
    return json;
}

doRequest(method, url, body, token).then((res) => {
    console.log(res);
}).catch((err) => {
    console.error(err);
});
```

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

```typescript
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

```http
DELETE https://{accountId}.api.nextspace.host/programkey/{programId}
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.
- Logged in user auth token: A token for an active user session on the account, sent as "Authorization: Bearer <token>".

| Parameter | In | Required | Description |
| --- | --- | --- | --- |
| `{accountId}` | path | yes | The account id of the account to perform the request on. |
| `{programId}` | path | yes | The program ID of the key to delete. Eg: CesiumIon. |

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/programkey/{programId}";
const method = "delete";
const token = "your-token";
const body = null;

async function doRequest(type, url, body, token) {
    const headers = {
        "Authorization": `Bearer ${token}`,
        "Content-Type": "application/json"
    };
    const options = {
        method: type,
        headers: headers,
        body: body ? JSON.stringify(body) : null
    };
    const res = await fetch(url, options);
    const json = await res.json();
    return json;
}

doRequest(method, url, body, token).then((res) => {
    console.log(res);
}).catch((err) => {
    console.error(err);
});
```

---

Urls on this page are resolved for account `{accountId}`.
Site index: https://docs.nextspace.host/llms.txt · whole site in one file: https://docs.nextspace.host/llms-full.txt
Human-readable version of this page: https://docs.nextspace.host/thirdpartykeys
