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

> Master user authentication in gods-eye-view with environment-driven OpenSky configuration. Explore OAuth, basic, auto, and anon modes for secure access.

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

---

**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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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](https://github.com/bilawalsidhu/gods-eye-view/blob/main/vite.config.js#L174).

### 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](https://github.com/bilawalsidhu/gods-eye-view/blob/main/vite.config.js#L167)).

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](https://github.com/bilawalsidhu/gods-eye-view/blob/main/vite.config.js#L1436)). Tokens are obtained automatically at build time and refreshed as needed.

```bash

# .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](https://github.com/bilawalsidhu/gods-eye-view/blob/main/vite.config.js#L3189)).

```bash

# .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](https://github.com/bilawalsidhu/gods-eye-view/blob/main/vite.config.js#L3088). The plugin evaluates credential availability before making any network requests.

```bash

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

```bash
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](https://github.com/bilawalsidhu/gods-eye-view/blob/main/vite.config.js#L3189)), 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:

```bash
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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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

```bash

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

```bash

# 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

# 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)](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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/.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)](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)](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/keySetup.js) | Runtime environment initialization and default enforcement |
| [`src/keySetupCore.mjs`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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](https://github.com/bilawalsidhu/gods-eye-view/blob/main/vite.config.js#L3088))
- **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](https://github.com/bilawalsidhu/gods-eye-view/blob/main/vite.config.js#L167)) 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)](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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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.