spectra-auth 1.0.0

API key management and authentication middleware for Spectra analytics

spectra-auth

API key management and authentication middleware for Spectra analytics.

Installation

pip install spectra-auth

For FastAPI projects, install with the optional FastAPI dependency:

pip install "spectra-auth[fastapi]"

Configuration

Explicit (recommended)

Call configure() once at application startup before using any other functions:

from spectra_auth import configure

configure(
    mongodb_uri="mongodb+srv://user:[e-mail]/",
    mongodb_database="spectra",
)

Environment variables (fallback)

If configure() is not called, the library reads from the environment:

Variable	Default	Description
MONGODB_URI	mongodb://localhost:27017	MongoDB connection string
MONGODB_DATABASE	spectra	Database name

Copy .env.example to .env and fill in your values.

Usage

Starlette / FastAPI middleware

Add AuthMiddleware to enforce authentication on all routes:

from fastapi import FastAPI
from spectra_auth import configure, AuthMiddleware

configure(mongodb_uri="...", mongodb_database="spectra")

app = FastAPI()
app.add_middleware(AuthMiddleware)

Authentication flow per request:

1. account_id is always required — passed via the X-Account-ID header or an account_id field in the JSON body.
2. If the request Origin / Referer matches an allowed origin for that account, the request passes through without an API key.
3. Otherwise, a valid API key must be provided via:
   • Authorization: Bearer <key> header (standard)
   • api_key field in the JSON body (sendBeacon fallback)

The /health path is always unauthenticated.

FastAPI route dependency

Use require_api_key as a route-level dependency when you need per-route enforcement instead of middleware:

from fastapi import Depends, FastAPI
from spectra_auth import require_api_key

app = FastAPI()

@app.get("/protected", dependencies=[Depends(require_api_key)])
async def protected_route():
    return {"message": "authenticated"}

API key management

from spectra_auth import create_api_key, delete_api_key, verify_key

# Create a new key (returns the raw key — store it securely, it is never stored in plain text)
raw_key = create_api_key(account_id="acct_123", label="Production")

# Verify a key
is_valid = verify_key(raw_key, account_id="acct_123")

# Delete a key
deleted = delete_api_key(raw_key)

Allowed origins

Allowed origins let browser clients send requests without an API key, identified by their Origin header:

from spectra_auth import add_allowed_origin, remove_allowed_origin, get_allowed_origins

add_allowed_origin("acct_123", "https://yourapp.com")

origins = get_allowed_origins("acct_123")
# ["https://yourapp.com"]

remove_allowed_origin("acct_123", "https://yourapp.com")

MongoDB schema

spectra-auth expects two collections in your database:

Collection	Key fields
api_keys	account_id, key_hash, created_at, label
allowed_origins	account_id, origins (array)

Indexes are created automatically on first use.

License

MIT