API Key Security and Operations

Security Considerations

Key Format:

• Format: sk_{prefix}_{random_component}
• Prefix is stored for identification (e.g., sk_a1b2c3)
• Random component is 64 characters (high entropy)
• Total length: ~74 characters

Storage Security:

• Keys are hashed using SHA256 before storage
• Verification is intended to use constant-time comparison to reduce timing leakage
• The implementation is intended not to store or log the original key; verify redaction in the deployed release
• Key shown only once during creation

Permission Model:

• Keys carry a single-service scope; public cross-tenant abuse-case coverage is still being expanded
• Granular permissions (read vs. write, per resource type)
• Key routes are intended not to modify their own permissions
• Key routes are intended not to access organization-management endpoints; validate this boundary for the deployed release

Expiration:

• Optional expiration date for time-limited access
• Expired keys are rejected immediately
• No automatic cleanup (expired keys remain in database for audit)
• Set expiration for temporary integrations and CI/CD

Monitoring:

• last_used_at updated on each request
• Audit logs track key creation and deletion
• Monitor for unused keys and suspicious activity
• Alert on keys used from unexpected IP addresses

Best Practices:

• Never commit keys to version control
• Use environment variables or secret managers
• Rotate keys every 90 days
• Delete unused keys immediately
• Use separate keys per environment (dev/staging/prod)
• Grant minimum required permissions
• Set expiration dates for temporary keys
• Monitor last_used_at for inactive keys
• Audit logs regularly for security events

Key Rotation:

1. Create new API key with same permissions
2. Update service configuration with new key
3. Test new key in non-production environment
4. Deploy service with new key
5. Monitor for errors
6. Delete old key after confirmation

Compromise Response:

1. Delete compromised key immediately
2. Create new key with different prefix
3. Review audit logs for unauthorized access
4. Notify security team
5. Investigate scope of compromise
6. Update incident response documentation

Rate Limiting

API key operations are rate limited:

• Create API Key: 20 per hour per user
• List API Keys: 100 per hour per user
• Delete API Key: 30 per hour per user

Service API endpoints (accessed with API keys) have separate rate limits:

• Read Operations: 1000 requests per hour per key
• Write Operations: 500 requests per hour per key

Rate limit headers are included in responses:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 950
X-RateLimit-Reset: 1642348800