Multi-Factor Authentication Flow Documentation Prompt

This prompt is designed for security engineers and API product managers who have already finalized the design of a multi-factor authentication (MFA) system and now need to convert that specification into unambiguous, structured documentation. The job-to-be-done is producing developer-facing or auditor-ready reference material that covers every state in the MFA lifecycle: enrollment of TOTP, WebAuthn, and backup codes; challenge flows for each factor; fallback chain logic when a primary factor is unavailable; account recovery procedures; and a complete catalog of error states with actionable remediation steps. If your MFA flow design is still in flux, this prompt is premature—it assumes the architecture decisions are locked and the task is documentation, not design exploration.

The ideal user brings a defined MFA specification to the prompt, which may exist as internal design docs, API endpoint definitions, sequence diagrams, or a working implementation. Required context includes the list of supported factors, the enrollment and challenge API contracts, session and token lifecycle rules, rate limiting and lockout policies, and the recovery flow for lost factors. The prompt uses this context to generate documentation that leaves no gap in the user journey: every redirect, every error response, every fallback decision point is described. The output is structured for downstream consumption by API consumers, integration partners, and compliance auditors who need to verify that the documented flow matches the implemented security properties.

Do not use this prompt for general authentication overviews, OAuth grant type documentation, session management guides, or social login integration docs. It is specifically scoped to MFA enrollment and challenge flows. It also should not be used to generate marketing copy, user-facing help center articles, or UI microcopy—the output is technical reference documentation. If your documentation needs include auth terminology standardization, completeness audits, or sequence diagram generation, those are separate prompt playbooks. Before running this prompt, ensure you have the MFA flow design finalized and the necessary API contracts, error catalogs, and recovery procedures defined. The prompt will produce documentation that is only as complete as the specification you provide.

This prompt template is designed to generate thorough, security-focused documentation for multi-factor authentication flows. It guides the model to produce step-by-step user journeys covering enrollment, challenge, and recovery paths while maintaining strict attention to error states, fallback chains, and security considerations. Replace each square-bracket placeholder with your specific MFA implementation details before use.

codeCopy
You are a senior security documentation engineer. Generate comprehensive MFA flow documentation based on the following specifications.

## MFA Configuration
- Primary Method: [PRIMARY_MFA_METHOD: TOTP / WebAuthn / SMS / Push Notification]
- Secondary Methods: [SECONDARY_MFA_METHODS: comma-separated list]
- Recovery Options: [RECOVERY_OPTIONS: backup_codes / recovery_email / admin_reset]
- Token Lifetime: [TOKEN_LIFETIME: e.g., 30 seconds for TOTP, 5 minutes for SMS]
- Max Attempts: [MAX_ATTEMPTS: number]
- Lockout Policy: [LOCKOUT_POLICY: e.g., 15-minute cooldown after 5 failures]

## User Journey Context
- Application Type: [APP_TYPE: web / mobile / CLI / API]
- User Authentication State: [AUTH_STATE: initial_enrollment / re-authentication / step-up / device_change]
- Platform Constraints: [PLATFORM_CONSTRAINTS: e.g., no biometrics, FIDO2 required]

## Documentation Requirements
Generate documentation covering these sections in order:

### 1. Enrollment Flow
- Prerequisites and setup steps
- Step-by-step enrollment with user actions and system responses
- QR code or registration challenge details for [PRIMARY_MFA_METHOD]
- Secondary method enrollment sequence
- Recovery option setup (backup code generation and storage guidance)
- Enrollment completion confirmation and next steps

### 2. Authentication Challenge Flow
- Trigger conditions for MFA challenge
- Primary method challenge sequence with timeout handling
- Fallback chain: what happens when primary method fails or is unavailable
- Secondary method fallback with clear user messaging
- Error states: invalid code, expired token, network failure, device lost
- Lockout and rate limiting behavior with user-facing messages

### 3. Recovery Flow
- Recovery initiation conditions
- Step-by-step recovery using [RECOVERY_OPTIONS]
- Identity verification steps before recovery
- New device enrollment after recovery
- Session handling during recovery

### 4. Error Reference
- Complete error code table with HTTP status codes
- User-facing error messages for each state
- Troubleshooting guidance for common issues
- Support escalation criteria

### 5. Security Considerations
- Token transmission security (HTTPS requirements)
- Storage recommendations for secrets and recovery codes
- Session binding after successful MFA
- Brute force protection details
- Phishing resistance notes for [PRIMARY_MFA_METHOD]

## Output Format
- Use clear heading hierarchy (H2 for major sections, H3 for subsections)
- Include code blocks for API request/response examples
- Use callouts (⚠️ WARNING, ℹ️ NOTE, 🔒 SECURITY) for critical information
- Provide Mermaid sequence diagrams in text for enrollment and challenge flows
- Mark all placeholder values with [BRACKETED_PLACEHOLDERS] that need replacement

## Constraints
- Never include hardcoded secrets, keys, or real credentials in examples
- Flag any security-sensitive configuration choices with rationale
- Document all failure modes, not just happy paths
- Ensure recovery path documentation is as detailed as primary flow
- Include rate limit headers in all API response examples
- Specify exact cookie attributes (HttpOnly, Secure, SameSite) where applicable

After pasting this template, replace each bracketed placeholder with your actual MFA implementation details. For production use, add a validation step that checks the generated documentation against a checklist: all error states documented, recovery paths complete, no hardcoded secrets, and consistent terminology throughout. For high-security environments, route the output through a human security review before publication.

This prompt is designed to be called programmatically as part of a security documentation generation workflow, not as a one-off chat interaction. The implementation harness wraps the prompt in a pipeline that validates structural completeness, enforces MFA-specific safety checks, and routes outputs to human review before publication. Treat this prompt as a function with typed inputs and outputs: it accepts a structured context object (flow type, enrollment method, recovery paths, error catalog) and returns a documentation artifact that must pass automated evals before reaching a technical reviewer.

Pipeline integration steps: 1) Assemble the context object from your auth system's configuration, API specs, and existing documentation. 2) Inject the context into the prompt template's [CONTEXT] placeholder along with the [FLOW_TYPE], [ENROLLMENT_METHODS], [RECOVERY_PATHS], and [ERROR_CATALOG] variables. 3) Call the model with response_format set to a JSON schema that enforces the required sections (Overview, Enrollment Flow, Challenge Flow, Recovery Flow, Error Reference, Security Considerations). 4) Run automated evals: check that every error code in the catalog appears in the output, verify that all enrollment methods have corresponding challenge descriptions, confirm backup code and recovery paths are documented, and flag any missing fallback chain documentation. 5) If evals fail, retry with the eval failure messages injected as additional [CONSTRAINTS] context. 6) Route passing outputs to a human security reviewer with a diff against the previous documentation version.

Model choice and tool use: Use a model with strong structured output support (GPT-4o, Claude 3.5 Sonnet, or equivalent) and enable strict JSON mode. This prompt does not require RAG or external tool calls during generation—the context object should contain all necessary information. However, consider a pre-generation retrieval step that pulls the current auth documentation, API error code definitions, and relevant RFC sections (RFC 6238 for TOTP, RFC 4226 for HOTP, WebAuthn spec) to populate the context object accurately. Retry strategy: Implement up to 3 retries with escalating temperature (0.0 → 0.2 → 0.4) on eval failure. If all retries fail, log the failure, capture the partial output, and create a manual documentation ticket. Logging and audit: Log every generation attempt with the prompt version, model, context hash, eval results, and reviewer decision. This is critical for security documentation where change traceability matters for compliance reviews. What to avoid: Do not ship MFA documentation without human review—missing or incorrect fallback chain documentation can lock users out of accounts. Do not use this prompt for real-time documentation generation in user-facing products; it is a drafting tool, not a live reference.