FRD-031: API Key Manager

Field	Value
Owner	David Holmes
Status	Draft
Last Updated	2026-05-26
Related	ADR-027 (Default Tech Stack)
Target Release	v2.0.0
Type	Widget
Size	M
Priority	P1 — SaaS Widget

---

Document Summary

Build an API Key Manager widget that provides list, create, reveal-once, rotate, and revoke UX for API keys. The widget displays scoped permission badges, last-used metadata, and handles loading, empty, and destructive-confirmation states. It builds on the existing secret-reveal-field.tsx and secret-visibility-toggle.tsx primitives.

---

Introduction

Overview

SaaS applications universally need API key management: listing existing keys, creating new ones with scoped permissions, revealing a key exactly once after creation, rotating compromised keys, and revoking keys with confirmation. The design system provides SecretRevealField and SecretVisibilityToggle for secret display, but no composed widget for the full key lifecycle. Teams repeatedly build this pattern from scratch.

Goals

• Provide a self-contained ApiKeyManager widget handling the full key lifecycle (list, create, reveal-once, rotate, revoke).
• Display scoped permission badges per key.
• Show last-used timestamp and creation date metadata.
• Handle loading, empty, and error states with appropriate visual treatments.
• Provide destructive-action confirmation dialogs for rotate and revoke.
• Ship with comprehensive Storybook stories and unit tests.

Non-Goals

• Actual API integration (key generation, storage); the widget is headless and calls consumer-provided callbacks.
• OAuth token management (different UX pattern).
• Rate limiting or usage analytics display.

---

Scope

In Scope

Item	Description
Key list view	DataGrid-based table showing key name, masked prefix, permissions, last used, created date, and actions.
Create key flow	Modal or slide-out panel with name input, permission scope checkboxes, and a generate action.
Reveal-once display	After creation, display the full key using SecretRevealField with auto-remask and copy-to-clipboard.
Rotate key	Confirmation dialog explaining that the old key will be invalidated; returns new key via callback.
Revoke key	Destructive confirmation dialog with key name echo; calls revoke callback.
Permission badges	Badge components showing scoped permissions (e.g., “read”, “write”, “admin”).
Metadata display	Last-used relative timestamp, creation date, optional expiry date.
State handling	Loading skeleton, empty state (“No API keys yet”), error state with retry.
Stories and tests	Storybook stories for all states; unit tests for interaction flows.

Out of Scope

Item	Reason
Key generation logic	Backend concern; widget calls onCreate callback and displays the returned key.
Usage analytics	Separate widget; API Key Manager focuses on CRUD.
OAuth/SSO token management	Different interaction model and security considerations.

---

Users and Pain Points

User	Pain Point
SaaS developers	Build API key management UI from scratch for every project; inconsistent patterns across teams.
DevOps/platform engineers	Need to manage service account keys; existing tools are CLI-only.
End users managing API keys	Cannot easily see which permissions a key has or when it was last used.
Security teams	No standard revoke confirmation flow; accidental revocations or missed rotations.

---

Definitions

Term	Definition
Reveal-once	A key is shown in full exactly once after creation; subsequent views show only a masked prefix.
Key rotation	Generating a new key to replace an existing one; the old key is invalidated immediately.
Scoped permissions	A set of capabilities assigned to a key (e.g., “read:data”, “write:data”, “admin”).
Masked prefix	The first and last few characters of a key shown with the middle masked (e.g., sk_live_abc...xyz).

---

Current State

• SecretRevealField (src/components/ui/secret-reveal-field.tsx): Read-only secret display with reveal/copy actions, auto-remask timer. Accepts value, revealed, onRevealedChange, autoRemaskMs, onCopy.
• SecretVisibilityToggle (src/components/ui/secret-visibility-toggle.tsx): Eye icon toggle for show/hide.
• DataGrid (src/components/ui/data-grid.tsx): Full-featured table with sort, filter, paginate, row selection.
• No API key management widget exists.
• Badge component exists for permission display.
• StatusCard exists for empty/error states.
• AlertDialog exists for destructive confirmations.

---

Proposed Solution

Build src/components/widgets/api-key-manager.tsx as a composed widget:

Key List

Uses DataGrid with columns: Name, Key (masked prefix), Permissions (badge group), Last Used, Created, Actions (rotate/revoke dropdown). The list supports search filtering by key name.

Create Flow

A “Create API Key” button opens a SlideOutPanel or Dialog containing:

1. Name input (required).
2. Permission scope checkboxes (consumer provides available scopes).
3. Optional expiry date picker.
4. “Generate Key” button calls onCreate(config) callback.

Reveal-Once

After onCreate resolves with the full key string:

1. The panel transitions to a reveal-once view using SecretRevealField.
2. A prominent “Copy” button and warning text: “This key will not be shown again.”
3. “Done” button closes the panel and the key list refreshes.

Rotate

Clicking “Rotate” on a key row opens AlertDialog with destructive variant:

• Explains the old key will be invalidated immediately.
• Calls onRotate(keyId) callback on confirm.
• Shows the new key in reveal-once mode.

Revoke

Clicking “Revoke” opens AlertDialog with destructive variant:

• Requires typing the key name to confirm (pattern from GitHub/Vercel).
• Calls onRevoke(keyId) callback on confirm.

State Handling

• Loading: DataGrid skeleton rows.
• Empty: StatusCard with “No API keys” message and “Create your first key” CTA.
• Error: StatusCard with error message and retry button.

---

Requirements

Requirement Priorities

• Must Have: Key list, create flow, reveal-once, revoke with confirmation.
• Should Have: Rotate flow, permission badges, last-used metadata.
• Could Have: Key expiry date, bulk revoke, key name validation.

---

Functional Requirements

ID	Requirement	Priority
FR-01	Widget displays a DataGrid of API keys with name, masked prefix, permissions, last used, created date, and actions columns.	Must
FR-02	”Create API Key” button opens a form with name input and permission scope selection.	Must
FR-03	After key creation, the full key is displayed once using SecretRevealField with copy-to-clipboard.	Must
FR-04	A warning is shown that the key will not be displayed again after the reveal-once panel is closed.	Must
FR-05	”Revoke” action opens a destructive AlertDialog; user must type the key name to confirm.	Must
FR-06	”Rotate” action opens a destructive AlertDialog explaining the old key will be invalidated.	Should
FR-07	After rotation, the new key is shown in reveal-once mode.	Should
FR-08	Permission scopes render as colored Badge components in the key list.	Should
FR-09	Last-used timestamp displays as relative time (e.g., “2 hours ago”) with absolute tooltip.	Should
FR-10	Loading state renders DataGrid skeleton rows.	Must
FR-11	Empty state renders a StatusCard with CTA to create the first key.	Must
FR-12	Error state renders a StatusCard with error message and retry button.	Must
FR-13	Widget calls consumer-provided callbacks (onCreate, onRotate, onRevoke) and does not manage API state internally.	Must

---

Non-Functional Requirements

ID	Requirement	Target
NFR-01	Widget renders key list with 50 keys in < 50ms.	Measured via React Profiler.
NFR-02	Bundle size	< 10 KB gzipped (excluding shared DataGrid and Dialog deps).
NFR-03	Reveal-once key is never persisted in component state after panel close.	Security requirement; key is cleared from state on unmount.
NFR-04	Dark mode	Full token-based dark mode support.
NFR-05	Responsive	Usable on tablet (768px+); degrades gracefully on mobile.

---

API/Interface Requirements

interface ApiKey {
  id: string;
  name: string;
  prefix: string;           // masked display, e.g. "sk_live_abc...xyz"
  permissions: string[];     // e.g. ["read:data", "write:data"]
  lastUsed?: string;         // ISO datetime or relative string
  createdAt: string;         // ISO datetime
  expiresAt?: string;        // ISO datetime
}

interface ApiKeyManagerProps {
  keys: ApiKey[];
  availablePermissions: string[];
  loading?: boolean;
  error?: string;
  onRetry?: () => void;
  onCreate: (config: { name: string; permissions: string[]; expiresAt?: string }) => Promise<{ key: string }>;
  onRotate?: (keyId: string) => Promise<{ key: string }>;
  onRevoke: (keyId: string) => Promise<void>;
  emptyTitle?: string;
  emptyDescription?: string;
  className?: string;
}

---

Accessibility Requirements

ID	Requirement
A11Y-01	Create and revoke dialogs trap focus and return focus to trigger on close.
A11Y-02	Revoke confirmation input has aria-label describing what to type.
A11Y-03	Permission badges use aria-label describing the permission scope.
A11Y-04	Reveal-once SecretRevealField announces “Key copied to clipboard” via aria-live on copy.
A11Y-05	DataGrid keyboard navigation works for all action buttons in the actions column.
A11Y-06	All components pass axe-core automated checks with zero violations.

---

Content and Documentation Requirements

ID	Requirement
DOC-01	Storybook docs page with usage guidelines, prop table, and interactive examples.
DOC-02	Recipes showing integration with TanStack Query for key fetching and mutation.
DOC-03	Security guidance: never log full keys, clear from state after reveal, use HTTPS-only.

---

Dependencies

Dependency	Type	Risk
src/components/ui/secret-reveal-field.tsx	Internal	Low — core reveal-once primitive.
src/components/ui/secret-visibility-toggle.tsx	Internal	Low — visibility toggle icon.
src/components/ui/data-grid.tsx	Internal	Low — table display.
src/components/ui/badge.tsx	Internal	Low — permission badges.
src/components/ui/status-card.tsx	Internal	Low — empty/error states.
src/components/ui/alert-dialog.tsx	Internal	Low — destructive confirmations.

---

Risks and Tradeoffs

Risk	Likelihood	Impact	Mitigation
Reveal-once key accidentally persists in React state or DevTools	Low	Critical	Clear key from state on panel close; use a ref instead of state for the raw key.
Revoke name-match confirmation is too strict (case sensitivity, whitespace)	Medium	Low	Trim and lowercase comparison; show the exact expected string.
Widget API is too opinionated for diverse backend shapes	Medium	Medium	Keep ApiKey interface minimal; consumers transform their data to fit.

---

Open Questions

#	Question	Owner	Status
OQ-01	Should the create flow use a Dialog or SlideOutPanel?	David Holmes	Open
OQ-02	Should the widget support bulk revoke (multi-select + revoke all)?	David Holmes	Open
OQ-03	Should key expiry be displayed as a badge with color coding (green/yellow/red)?	David Holmes	Open

---

Acceptance Criteria

#	Criterion
AC-01	Widget renders a list of API keys with name, masked prefix, permissions, last used, and actions.
AC-02	Create flow collects name and permissions, calls onCreate, and displays the full key exactly once.
AC-03	Reveal-once view includes copy button and warning text; key is cleared from state on close.
AC-04	Revoke flow requires typing the key name and calls onRevoke on confirmation.
AC-05	Loading, empty, and error states render appropriate visual treatments.
AC-06	All components pass axe-core checks with zero violations.
AC-07	Storybook stories exist for all states and interaction flows.
AC-08	Unit tests cover create, reveal-once, revoke confirmation, and state transitions.
AC-09	pnpm typecheck and pnpm vitest run --project unit pass with zero errors.

---

LLM Handoff Instructions

When implementing this FRD:

1. Create src/components/widgets/api-key-manager.tsx. Follow the pattern from people-table.tsx — define the data interface, column factory function, and composed widget.
2. DataGrid columns: Name (text), Key (masked prefix with monospace font), Permissions (badge group), Last Used (relative time), Created (date), Actions (dropdown with Rotate/Revoke).
3. Create flow: Use SlideOutPanel with a form containing TextField for name and a checkbox group for permissions. On submit, call onCreate and transition to reveal-once view.
4. Reveal-once: Render SecretRevealField with autoRemaskMs={undefined} (no auto-remask — the key stays visible until the user closes the panel). Add a copy button and warning text. On panel close, clear the key from a ref.
5. Revoke flow: Use AlertDialog with variant="destructive". Add a TextField where the user must type the key name. Disable the confirm button until the input matches.
6. Stories in src/components/widgets/api-key-manager.stories.tsx. Include: Default, Loading, Empty, Error, CreateFlow, RevealOnce, RevokeConfirmation.
7. Tests in src/components/widgets/api-key-manager.test.tsx. Test create callback, reveal-once display, revoke name matching, state transitions.

Key files to reference:

• src/components/ui/secret-reveal-field.tsx — reveal/copy pattern.
• src/components/widgets/people-table.tsx — widget composition pattern.
• src/components/ui/data-grid.tsx — table API.
• src/components/ui/badge.tsx — permission display.
• src/components/ui/status-card.tsx — empty/error states.

---

Decision Log

Date	Decision	Rationale
2026-05-26	Widget is headless (callbacks, not API calls).	Consumers have diverse backends; the widget should be backend-agnostic.
2026-05-26	Reveal-once uses a ref, not state, for the raw key.	Prevents the key from appearing in React DevTools or persisting across renders.
2026-05-26	Revoke requires typing the key name, not just clicking “Confirm”.	Follows the GitHub/Vercel destructive-action confirmation pattern for safety.

---

Document History

Version	Date	Author	Changes
0.1	2026-05-26	David Holmes	Initial draft.