Verification Prompts

EXECUTIVE SUMMARY

What is this feature?

Verification Prompt is a reusable security feature that requires administrators to verify their identity before performing sensitive or destructive actions. After successful verification, the system issues a temporary single-use re-authentication token that authorizes the requested operation.

Why does it matter?

Sensitive administrative actions should require more than an active login session. The Verification Prompt protects critical operations by ensuring the administrator intentionally confirms their identity before the backend executes the request.

What's the MVP scope?

• Verify administrator identity before protected actions.

• Support both password-based and OAuth-based administrator accounts.

• Generate temporary single-use verification tokens.

• Validate verification tokens before executing sensitive APIs.

1. USER PAIN POINT & SOLUTION

Without Verification Prompt

Administrators can immediately perform destructive actions using only their active session.

Pain Point

Emotional: Administrators may accidentally perform irreversible actions.
Functional: Sensitive operations have no secondary identity verification.
Business Impact: Increased security risk for privileged administrative functions.

Current State (Already Implemented)

Protected administrative actions require successful identity verification before execution.

2. 4D FRAMEWORK MAPPING

Diagnose

Identifies sensitive administrative actions requiring additional verification.

Design

Provides a reusable identity verification workflow.

Develop

Generates and validates temporary verification tokens.

Deliver

Protects destructive administrative APIs before execution.

3. USER FLOWS

Entry Point

Automatically triggered before protected administrative operations.

Success Criteria

Administrator successfully verifies identity and the protected operation proceeds.

Main Flow

1. Administrator initiates a protected action.

2. Verification Prompt opens.

3. Authentication method is detected.

4. Administrator verifies identity.

5. Verification token is generated.

6. Protected API receives the verification token.

7. Backend validates the token.

8. Requested action is completed.

Edge Cases

• Invalid password

• Incorrect email confirmation

• Expired verification token

• Previously consumed verification token

• API request failure

Decision Points

IF administrator uses email/password authentication

→ Verify password.

ELSE

→ Verify primary email.

4. INFORMATION ARCHITECTURE

Primary Information

• Verification Token

• Authentication Method

Secondary Information

• Verification Status

• Token Expiration

Tertiary Information

• Audit Logs

Actions
Primary CTA: Verify Identity
Secondary Actions: Cancel, Retry

5. WIREFRAMES

Excluded — Feature fully implemented.

6. WIREFLOWS

Excluded — Feature fully implemented.

7. PROTOTYPE

Excluded — Feature fully implemented.

8. BACKEND SCHEMA

Database Tables

admin_reauth_tokens

Stores temporary verification tokens issued after successful administrator authentication.

Example:
{
  "admin_clerk_id": "...",
  "token": "...",
  "expires_at": "...",
  "used": false
}

audit_logs

Stores verification success and failure events.

9. API ENDPOINTS

Endpoint 1: GET /api/admin/reauth
Purpose: Determines the administrator's authentication method.
Auth: Administrator access required.
Response Data: Authentication method (password or OAuth).

Endpoint 2: POST /api/admin/reauth
Purpose: Verifies administrator credentials and generates a temporary verification token.
Auth: Administrator access required.
Request Body: Verification credentials.
Response Data: Verification token.

10. DATA REQUIREMENTS

Frontend Needs

• Authentication method

• Verification input

• Verification token

• Error state

• Loading state

API Calls Frontend Will Make

• Determine administrator authentication method.

• Verify administrator identity.

• Receive temporary verification token.
  

11. PERFORMANCE CONSIDERATIONS

Database Optimization

Verification tokens are lightweight records stored temporarily. Each token is consumed after a single successful request or expires automatically after five minutes.

12. SECURITY & AUTHORIZATION

Who Can Access This Feature?

Administrator: Full access.
Reviewer: No access.
Creator: No access.
Learner: No access.

13. ERROR HANDLING

Current Existing Error Handling

• Invalid credentials return an authentication error.

• Expired verification tokens are rejected.

• Previously consumed tokens are rejected.

• Invalid verification requests fail schema validation.

• Unauthorized users cannot request verification tokens.

• Verification failures are recorded in audit logs.
  

14. TESTING CHECKLIST

Happy Path

• Password verification

• OAuth verification

• Verification token generation

• Protected API authorization

Edge Cases

• Wrong password

• Invalid email confirmation

• Expired verification token

• Token reuse

• Unauthorized access
  

15. OPEN QUESTIONS

• Should multi-factor authentication be supported in future releases?

• Should verification token expiration be configurable?
  

16. OUT OF SCOPE

• Multi-factor authentication

• Password reset

• Session management

• Long-lived verification tokens
  

17. SUCCESS METRICS

• Verification success rate

• Verification failure rate

• Token generation success rate

• Protected API authorization success rate

18. DEPENDENCIES

This feature depends on:

• Clerk Authentication

• Supabase

• Administrator APIs

These features depend on this:

• Secure User Delete

• Agency Ownership Transfer

• Gemini Configuration

• Future protected administrative operations
  

19. TIMELINE & OWNERSHIP

Sprint: Feature already implemented and deployed.
Backend: Krizha Onise Cortez
Frontend: Krizha Onise Cortez
Estimated Completion: Feature completed.