---
id: document-api-key-expiration-behavior
name: Document API Key Expiration Behavior
status: completed
depends_on: []
scope: single
risk: trivial
impact: isolated
level: implementation
---

## Description

**S05**: Does an expired API key return "key expired" or a generic "authentication failed"? Without documentation, implementers may leak key state to attackers by returning specific error messages. Recommend documenting that expired keys return a generic authentication failure to avoid information disclosure.

## Acceptance Criteria

- [ ] `identity.md` or `services.md` documents API key expiration error behavior
- [ ] Recommendation stated: expired keys return generic auth failure, not "key expired"
- [ ] Consistent with ADR-008 (key rotation) and keypal integration notes

## References

- docs/reviews/storage-architecture-review-2026-04-21.md#S05
- docs/architecture/storage/identity.md (api_keys table)
- docs/decisions/ADR-008

## Notes

> To be filled by implementation agent

## Summary

> To be filled on completion