beanone-apikey 0.3.0

A reusable FastAPI router for API key management

API Key Management Library

A library for API key management and JWT validation, designed to be integrated into services that need to handle API key operations and authentication.

Overview

This library provides:

• API key model and persistence
• API key generation and validation
• JWT validation
• Key management endpoints
• Database access layer

Installation

pip install beanone-apikey

Quick Start

from fastapi import FastAPI
from apikey import api_key_router

app = FastAPI()
app.include_router(api_key_router)

Features

• API key generation and management
• API key validation
• JWT validation
• API key listing and deletion
• Secure key storage with hashing
• Async database operations
• FastAPI integration

API Endpoints

Endpoint	Method	Description
/api-keys/	POST	Create a new API key
/api-keys/	GET	List all API keys
/api-keys/{key_id}	DELETE	Delete an API key

Authentication

The library supports two authentication methods:

1. JWT Authentication

   • Validates JWTs issued by the login service
   • Extracts user information from JWT claims
   • Supports audience validation

2. API Key Authentication

   • Validates API keys in requests
   • Supports both header and query parameter authentication
   • Checks key status and expiration

Configuration

Environment variables:

• DATABASE_URL: Database connection URL (default: sqlite+aiosqlite:///./apikey.db)
  • For development: sqlite+aiosqlite:///./apikey.db
  • For production: postgresql+asyncpg://user:password@host:5432/dbname
• JWT_SECRET: Secret for JWT validation
• JWT_ALGORITHM: JWT algorithm (default: HS256)
• LOGIN_URL: Login service URL (default: http://localhost:8001)

Database Configuration

• For development: SQLite (default)
• For production: PostgreSQL
  • Use the full connection URL in DATABASE_URL
  • Example: postgresql+asyncpg://postgres:password@localhost:5432/apikeydb

Development

1. Clone the repository
2. Install development dependencies:

   pip install -e ".[dev]"
   

3. Run tests:

   pytest
   

Starting a New Development Instance

1. Set up the environment

   # Create and activate virtual environment
   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   
   # Install dependencies
   pip install -r requirements.txt
   pip install -r requirements-test.txt
   

2. Configure environment variables Create a .env file in the project root:

   # Database configuration
   # For local deployment only
   DATABASE_URL=sqlite+aiosqlite:///./apikey.db
   # DATABASE_URL=postgresql+asyncpg://postgres:password@localhost:5433/apikeydb  # For PostgreSQL with Docker
   
   # JWT configuration: should match that of the Login service
   JWT_SECRET=supersecretjwtkey
   JWT_ALGORITHM=HS256
   LOGIN_URL=http://localhost:8001
   

3. Start the development server

   # Using uvicorn directly
   uvicorn src.apikey.service:app --reload --port 8002
   
   # Or using Docker Compose for development
   docker compose -f docker-compose.dev.yml build --no-cache
   docker compose -f docker-compose.dev.yml up
   

4. Verify the setup

   • Check the health endpoint: http://localhost:8002/health
   • Access the API documentation: http://localhost:8002/docs
   • Run the test suite: pytest

5. Development workflow

   • The server will automatically reload on code changes
   • Use the API documentation to test endpoints
   • Check logs: docker-compose -f docker-compose.dev.yml logs -f apikey

Docker Deployment

Production Deployment

1. Create a .env file with required environment variables
2. Run with Docker Compose:

   docker-compose up -d
   

The service will be available at http://localhost:8002

Development Deployment

1. Create a .env file with required environment variables
2. Run with development Docker Compose:

   docker compose -f docker-compose.dev.yml up -d
   

Development features:

• Hot reload enabled
• Source code mounted for live updates
• PostgreSQL database with persistent volume
• Health checks configured

Docker Configuration

• Service runs on port 8002
• Health check endpoint: /health
• Resource limits:
  • CPU: 0.5 cores
  • Memory: 512MB
• Logging: JSON format with rotation (10MB max, 3 files)

Architecture

This library is designed to be integrated into services that need to:

• Manage API keys for their users
• Validate incoming requests using either JWTs or API keys
• Store and manage API key data

The library follows a distributed API key management pattern where:

• Each service maintains its own API key database
• API key validation is performed locally
• JWT validation is performed against the login service

Security

• API keys are hashed before storage
• JWT validation includes audience checks
• API key validation checks status and expiration
• All endpoints require authentication
• Database operations use parameterized queries
• Non-root user in Docker container
• Resource limits enforced
• Health checks implemented

License

MIT