Auth & Security

Password Recovery & Reset Loop

Test end-to-end account recovery flows with real-time virtual email delivery. Initiating a password reset triggers an authentic HTML recovery email delivered straight into your isolated Virtual Mailbox without third-party email service credentials.

End-to-End Recovery Flow

Execute the complete password reset lifecycle in 3 intuitive steps:

Step 1: Request Recovery Link (/auth/forgot-password)

Submits the user email address. The backend generates a secure single-use recovery token and renders an email:

Dispatch Reset Link to admin@example.com

POST

response.json

{

// Click "Send" above to execute this request against the live server.

}

Step 2: Inspect Dispatched Email in Virtual Inbox

Navigate to the virtual mailbox to view the rendered HTML email template, extract the recovery token, or copy the direct password reset URL.

Open Virtual Mailbox (/docs/inbox/email-mailbox)

Step 3: Submit New Password (/auth/reset-password)

Submits the reset token from the email along with the updated password:

Complete Password Reset

POST

response.json

{

// Click "Send" above to execute this request against the live server.

}

Recovery Security Best Practices

Critical defensive patterns modeled by the Playground API authentication gateway:

Email Enumeration Defense

The /auth/forgot-password endpoint returns HTTP 200 regardless of whether the email exists, preventing user enumeration.

Strict Token Expiration

Reset tokens expire after 15 minutes. Once consumed to update a password, the token is permanently invalidated.

Automatic Session Invalidation

Upon successful password reset, all existing refresh token families and active sessions are revoked across all client devices.

Frontend Recovery Recipes

Production-ready React 19 hooks and Next.js Server Action patterns:

passwordRecovery.ts

// React 19 Custom Password Reset Hook

import { useState } from 'react';

export function usePasswordRecovery() {

const [loading, setLoading] = useState(false);

const [status, setStatus] = useState<'idle' | 'email_sent' | 'reset_success' | 'error'>('idle');

const [errorMessage, setErrorMessage] = useState('');

// 1. Initiate password reset (sends email to virtual mailbox)

const requestReset = async (email: string) => {

setLoading(true);

setErrorMessage('');

try {

const res = await fetch('https://playground.nileslabs.com/api/v1/auth/forgot-password', {

method: 'POST',

headers: { 'Content-Type': 'application/json' },

body: JSON.stringify({ email }),

});

if (!res.ok) throw new Error('Password reset request failed');

setStatus('email_sent');

} catch (err: any) {

setErrorMessage(err.message);

setStatus('error');

} finally {

setLoading(false);

}

};

// 2. Submit new password with received token

const completeReset = async (token: string, newPassword: string) => {

setLoading(true);

setErrorMessage('');

try {

const res = await fetch('https://playground.nileslabs.com/api/v1/auth/reset-password', {

method: 'POST',

headers: { 'Content-Type': 'application/json' },

body: JSON.stringify({ token, new_password: newPassword }),

});

if (!res.ok) throw new Error('Invalid or expired reset token');

setStatus('reset_success');

} catch (err: any) {

setErrorMessage(err.message);

setStatus('error');

} finally {

setLoading(false);

}

};

return { requestReset, completeReset, loading, status, errorMessage };

}

PreviousClock Skew Drift

NextDual-Mode Sandboxing