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

Generated API keys follow this format:

aurora_<64_random_hex_characters>

Example:

aurora_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4

The aurora_ prefix makes key material easy to identify in secret scanners and log filters.

API Key Lifecycle

Creating a Key

curl -X POST /api/v1/auth/api-keys \
  -H "Authorization: Bearer $TOKEN_WITH_USERS_MANAGE" \
  -H "Content-Type: application/json" \
  -d '{
    "service_name": "suricata-forwarder",
    "expires_in_days": 90,
    "permissions": ["alerts:read", "iocs:write"]
  }'

Response:

{
  "id": "7c557b75-16cf-4d15-8f6a-f8ee5f0e19d7",
  "service_name": "suricata-forwarder",
  "api_key": "aurora_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4",
  "key_prefix": "ak_3a9f2d4c7b11",
  "permissions": ["alerts:read", "iocs:write"],
  "created_by": "admin",
  "created_at": "2026-04-05T09:21:13.442176+00:00",
  "expires_at": "2026-07-04T09:21:13.442163+00:00",
  "message": "Store this API key securely now. It will not be shown again."
}

Notes:

• expires_in_days is optional. Set it to null for a non-expiring key.
• permissions is optional. If omitted, AuroraSOC applies the default api_service permission set.
• The raw api_key is returned only once.
• key_prefix is a management label for audit and rotation workflows. It is not derived from the raw key material.

Listing Keys

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

Response shows key metadata only (never the full key value):

{
  "api_keys": [
    {
      "id": "7c557b75-16cf-4d15-8f6a-f8ee5f0e19d7",
      "service_name": "suricata-forwarder",
      "key_prefix": "ak_3a9f2d4c7b11",
      "role": "api_service",
      "permissions": ["alerts:read", "iocs:write"],
      "is_active": true,
      "created_by": "admin",
      "created_at": "2026-04-05T09:21:13.442176+00:00",
      "expires_at": "2026-07-04T09:21:13.442163+00:00",
      "last_used_at": "2026-04-05T10:41:03.107511+00:00",
      "revoked_at": null
    }
  ],
  "total": 1
}

Revoking a Key

curl -X DELETE /api/v1/auth/api-keys/7c557b75-16cf-4d15-8f6a-f8ee5f0e19d7 \
  -H "Authorization: Bearer $TOKEN_WITH_USERS_MANAGE"

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 uses timing-safe hash checks

To reduce database pressure in production, AuroraSOC caches valid database-managed API key metadata in-process for a short TTL. Revoking a key clears the current process cache immediately, and other workers naturally age out the cached entry after the TTL.

Authentication Header

Use API keys with the X-API-Key header:

X-API-Key: aurora_<...>

AuroraSOC also supports a static environment key (API_SERVICE_KEY) for infrastructure-level integrations. Managed DB-backed keys are recommended for auditing, expiry, and revocation.

Rate Limiting

API-key authenticated requests are subject to endpoint and service rate limits. When exceeded, AuroraSOC returns 429 Too Many Requests.

Best Practices

1. One key per integration — Create separate keys for each service
2. Principle of least privilege — Assign only the minimum required permissions
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