# How to Import OpenSky Data for God's Eye View: Credentials Setup Guide

> Learn how to import OpenSky data into God's Eye View. This guide covers setting up OAuth client credentials from environment variables, JSON files, or the macOS Keychain for live flight data.

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

---

**God's Eye View imports live flight data from the OpenSky Network by resolving OAuth client credentials from environment variables, a JSON file, or the macOS Keychain, then exposes this data through the `/api/opensky` endpoint.**

God's Eye View is an open-source flight tracking application that integrates with the OpenSky Network to display real-time aircraft positions. To establish this connection, you must configure authentication credentials that the server uses when requesting data from OpenSky's API. This guide explains the credential resolution order, import workflows, and verification steps based on the source implementation.

## OpenSky Authentication Architecture

The OpenSky integration in God's Eye View supports multiple authentication modes to accommodate different deployment scenarios. Understanding these modes helps you choose the appropriate configuration method for your environment.

### Supported Authentication Modes

According to [`docs/opensky-auth.md`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/docs/opensky-auth.md), the server supports three distinct authentication strategies:

- **OAuth Client-Credentials** — The default and recommended mode, providing full API access with rate limits appropriate for production use.
- **Basic authentication** — A fallback mode using username/password credentials.
- **Anonymous** — Requires no credentials but provides limited API credits and restricted data access.

### Credential Resolution Priority

When the application starts, it resolves OpenSky credentials in the following strict order, as implemented in the configuration logic:

1. **Environment variables** — Checks for `OPENSKY_CLIENT_ID` and `OPENSKY_CLIENT_SECRET`.
2. **JSON credentials file** — Reads the path specified in `OPENSKY_CREDENTIALS_FILE`.
3. **macOS Keychain** — Retrieves the `client_id` and `client_secret` from the *opensky-network* service entry.

If no credentials are found, the server automatically falls back to Basic or Anonymous modes, though these provide reduced functionality.

## Importing OpenSky Credentials

To import your own OpenSky OAuth client, use the helper script [`scripts/opensky-import-client.sh`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/scripts/opensky-import-client.sh). This script reads a credential JSON file downloaded from the OpenSky dashboard and stores the credentials securely in the macOS Keychain.

### Step 1: Obtain Client Credentials from OpenSky

First, download your OAuth client JSON from the [OpenSky developer portal](https://opensky-network.org). This file contains your `client_id` and `client_secret` required for API access.

### Step 2: Run the Import Script

Execute the import script to store your credentials in the macOS Keychain under the *opensky-network* service:

```bash

# Import credentials into macOS Keychain

./scripts/opensky-import-client.sh ~/Downloads/opensky-cred.json

```

Alternatively, you can use the npm wrapper command:

```bash
npm run opensky:import -- ~/Downloads/opensky-cred.json

```

### Step 3: Start the Development Server

Once credentials are imported, start a fresh development server to automatically detect the stored credentials:

```bash
./scripts/dev-fresh.sh

```

Check the server logs for confirmation messages:

```text
OpenSky auth mode: oauth
OpenSky OAuth: configured

```

The [`src/data/flights.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/data/flights.js) file implements the `/api/opensky` request logic that utilizes these resolved credentials when making API calls.

## Alternative: Environment-Based Configuration

If you prefer not to use the macOS Keychain, you can point the server directly at your credentials JSON file using the `OPENSKY_CREDENTIALS_FILE` environment variable:

```bash
OPENSKY_CREDENTIALS_FILE=~/Downloads/opensky-cred.json \
  ./scripts/dev-fresh.sh

```

This method bypasses the Keychain lookup and reads credentials directly from the specified file path, which is useful for containerized deployments or CI/CD pipelines.

## Verifying the OpenSky Integration

To confirm that God's Eye View is successfully importing OpenSky data and authenticating correctly, test the endpoint using curl:

```bash
curl -si http://localhost:4173/api/opensky | grep -iE 'HTTP/|X-OpenSky-Auth'

```

Look for a successful `HTTP/1.1 200 OK` response and the presence of the `X-OpenSky-Auth` header, which indicates the server is correctly transmitting authentication details to the OpenSky API.

## Key Implementation Files

The following source files contain the core logic for OpenSky data import and authentication:

- **[`docs/opensky-auth.md`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/docs/opensky-auth.md)** — Documents authentication modes, import procedures, and troubleshooting steps.
- **[`scripts/opensky-import-client.sh`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/scripts/opensky-import-client.sh)** — CLI helper that securely stores OAuth credentials in the macOS Keychain.
- **[`src/data/flights.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/data/flights.js)** — Implements the `/api/opensky` endpoint logic and credential resolution.
- **[`README.md`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/README.md)** — Provides overview documentation for OpenSky integration and quick-start instructions.
- **[`DATA_SOURCES.md`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/DATA_SOURCES.md)** — Lists OpenSky as a primary live-flight data source alongside implementation notes.

## Summary

- God's Eye View supports OAuth Client-Credentials, Basic, and Anonymous authentication modes for the OpenSky Network.
- The server resolves credentials in priority order: environment variables, JSON file path, then macOS Keychain.
- Use [`scripts/opensky-import-client.sh`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/scripts/opensky-import-client.sh) or `npm run opensky:import` to store credentials securely in the Keychain.
- For non-Keychain deployments, set `OPENSKY_CREDENTIALS_FILE` to point directly to your credentials JSON.
- Verify successful authentication by checking server logs for "OpenSky OAuth: configured" and testing the `/api/opensky` endpoint.

## Frequently Asked Questions

### What authentication modes does God's Eye View support for OpenSky?

God's Eye View supports three authentication modes: **OAuth Client-Credentials** (default and recommended), **Basic authentication**, and **Anonymous** access. OAuth Client-Credentials provides the highest rate limits and data access, while Anonymous mode requires no configuration but offers limited API credits.

### How does God's Eye View resolve OpenSky credentials?

The credential resolver checks sources in strict priority: first environment variables (`OPENSKY_CLIENT_ID` and `OPENSKY_CLIENT_SECRET`), then a JSON file specified by `OPENSKY_CREDENTIALS_FILE`, and finally the macOS Keychain entry named *opensky-network*. If none are found, it falls back to Basic or Anonymous modes.

### Can I use OpenSky data without storing credentials in the macOS Keychain?

Yes. Instead of using the import script and Keychain storage, you can set the `OPENSKY_CREDENTIALS_FILE` environment variable to the path of your OpenSky credentials JSON file before starting the server. This bypasses Keychain lookup and is suitable for Linux servers or containerized environments.

### How do I verify that OpenSky data is importing correctly?

Start the development server with [`./scripts/dev-fresh.sh`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/./scripts/dev-fresh.sh) and verify the logs show "OpenSky auth mode: oauth" and "OpenSky OAuth: configured". Then test the endpoint with `curl http://localhost:4173/api/opensky` and look for a 200 OK response and the `X-OpenSky-Auth` header, confirming successful authentication against the OpenSky API.