How to Manage User Authentication in gods-eye-view: Environment-Driven OpenSky Configuration

User authentication in gods-eye-view is handled through a Vite plugin that supports four modes—oauth, basic, auto, and anon—controlled entirely by environment variables.

The bilawalsidhu/gods-eye-view repository implements a flexible, centralized authentication system for its upstream data provider, the OpenSky Network. Rather than hardcoding credentials or managing tokens manually, developers configure authentication behavior through a single environment variable and corresponding credential sets. This guide covers all authentication modes, their implementation in vite.config.js, and how to configure them for local development and production deployments.

Authentication Modes Explained

The OPENSKY_AUTH_MODE environment variable determines which authentication strategy the Vite plugin activates. Four values are supported, validated by a Set defined at vite.config.js line 174.

OAuth Mode (Default)

OAuth is the default authentication method when OPENSKY_AUTH_MODE is unset or explicitly set to oauth (vite.config.js line 167).

This mode requires:

• OPENSKY_CLIENT_ID
• OPENSKY_CLIENT_SECRET

The plugin requests a client_credentials bearer token from the OpenSky token endpoint (vite.config.js line 1436). Tokens are obtained automatically at build time and refreshed as needed.

# .env configuration for OAuth

OPENSKY_AUTH_MODE=oauth
OPENSKY_CLIENT_ID=your_client_id_here
OPENSKY_CLIENT_SECRET=your_client_secret_here

Basic Authentication Mode

Basic authentication uses username and password credentials directly in HTTP requests. Enable it by setting OPENSKY_AUTH_MODE=basic.

Required variables:

• OPENSKY_USERNAME
• OPENSKY_PASSWORD

Basic auth is also used as a fallback when OAuth fails and the mode resolution logic permits fallback behavior (vite.config.js lines 3189-3194).

# .env configuration for Basic auth

OPENSKY_AUTH_MODE=basic
OPENSKY_USERNAME=your_opensky_username
OPENSKY_PASSWORD=your_opensky_password

Auto Mode with Intelligent Fallback

Auto mode attempts OAuth first, then automatically falls back to Basic authentication if OAuth credentials are missing or invalid. This provides resilience for development environments where OAuth may be temporarily unavailable.

The decision flow is implemented in vite.config.js lines 3088-3225. The plugin evaluates credential availability before making any network requests.

# Provide both credential sets for maximum flexibility

OPENSKY_AUTH_MODE=auto
OPENSKY_CLIENT_ID=your_client_id
OPENSKY_CLIENT_SECRET=your_secret
OPENSKY_USERNAME=backup_username
OPENSKY_PASSWORD=backup_password

Anonymous Mode

Anon mode disables authentication entirely. Requests to OpenSky are made without credentials, which typically results in stricter rate limits and reduced data availability. Use this only for public demonstration deployments or when testing without any credentials.

OPENSKY_AUTH_MODE=anon

Error Handling and Diagnostics

When authentication fails, the Vite plugin emits explicit error objects that surface in both the build output and UI. Common error messages include:

• "OpenSky auth missing" — Required credentials for the selected mode are absent
• "OpenSky auth invalid" — Credentials were rejected by the OpenSky API

These errors influence cache-control decisions (vite.config.js lines 3189-3216), ensuring that failed auth states don't cache invalid data.

Configuration Files and Setup

Environment File Template

All authentication variables are documented in .env.example. Copy this file to .env and populate values appropriate for your deployment:

cp .env.example .env

Never commit .env to version control. The example file shows all supported keys including commented alternatives for each authentication mode.

Runtime Environment Initialization

The src/keySetup.js module initializes runtime environment variables and enforces defaults. It references the same authentication mode logic used by the Vite plugin, ensuring consistency between build-time and runtime configuration.

Core validation utilities live in src/keySetupCore.mjs, which the Vite plugin imports to read and validate credentials before making authentication requests.

Documentation Reference

The docs/opensky-auth.md file provides step-by-step instructions for obtaining OAuth client credentials from the OpenSky developer portal, including portal URLs and approval timelines.

Practical Configuration Examples

Local Development with OAuth

# .env

OPENSKY_AUTH_MODE=oauth
OPENSKY_CLIENT_ID=dev_client_123
OPENSKY_CLIENT_SECRET=dev_secret_abc

# Start development server

npm run dev

CI/CD Pipeline with Basic Auth

# In your CI configuration

export OPENSKY_AUTH_MODE=basic
export OPENSKY_USERNAME=$OPENSKY_USER
export OPENSKY_PASSWORD=$OPENSKY_PASS
npm run build

Docker Deployment with Auto Mode

# Dockerfile excerpt

ENV OPENSKY_AUTH_MODE=auto

# Credentials injected at runtime via secrets

Key Files Reference

File	Purpose
[vite.config.js](https://github.com/bilawalsidhu/gods-eye-view/blob/main/vite.config.js)	Vite plugin implementing multi-mode authentication, token fetching, and error handling
.env.example	Template showing all supported authentication environment variables
[docs/opensky-auth.md](https://github.com/bilawalsidhu/gods-eye-view/blob/main/docs/opensky-auth.md)	Guide to OpenSky authentication options and credential acquisition
[src/keySetup.js](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/keySetup.js)	Runtime environment initialization and default enforcement
src/keySetupCore.mjs	Core utilities for credential validation used by the Vite plugin

Summary

• Four authentication modes are available: oauth (default), basic, auto, and anon, selected via OPENSKY_AUTH_MODE
• OAuth requires OPENSKY_CLIENT_ID and OPENSKY_CLIENT_SECRET; Basic requires OPENSKY_USERNAME and OPENSKY_PASSWORD
• Auto mode tries OAuth first, then falls back to Basic automatically (vite.config.js lines 3088-3225)
• Configuration is environment-driven through .env (copied from .env.example)
• Clear error messages surface authentication failures for debugging and cache control
• Token acquisition happens automatically in the Vite plugin without manual intervention

Frequently Asked Questions

What happens if I don't set any authentication variables?

The plugin defaults to oauth mode (vite.config.js line 167) and will emit an "OpenSky auth missing" error since credentials are absent. For credential-free operation, explicitly set OPENSKY_AUTH_MODE=anon, though this limits data access.

How do I obtain OAuth credentials for OpenSky?

Visit the OpenSky developer portal as documented in [docs/opensky-auth.md](https://github.com/bilawalsidhu/gods-eye-view/blob/main/docs/opensky-auth.md). Registration requires account creation and application approval. Once granted, you'll receive a CLIENT_ID and CLIENT_SECRET for use in your .env file.

Can I switch authentication modes without rebuilding?

No. The Vite plugin evaluates OPENSKY_AUTH_MODE at build time when determining authentication strategy. Changing modes requires restarting the development server or triggering a new build. Runtime mode inspection is available through environment utilities in src/keySetup.js.

Is Basic authentication less secure than OAuth?

Both methods transmit credentials over HTTPS, but OAuth is preferred because tokens expire and can be revoked without changing your account password. Basic auth embeds your actual OpenSky credentials in every request. Use OAuth for production deployments and Basic only for development or when OAuth is unavailable.

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