Writing sample · Product Requirements Document
Self-serve API key rotation
Letting developers rotate credentials safely — without a support ticket or an outage.
- Product
- Developer Platform (concept)
- Author
- Kayleigh
- Status
- Concept · writing sample
- Last updated
- November 2026
01Summary
Today, customers who need to rotate an API key must open a support ticket and accept a hard cutover: the old key stops working the moment the new one is issued. This PRD proposes self-serve rotation with a configurable overlap window, so teams can deploy new credentials before old ones expire.
02Problem
Key rotation is a security best practice — and increasingly a compliance requirement — but our current process actively discourages it.
- Support load: rotation requests make up an estimated 9% of developer support tickets (illustrative).
- Outage risk: a hard cutover forces customers to coordinate deploys to the minute; failed rotations cause self-inflicted downtime.
- Security posture: because rotation is painful, many keys are never rotated. Leaked keys stay valid indefinitely.
- Enterprise blockers: security questionnaires routinely ask whether keys can be rotated without downtime. Today the honest answer is no.
03Goals & non-goals
| Goals | Non-goals |
|---|---|
| Rotate a key in the dashboard or via API, without contacting support | Replacing API keys with OAuth or short-lived tokens |
| Zero-downtime rotation through an overlap window | Automatic rotation on a schedule (future phase) |
| Immediate revocation for compromised keys | Changes to key permission scopes |
| Full audit trail of key lifecycle events | Secrets-manager integrations (future phase) |
04Personas
| Persona | Need | Today's pain |
|---|---|---|
| Platform engineer | Rotate keys as part of routine deploys | Must schedule a cutover with support |
| Security lead | Prove keys are rotated and revoke leaked keys fast | No audit trail; revocation needs a ticket |
| Solo developer | Replace a key accidentally committed to Git | Waits hours while the leaked key stays live |
05User stories
- As a platform engineer, I want to generate a new key while the old one keeps working, so that I can roll out the change without downtime.
- As a platform engineer, I want to choose how long the old key remains valid, so that the window matches my deploy cadence.
- As a security lead, I want to revoke a key immediately, so that a leaked credential stops working within seconds.
- As a security lead, I want to see who created, rotated, or revoked each key and when, so that I can satisfy audits.
- As a developer, I want to see when a key was last used, so that I know whether it's safe to retire.
06Requirements
| ID | Requirement | Priority |
|---|---|---|
| FR-1 | Users can rotate a key from the dashboard and via a public API endpoint. | P0 |
| FR-2 | On rotation, the previous key remains valid for an overlap window: 1h, 24h (default), 7d, or custom up to 30d. | P0 |
| FR-3 | Users can revoke any key immediately; revocation propagates globally in under 60 seconds. | P0 |
| FR-4 | The dashboard shows each key's status, creation date, expiry, and last-used timestamp. | P0 |
| FR-5 | All lifecycle events are written to the audit log with actor, timestamp, and source IP. | P0 |
| FR-6 | Account owners receive an email when a key is rotated or revoked. | P1 |
| FR-7 | Requests using a key inside its overlap window return a deprecation response header. | P1 |
| FR-8 | Admins can require MFA re-authentication before rotation or revocation. | P2 |
| Area | Requirement |
|---|---|
| Latency | Key validation adds no more than 2ms at p99 during overlap windows. |
| Availability | Rotation endpoints meet the platform's existing 99.95% SLO. |
| Security | Secrets are shown once at creation, stored hashed, and never logged. |
| Accessibility | Dashboard flows meet WCAG 2.2 AA, including keyboard-only operation. |
07Edge cases
- Rotating during an overlap window: limit each key lineage to two active keys; rotating again requires the oldest key to be revoked first.
- Revoking the only active key: require explicit confirmation and warn that all traffic using it will fail.
- Clock skew across regions: expiry is enforced server-side using a single time source, with a 30-second grace period.
- Custom window beyond org policy: org admins can set a maximum window that overrides user choices.
- API-initiated rotation by a key that is itself being rotated: allowed, but the response must return the new secret exactly once.
08Success metrics
| Metric | Baseline (illustrative) | Target at 90 days |
|---|---|---|
| Rotation-related support tickets | ~9% of tickets | < 1% |
| Keys rotated in the last 90 days | 12% | 40% |
| Median time to revoke a leaked key | ~4 hours | < 5 minutes |
| Rotation-caused incidents | Several per quarter | Zero |
Guardrail metric: p99 authentication latency must not regress by more than 2ms.
09Rollout plan
- 01Internal dogfoodOur own services rotate first
- 02Private beta10 design-partner accounts
- 03Public betaDashboard + API, opt-in
- 04General availabilityDocs, changelog, support macros
Each phase has a go/no-go review against the guardrail metric and support-ticket trends. Support and documentation updates ship with each phase, not after.
10Risks & open questions
| Risk / question | Mitigation / owner |
|---|---|
| Customers set long overlap windows and never retire old keys | Default to 24h; nudge emails before expiry · Product |
| Cache invalidation delays revocation in edge regions | Load test propagation pre-beta · Engineering |
| Should rotation be allowed for keys with no recent usage? | Decide with Security before public beta · Product + Security |
| Do enterprise plans need approval workflows for rotation? | Validate with design partners in private beta · Product |