skybridge/kms

API Key Management Service

A comprehensive, secure API Key Management Service built in modern Go, designed to scale to millions of concurrent requests.

Features

• Scalable Architecture: Built with interfaces and dependency injection for easy extension
• Dual Token Types: Support for both static API keys and user JWT tokens
• Permission System: Hierarchical permission scopes with granular access control
• Multiple Auth Providers: Header-based and SSO authentication providers
• Rate Limiting: Configurable rate limiting to prevent abuse
• Security: Comprehensive security headers, CORS, and secure token handling
• Database: PostgreSQL with proper migrations and connection pooling
• Monitoring: Health checks, metrics, and structured logging
• Docker Ready: Complete Docker Compose setup for easy deployment

Architecture

The service follows clean architecture principles with clear separation of concerns:

cmd/server/          - Application entry point
internal/
  ├── domain/        - Domain models and business logic
  ├── repository/    - Data access interfaces and implementations
  ├── services/      - Business logic layer
  ├── handlers/      - HTTP request handlers
  ├── middleware/    - HTTP middleware components
  ├── config/        - Configuration management
  └── database/      - Database connection and migrations

Quick Start

Prerequisites

• Docker and Docker Compose
• Go 1.21+ (for local development)

Running with Docker Compose

1. Start the services:

docker-compose up -d

This starts:

• PostgreSQL database on port 5432
• API service on port 8080
• Nginx proxy on port 80
• Metrics endpoint on port 9090

2. Check service health:

curl http://localhost/health

3. View API documentation:

curl http://localhost/api/docs

Configuration

The service is configured via environment variables. Key settings:

# Database
DB_HOST=localhost
DB_PORT=5432
DB_NAME=kms
DB_USER=postgres
DB_PASSWORD=postgres

# Server
SERVER_HOST=0.0.0.0
SERVER_PORT=8080

# Authentication
AUTH_PROVIDER=header
AUTH_HEADER_USER_EMAIL=X-User-Email

# Security
RATE_LIMIT_ENABLED=true
RATE_LIMIT_RPS=100
RATE_LIMIT_BURST=200

API Usage

Authentication

All protected endpoints require the X-User-Email header when using the HeaderAuthenticationProvider:

curl -H "X-User-Email: admin@example.com" \
     -H "Content-Type: application/json" \
     http://localhost/api/applications

Creating an Application

curl -X POST http://localhost/api/applications \
  -H "Content-Type: application/json" \
  -H "X-User-Email: admin@example.com" \
  -d '{
    "app_id": "com.mycompany.api",
    "app_link": "https://api.mycompany.com",
    "type": ["static", "user"],
    "callback_url": "https://api.mycompany.com/callback",
    "token_renewal_duration": "168h",
    "max_token_duration": "720h",
    "owner": {
      "type": "team",
      "name": "API Team",
      "owner": "api-team@mycompany.com"
    }
  }'

Creating a Static Token

curl -X POST http://localhost/api/applications/com.mycompany.api/tokens \
  -H "Content-Type: application/json" \
  -H "X-User-Email: admin@example.com" \
  -d '{
    "owner": {
      "type": "individual",
      "name": "Service Account",
      "owner": "service@mycompany.com"
    },
    "permissions": ["repo.read", "repo.write"]
  }'

Token Verification

curl -X POST http://localhost/api/verify \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "com.mycompany.api",
    "type": "static",
    "token": "your-static-token-here",
    "permissions": ["repo.read"]
  }'

Permission Scopes

The service includes a hierarchical permission system:

System Permissions

• internal - Full access to internal system operations
• internal.admin - Administrative access to internal system

Application Management

• app.read - Read application information
• app.write - Create and update applications
• app.delete - Delete applications

Token Management

• token.read - Read token information
• token.create - Create new tokens
• token.revoke - Revoke existing tokens

Repository Access (Example)

• repo.read - Read repository data
• repo.write - Write to repositories
• repo.admin - Administrative access to repositories

Development

Local Development

1. Install dependencies:

go mod download

2. Run database migrations:

# Using Docker for PostgreSQL
docker run --name kms-postgres -e POSTGRES_DB=kms -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=postgres -p 5432:5432 -d postgres:15-alpine

3. Run the service:

go run cmd/server/main.go

Testing

The service includes comprehensive logging and can be tested at different user levels:

• Port 80: Regular user (test@example.com)
• Port 8081: Admin user (admin@example.com)
• Port 8082: Limited user (limited@example.com)

Building with distrobox

If you have distrobox available:

distrobox create --name golang-dev --image golang:1.21-alpine
distrobox enter golang-dev
cd /path/to/project
go build -o api-key-service ./cmd/server

Security Features

• Rate Limiting: Configurable per-endpoint rate limits
• Security Headers: Comprehensive security headers on all responses
• CORS: Configurable Cross-Origin Resource Sharing
• Token Security: Secure token generation and validation
• Permission Validation: Hierarchical permission checking
• Audit Logging: All operations logged with user attribution
• Input Validation: Request validation with detailed error messages

Monitoring

Health Checks

• GET /health - Basic health check
• GET /ready - Readiness check with database connectivity

Metrics

• GET /metrics - Prometheus-style metrics (when enabled)

Logging

Structured JSON logging with configurable levels:

• Request/response logging
• Error tracking with stack traces
• Performance metrics
• Security events

Database Schema

The service uses PostgreSQL with the following key tables:

• applications - Application definitions
• static_tokens - Static API tokens
• available_permissions - Permission catalog
• granted_permissions - Token-permission relationships

Migrations are automatically applied on startup.

Production Considerations

1. Security:

   • Change default HMAC keys
   • Use HTTPS in production
   • Configure proper CORS origins
   • Set up proper authentication provider

2. Performance:

   • Tune database connection pools
   • Configure appropriate rate limits
   • Set up load balancing
   • Monitor metrics and logs

3. High Availability:

   • Run multiple service instances
   • Use database clustering
   • Implement health check monitoring
   • Set up proper backup procedures

API Documentation

Comprehensive API documentation is available in docs/API.md, including:

• Complete endpoint reference
• Request/response examples
• Error handling
• Authentication flows
• Rate limiting details
• Security considerations

Architecture Decisions

• Interface-based Design: All dependencies are injected as interfaces for easy testing and replacement
• Clean Architecture: Clear separation between domain, service, and infrastructure layers
• Security First: Built with security considerations from the ground up
• Scalability: Designed to handle millions of concurrent requests
• Observability: Comprehensive logging, metrics, and health checks
• Configuration: Environment-based configuration with sensible defaults

Contributing

The codebase follows Go best practices and clean architecture principles. Key patterns:

• Repository pattern for data access
• Service layer for business logic
• Middleware for cross-cutting concerns
• Dependency injection throughout
• Comprehensive error handling
• Structured logging

License

This project is ready for production use with appropriate security measures in place.