boc/packages/api/README-APIKEYS.md

API Key Management Module

Complete API key management for LandveX admin backend.

Features

1. Generate API Keys — UUID-based keys with lvx_ prefix
2. Rotate Keys — Revoke old key, create new with same config
3. Revoke Keys — Soft delete (revoke) or hard delete
4. Rate Limiting — Per-minute, per-hour, per-day limits per key
5. Usage Tracking — Append-only log with analytics
6. Admin API Endpoints — Full CRUD + rotation

API Endpoints

Method	Endpoint	Description
POST	/api-keys	Create new API key
GET	/api-keys	List all API keys
GET	/api-keys/:id	Get key with usage stats
POST	/api-keys/:id/rotate	Rotate API key
DELETE	/api-keys/:id	Revoke (soft delete)
DELETE	/api-keys/:id?hard=true	Hard delete

Create API Key

curl -X POST http://localhost:3000/api-keys \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Integration",
    "expiresInDays": 90,
    "rateLimitPerMinute": 120,
    "rateLimitPerHour": 5000,
    "rateLimitPerDay": 50000,
    "metadata": { "team": "platform", "env": "prod" }
  }'

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Production Integration",
  "key": "lvx_Af7x9K2mNpQwRt3Uv5Yz8BcDeFgHiJk",
  "keyPrefix": "lvx_Af7x9K2mNp",
  "status": "active",
  "rateLimitPerMinute": 120,
  "rateLimitPerHour": 5000,
  "rateLimitPerDay": 50000,
  "createdAt": "2026-07-03T03:47:00.000Z",
  "expiresAt": "2026-10-01T03:47:00.000Z",
  "metadata": { "team": "platform", "env": "prod" }
}

⚠️ The key field is ONLY returned on creation. Store it securely — it cannot be retrieved later.

List API Keys

curl "http://localhost:3000/api-keys?status=active&limit=50&offset=0"

Get Key with Stats

curl http://localhost:3000/api-keys/550e8400-e29b-41d4-a716-446655440000

Rotate Key

curl -X POST http://localhost:3000/api-keys/550e8400-e29b-41d4-a716-446655440000/rotate

Returns new key. Old key is immediately revoked.

Revoke Key

# Soft delete (revoke)
curl -X DELETE http://localhost:3000/api-keys/550e8400-e29b-41d4-a716-446655440000

# Hard delete (permanent)
curl -X DELETE "http://localhost:3000/api-keys/550e8400-e29b-41d4-a716-446655440000?hard=true"

Using API Keys

Include the key in the X-API-Key header:

curl -H "X-API-Key: lvx_Af7x9K2mNpQwRt3Uv5Yz8BcDeFgHiJk" \
  http://localhost:3000/api/v1/missions

Rate limit headers are included in responses:

X-RateLimit-Limit-Minute: 120
X-RateLimit-Remaining-Minute: 119
X-RateLimit-Limit-Hour: 5000
X-RateLimit-Remaining-Hour: 4999
X-RateLimit-Limit-Day: 50000
X-RateLimit-Remaining-Day: 49999

Database Schema

Run the SQL migration:

psql -d landvex -f packages/api/src/routes/api-keys.sql

Tables:

• api_keys — Key metadata (hashed, never plain text)
• api_key_usage — Append-only usage log

Views:

• api_keys_active — Active, non-expired keys
• api_key_usage_summary — Aggregated usage stats

Architecture

Express Router → ApiKeyService → ApiKeyRepository (PostgreSQL)
                      ↓
              ApiKeyUsageRepository (PostgreSQL)
                      ↓
              api_key_usage table

Testing

cd packages/api
npm test -- api-keys.test.ts

Tests cover:

• Key creation with validation
• Listing with pagination and filtering
• Rotation (revoke old, create new)
• Revocation and deletion
• Key validation
• Rate limiting
• Usage tracking

Files

File	Description
packages/api/src/models/api-key.ts	Domain model
packages/api/src/services/api-key-service.ts	Business logic
packages/api/src/middleware/api-key-auth.ts	Auth & rate limiting middleware
packages/api/src/routes/api-keys.ts	Express routes
packages/api/src/routes/api-keys.test.ts	Tests
packages/api/src/routes/api-keys.sql	PostgreSQL schema
packages/infrastructure/src/repositories/api-key-repository.ts	Repository interfaces
packages/infrastructure/src/adapters/postgresql/postgres-api-key-repository.ts	PostgreSQL adapter
packages/infrastructure/src/adapters/in-memory-api-key-repository.ts	In-memory adapter (testing)