API Keys Management
API keys provide service-to-service authentication for integrations, scripts, and external systems.
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>
Authentication
Pass the API key in the X-API-Key header:
curl -H "X-API-Key: aurora_abc123..." http://localhost:8000/api/v1/alerts
Key lifecycle
- An admin creates a key with a name and optional expiry date.
- The full key is shown once at creation. Store it securely.
- Keys can be revoked at any time by an admin.
- Revoked keys are rejected on the next request.
Security notes
- API keys are stored hashed in the database, not in plaintext.
- Keys inherit the permissions of the role they are assigned to.
- Rotate keys regularly, especially after team changes.
- Never commit API keys to version control.