# How to Set Up a Cesium ion Token in Gods Eye View: A Complete Configuration Guide

> Easily set up your Cesium ion token in Gods Eye View. Follow this guide to configure your token in the .env file and integrate it seamlessly for 3D viewer initialization.

- Repository: [Bilawal Sidhu/gods-eye-view](https://github.com/bilawalsidhu/gods-eye-view)
- Tags: how-to-guide
- Published: 2026-09-12

---

**To set up a Cesium ion token in Gods Eye View, create a `.env` file in the project root with `VITE_CESIUM_ION_TOKEN=your_token_here`, which [`src/main.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/main.js) reads at startup and assigns to `Cesium.Ion.defaultAccessToken` before initializing the 3D viewer.**

Gods Eye View is a Vite-based 3D visualization application that renders globes using CesiumJS. The `bilawalsidhu/gods-eye-view` repository requires a valid Cesium ion access token to fetch terrain and imagery assets, configured through build-time environment variables consumed at runtime.

## How the Token Flow Works in Gods Eye View

The application follows the standard Vite + CesiumJS integration pattern. The Cesium ion token must be available before any `Cesium.Viewer` instance is created, otherwise requests for Cesium-hosted assets return authentication errors.

In [`src/main.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/main.js), the application imports the Cesium library and immediately sets the global default access token:

```javascript
import * as Cesium from "cesium";

// Set the default Cesium ion token from the build-time env var
Cesium.Ion.defaultAccessToken = import.meta.env.VITE_CESIUM_ION_TOKEN;

```

This assignment occurs before the application imports and executes [`src/mapStartup.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/mapStartup.js), which constructs the actual viewer instance. The repository's [`vite.config.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/vite.config.js) ensures that environment variables prefixed with `VITE_` are forwarded to the client bundle.

## Configuring Your Cesium ion Token

### 1. Obtain a Token from Cesium ion

Visit [Cesium ion](https://cesium.com/ion/) and sign in to generate an access token from your dashboard. Copy the token string for the next step.

### 2. Create the Environment File

In the project root, create a file named `.env` and add your token:

```dotenv
VITE_CESIUM_ION_TOKEN=12345678-90ab-cdef-1234-567890abcdef

```

Vite automatically exposes variables prefixed with `VITE_` to `import.meta.env` during both development and production builds. Never commit this file to version control.

### 3. Verify the Startup Sequence

The critical code in [`src/main.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/main.js) handles the token assignment and validation:

```javascript
import * as Cesium from "cesium";

const ionToken = import.meta.env.VITE_CESIUM_ION_TOKEN;
if (!ionToken) {
  console.warn("[Gods Eye View] No Cesium ion token found – the default basemap may not load.");
}
Cesium.Ion.defaultAccessToken = ionToken;

// Viewer creation follows in mapStartup.js
import { createViewer } from "./mapStartup.js";
createViewer();

```

Because [`src/mapStartup.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/mapStartup.js) is imported after the token assignment, the `createViewer` function can instantiate `new Cesium.Viewer` without additional token configuration.

## Alternative Runtime Token Injection

If you cannot store the token in a `.env` file, the repository supports runtime injection via URL query parameters.

Add the following fallback logic to [`src/mapStartup.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/mapStartup.js) or [`src/main.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/main.js):

```javascript
// Optional: read token from URL if not provided via env
if (!Cesium.Ion.defaultAccessToken) {
  const urlToken = new URLSearchParams(window.location.search).get("cesiumIonToken");
  if (urlToken) {
    Cesium.Ion.defaultAccessToken = urlToken;
  }
}

```

Access the application with `?cesiumIonToken=your_token_here` to override the environment variable.

## Critical Files in the Token Pipeline

Understanding these three files ensures successful authentication:

- **[`src/main.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/main.js)**: Reads `import.meta.env.VITE_CESIUM_ION_TOKEN` and assigns it to `Cesium.Ion.defaultAccessToken` before any viewer initialization occurs.
- **[`src/mapStartup.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/mapStartup.js)**: Contains the `createViewer` function that instantiates the Cesium Viewer; relies entirely on the global token set during startup.
- **[`vite.config.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/vite.config.js)**: Configures the Vite build system to expose `VITE_` prefixed environment variables to the client bundle.

## Summary

- Gods Eye View requires a Cesium ion token to render 3D terrain and satellite imagery from Cesium ion servers.
- Store your token in a root-level `.env` file as `VITE_CESIUM_ION_TOKEN`.
- The token is automatically injected into the client bundle and assigned to `Cesium.Ion.defaultAccessToken` in [`src/main.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/main.js).
- This assignment must complete before [`src/mapStartup.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/mapStartup.js) creates the Cesium Viewer instance.
- For temporary testing, you can pass the token via the `cesiumIonToken` URL query parameter.

## Frequently Asked Questions

### What happens if I don't set a Cesium ion token?

If `VITE_CESIUM_ION_TOKEN` is undefined, [`src/main.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/main.js) logs a console warning and CesiumJS attempts to use a default token, which may be rate-limited or expired. The default basemap and terrain will fail to load, leaving you with a blank globe or 401 authentication errors in the browser's network tab.

### Can I use different tokens for development and production?

Yes. Create `.env.development` and `.env.production` files in the project root. Vite loads `.env.development` during `npm run dev` and `.env.production` during `npm run build`, allowing you to use restricted development tokens and production-specific access keys without manual switching.

### Where is the Cesium Viewer actually created?

According to the source code in `bilawalsidhu/gods-eye-view`, the Viewer instantiation occurs in [`src/mapStartup.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/mapStartup.js) inside the `createViewer` function. This file is imported by [`src/main.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/main.js) only after the token has been set, ensuring the global `Cesium.Ion.defaultAccessToken` is already configured.

### Is it safe to commit the .env file to version control?

No. The `.env` file contains sensitive access credentials. Add `.env` to your `.gitignore` file immediately after creation. For production deployments, inject the `VITE_CESIUM_ION_TOKEN` through your hosting platform's environment variable interface rather than committing the file.