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

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, 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. 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. 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:

# Import credentials into macOS Keychain

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

Alternatively, you can use the npm wrapper command:

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:

./scripts/dev-fresh.sh

Check the server logs for confirmation messages:

OpenSky auth mode: oauth
OpenSky OAuth: configured

The 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:

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:

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 — Documents authentication modes, import procedures, and troubleshooting steps.
• scripts/opensky-import-client.sh — CLI helper that securely stores OAuth credentials in the macOS Keychain.
• src/data/flights.js — Implements the /api/opensky endpoint logic and credential resolution.
• README.md — Provides overview documentation for OpenSky integration and quick-start instructions.
• 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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}