Authentication telemetry without leaking tokens or recovery secrets

I built authentication telemetry around a simple constraint: an engineer must be able to distinguish token expiry, replay, recovery rejection and dependency failure without logging the credential or sensitive request that triggered the decision. "Authentication failed" is not enough context to debug a production incident.

The opposite extreme is worse: a verbose debug log that captures raw bearer tokens, passwords, one-time codes, or private account payloads. Good observability starts with a restricted event schema and a clear data-handling policy.

For a security-sensitive endpoint, an event can record the decision and its context without recording the proof itself. Useful fields depend on the threat model, but a small allowlisted schema is easier to audit than arbitrary JSON properties.

{
  "event": "auth.decision",
  "operation": "refresh",
  "outcome": "denied",
  "reason": "token_reused",
  "policyVersion": "2026-11",
  "correlationId": "req_7f6e1",
  "environment": "production"
}

All values here are synthetic. There is no token, code, email address, phone number, recovery challenge or unredacted payload. In a real deployment, identifiers and operational metadata can still be sensitive and need access controls, retention limits, and privacy review.

Avoid collapsing distinct failures into “network error.” An operator needs to know whether a request was rejected by policy, was invalid, exhausted retry limits, or could not reach an upstream dependency.

The category should describe a stable failure class, not reveal secrets to the end user.

Detailed internal failure reasons help debugging but can also disclose account state if returned to an untrusted client. Keep the public response appropriately generic where enumeration or side-channel risks apply, and retain detailed diagnostic reasons in protected telemetry.

Aggregate rates by operation, rollout, policy, and failure category before drilling into individual trace IDs. Rate limits and retention policy should protect both the primary system and the observability pipeline.

Unit tests should generate synthetic token-like values, recovery codes, and PII and assert that serialized events never contain them. Validate logs for success and failure paths, exception handlers, retries, and traces from third-party SDKs.

Further reading: OWASP Logging Cheat Sheet and the API authorization review.

I prepared this guide with AI assistance. The example logs are synthetic, not taken from customer systems.