Authentication Guide

Mend uses API key authentication to secure all API endpoints under /api/v1/*. This provides a simple yet effective way to control access to your media processing API.

Features

Multiple API Keys

Support for multiple API keys for different clients or environments

Flexible Headers

Accept API keys via X-API-Key header or Authorization: Bearer token

Backward Compatible

Can be disabled by leaving the api_keys array empty

Secure by Default

All job endpoints are protected, public endpoints remain accessible

Configuration

1. Set API Keys in config.yaml

   config.yaml

   server:
     port: 8080
     mode: release
     read_timeout: 30s
     write_timeout: 30s
     api_keys:
       - "${API_KEY_1}"
       - "${API_KEY_2}"  # Optional: add more keys

2. Set Environment Variables

   Create or update your .env file:

   .env

   # Generate a secure key
   API_KEY_1=$(openssl rand -hex 32)
   echo "API_KEY_1=$API_KEY_1" >> .env
   
   # Or manually set
   API_KEY_1=your_secure_random_key_here
   API_KEY_2=another_key_for_different_client

3. Generate Secure Keys

   OpenSSL

   # 64 character hex string
   openssl rand -hex 32

   UUID

   uuidgen

   Base64

   openssl rand -base64 32

   Example output:

   a7f3e8c9d2b1f4e6a8c5d9e2f7b3a6c8d1e4f9b2c5a8e3d6f1b4c7e9a2d5f8b1

Usage

Option 1: X-API-Key Header Recommended

curl -X POST http://localhost:8080/api/v1/jobs/image/resize \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{
    "source_bucket": "my-bucket",
    "source_key": "image.jpg",
    "dest_bucket": "my-bucket",
    "dest_key": "image-resized.jpg",
    "width": 800,
    "height": 600
  }'

Option 2: Authorization Bearer Token

curl -X POST http://localhost:8080/api/v1/jobs/image/resize \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_api_key_here" \
  -d '{ ... }'

Using with Environment Variables

# Set in your shell
export API_KEY_1="your_api_key_here"

# Use in scripts
curl -H "X-API-Key: $API_KEY_1" \
  http://localhost:8080/api/v1/jobs/image/resize \
  ...

Protected vs Public Endpoints

Protected Endpoints Require API Key

All endpoints under /api/v1/*:

• POST /api/v1/jobs/image/resize
• POST /api/v1/jobs/image/optimize
• POST /api/v1/jobs/image/watermark
• POST /api/v1/jobs/image/colors
• POST /api/v1/jobs/image/ai/keywords
• POST /api/v1/jobs/video/thumbnail
• POST /api/v1/jobs/audio/convert
• POST /api/v1/jobs/analyze
• GET /api/v1/jobs/:id

Public Endpoints No Authentication

• GET /health - Health check
• GET /metrics - Prometheus metrics
• GET /swagger/* - API documentation

Error Responses

Missing API Key

401 Unauthorized

{
  "error": "Missing API key. Provide via X-API-Key header or Authorization: Bearer <key>"
}

Invalid API Key

401 Unauthorized

{
  "error": "Invalid API key"
}

Security Best Practices

1. Generate Strong Keys

• Use cryptographically secure random generation
• Minimum 32 characters
• Use hex or base64 encoding

2. Store Keys Securely

Important

Never commit API keys to version control. Use environment variables or secret management systems. Keep .env files in .gitignore.

3. Rotate Keys Regularly

# Generate new key
NEW_KEY=$(openssl rand -hex 32)

# Add to config (keep old key temporarily)
server:
  api_keys:
    - "${API_KEY_1}"      # Old key
    - "${API_KEY_NEW}"    # New key

# Update clients to use new key
# Remove old key after migration

4. Use Different Keys per Environment

config.yaml

# Development
server:
  api_keys:
    - "${DEV_API_KEY}"

# Production
server:
  api_keys:
    - "${PROD_API_KEY_1}"
    - "${PROD_API_KEY_2}"

5. Monitor Usage

Check logs for authentication failures:

# View auth-related logs
docker-compose logs api | grep "API key"

# Look for patterns
docker-compose logs api | grep "invalid API key"

Multiple Keys Use Cases

Different Clients

server:
  api_keys:
    - "${MOBILE_APP_KEY}"
    - "${WEB_APP_KEY}"
    - "${ADMIN_KEY}"

Service Accounts

server:
  api_keys:
    - "${FRONTEND_SERVICE_KEY}"
    - "${BATCH_PROCESSOR_KEY}"
    - "${MONITORING_KEY}"

Dev vs Prod

server:
  api_keys:
    - "${API_KEY_1}"  # Production
    - "${DEV_KEY}"    # Development/testing

Testing Authentication

Test Valid Key

curl -i -H "X-API-Key: your_valid_key" \
  http://localhost:8080/api/v1/jobs/image/resize \
  -H "Content-Type: application/json" \
  -d '{ ... }'

# Expected: 202 Accepted (or 400 if invalid payload)

Test Invalid Key

curl -i -H "X-API-Key: invalid_key" \
  http://localhost:8080/api/v1/jobs/image/resize

# Expected: 401 Unauthorized

Test Missing Key

curl -i http://localhost:8080/api/v1/jobs/image/resize

# Expected: 401 Unauthorized

Test Public Endpoint

curl -i http://localhost:8080/health

# Expected: 200 OK (no auth required)

Disabling Authentication

Not Recommended for Production

You can disable authentication by setting an empty array, but this is not recommended for production environments.

config.yaml

server:
  api_keys: []  # Empty array disables auth

The middleware will log a warning:

API key authentication is disabled - no keys configured

Implementation Details

The authentication is implemented in /internal/api/middleware/auth.go:

• Lookup Method: O(1) hash map lookup for performance
• Header Priority: Checks X-API-Key first, then Authorization: Bearer
• Logging: Logs all authentication failures with IP and path
• Backward Compatible: Gracefully handles empty key configuration

Troubleshooting

Issue: “Missing API key” error

Solution:

• Ensure you’re including the X-API-Key header
• Check header spelling (case-sensitive)
• Verify the header value is not empty

Issue: “Invalid API key” error

Solution:

• Verify the key matches one in config.yaml
• Check for extra spaces or newlines in the key
• Ensure environment variables are loaded correctly
• Restart the API server after config changes

Issue: Authentication disabled warning

Solution:

• Add at least one API key to config.yaml
• Ensure environment variables are set
• Check that api_keys array is not empty

Issue: Can’t access public endpoints

Solution:

• Public endpoints (/health, /metrics, /swagger/*) should always work
• Check if you’re using the correct path
• Verify the server is running

Migration Guide

If you’re upgrading from a version without authentication:

1. Update config structure

   config.yaml

   server:
     api_keys:
       - "${API_KEY_1}"

2. Generate and set API key

   echo "API_KEY_1=$(openssl rand -hex 32)" >> .env

3. Update all API clients

   • Add X-API-Key header to all requests
   • Update example scripts and documentation

4. Test thoroughly

   • Verify all endpoints work with new auth
   • Check that public endpoints still work
   • Monitor logs for auth failures

5. Optional: Disable temporarily

   server:
     api_keys: []  # Disable during migration

Need Help?

For issues or questions:

• Check logs: docker-compose logs api
• Review API Documentation
• See examples in the repository