# Logging & Monitoring

Effective logging and monitoring are essential for maintaining the security and reliability of any API key-based authentication system. Done well, they give you visibility into how keys are used, early warning of abuse, and an audit trail for compliance. Done poorly, they can become a liability, especially if full key values end up in your logs.

## What to Log

Every authenticated API request should generate a log entry that captures enough context for debugging and security analysis, without exposing secrets.

**For every request, log:**
- A key identifier (key ID or last four characters), never the full key
- The timestamp in UTC
- The HTTP method and request path
- The response status code
- The originating IP address
- Latency / response time

**For authentication-specific events, log:**
- Successful and failed authentication attempts
- Key creation, [rotation](/docs/security/key-rotation), and [revocation](/docs/implementation/revocation) events
- Scope or permission changes
- [Rate limit](/docs/security/rate-limiting) hits (429 responses)
- Requests made with expired or revoked keys

These events form the backbone of your security audit trail. If an incident occurs, they allow you to reconstruct what happened and when.

## What NOT to Log

This is equally important. Logging sensitive material creates a secondary attack vector: if your log store is compromised, every secret it contains is exposed.

**Never log:**
- The full API key value
- Request or response bodies that may contain secrets (tokens, passwords, PII)
- Internal database IDs that could aid an attacker in enumerating resources

## Key Masking in Logs

Always mask API keys before they reach your logging pipeline. This should be enforced at the application level, not left to individual developers.

```python
def mask_key(key: str) -> str:
    """Show only the prefix and last 4 characters."""
    if len(key) > 12:
        return key[:7] + "****" + key[-4:]
    return "****"

# Result: "sk_live****o5p6"
```

Apply masking as a log filter or middleware so it catches all log output, including error messages and stack traces that might inadvertently contain key values.

```javascript
// Express middleware example: redact Authorization header from logs
app.use((req, res, next) => {
  const sanitized = { ...req.headers };
  if (sanitized.authorization) {
    sanitized.authorization = sanitized.authorization.slice(0, 12) + "****";
  }
  req.sanitizedHeaders = sanitized;
  next();
});
```

Be thorough. Keys can appear in query parameters, error messages, HTTP headers, and structured log fields. Audit your log output regularly to confirm masking is applied everywhere.

## Alerting on Anomalies

Monitoring without alerting is just data collection. Define alert rules that surface potential security incidents early.

**High-priority alerts:**
- Sustained spike in failed authentication attempts (possible brute force)
- A single key making requests from multiple geographically distant IPs in a short window
- Requests from a key that was recently revoked
- Sudden increase in request volume for a single key (possible compromise)
- Requests hitting endpoints outside the key's normal usage pattern

**Medium-priority alerts:**
- Keys approaching rate limits consistently
- Keys that have not been [rotated](/docs/security/key-rotation) within your policy window
- Unused keys (no activity in 30+ days) that are still active

Set alert thresholds based on baseline behavior. A key that normally makes 100 requests per hour suddenly making 10,000 is significant; a key that normally makes 10,000 making 12,000 may not be.

## Dashboards

Build dashboards that give both real-time and historical views of key activity.

**Useful dashboard panels:**
- Total requests by key (top N most active)
- Authentication failure rate over time
- Request volume by endpoint
- Geographic distribution of requests
- Key lifecycle events (created, rotated, revoked) over time
- P95 and P99 latency by key

These dashboards serve dual purposes: operational monitoring for your infrastructure team and usage visibility for product and customer success teams investigating account-level behavior.

## Compliance Considerations

Depending on your industry and geography, you may be subject to regulations that dictate how authentication logs are handled.

- **Retention periods.** Standards like SOC 2 and PCI DSS require audit logs to be retained for a defined period (typically 1 year minimum). Ensure your logging pipeline supports this.
- **Access controls on logs.** Logs containing authentication data should be treated as sensitive. Restrict access to authorized personnel and log who accesses the logs themselves.
- **Immutability.** For compliance-grade logging, ensure log entries cannot be modified or deleted. Append-only storage (such as S3 with Object Lock) or a dedicated SIEM provides this guarantee.
- **Data residency.** If your users are in the EU or other jurisdictions with data residency requirements, ensure logs containing IP addresses and key identifiers are stored in compliant regions.

Good logging hygiene is one of those things that feels invisible when it's working. But when an incident happens (and eventually one will), the quality of your logs determines whether you're responding in minutes or scrambling for days.