API Keys Management

API keys provide service-to-service authentication for integrations, scripts, and external systems that need to interact with AuroraSOC programmatically.

When to Use API Keys vs. JWT

Use Case	Recommended Auth	Reason
Dashboard login	JWT	Interactive, session-based
SIEM integration	API Key	Long-running service
CI/CD pipeline	API Key	Automated, non-interactive
Custom scripts	API Key	No login flow needed
Mobile app	JWT	User-specific sessions
Webhook receiver	API Key	Stateless verification

Key Format

API keys follow this format:

aurora_key_{32_random_hex_characters}

Example: aurora_key_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6

The prefix aurora_key_ makes it easy to identify AuroraSOC API keys in code reviews and secret scanners.

API Key Lifecycle

Creating a Key

curl -X POST /api/v1/auth/api-keys \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Suricata Integration",
    "role": "api_service",
    "description": "Used by Suricata log forwarder"
  }'

Response:

{
  "id": "key_001",
  "name": "Suricata Integration",
  "key": "aurora_key_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "role": "api_service",
  "created_at": "2024-01-15T10:00:00Z",
  "created_by": "admin@aurora.local"
}

Listing Keys

curl -X GET /api/v1/auth/api-keys \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Response shows keys without the actual key value (only the first 8 characters):

[
  {
    "id": "key_001",
    "name": "Suricata Integration",
    "key_prefix": "aurora_k...",
    "role": "api_service",
    "created_at": "2024-01-15T10:00:00Z",
    "last_used": "2024-01-15T14:30:00Z"
  }
]

Revoking a Key

curl -X DELETE /api/v1/auth/api-keys/key_001 \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Revocation is immediate — any request using the revoked key will receive 401 Unauthorized.

Key Storage Security

AuroraSOC never stores plaintext API keys. Only the SHA-256 hash is persisted. This means:

• If the database is compromised, API keys cannot be extracted
• Lost keys cannot be recovered — a new key must be generated
• Key comparison is done via hash comparison

Rate Limiting

API keys are subject to rate limiting:

Rate Limit	Threshold	Window
API requests	200 requests	Per minute
Investigation triggers	10 requests	Per minute
Playbook executions	20 requests	Per minute

Rate limits use Redis sliding window counters. When exceeded, the API returns 429 Too Many Requests with a Retry-After header.

Best Practices

1. One key per integration — Create separate keys for each service
2. Principle of least privilege — Assign the minimum role needed
3. Rotate regularly — Generate new keys quarterly, revoke old ones
4. Monitor usage — Check last_used timestamps for unused keys
5. Use secrets managers — Store keys in HashiCorp Vault, AWS Secrets Manager, or similar
6. Never hardcode — Use environment variables, not source code
7. Audit trail — All API key creations and revocations are logged