Bernt
aee0f09db8
- Datafabrik: Dockerfile fix, agentorkestrering fungerar - Vision: Identify-modell, FAISS, OCR alla testade - API: Alla 7 integrationstester passerade - Upplösare: Entitetsupplösning verifierad
162 lines
4.3 KiB
Markdown
162 lines
4.3 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
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:**
|
|
```json
|
|
{
|
|
"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
|
|
|
|
```bash
|
|
curl "http://localhost:3000/api-keys?status=active&limit=50&offset=0"
|
|
```
|
|
|
|
## Get Key with Stats
|
|
|
|
```bash
|
|
curl http://localhost:3000/api-keys/550e8400-e29b-41d4-a716-446655440000
|
|
```
|
|
|
|
## Rotate Key
|
|
|
|
```bash
|
|
curl -X POST http://localhost:3000/api-keys/550e8400-e29b-41d4-a716-446655440000/rotate
|
|
```
|
|
|
|
Returns new key. Old key is immediately revoked.
|
|
|
|
## Revoke Key
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
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:
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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) |
|