# Password Reset Request

div
strong
🔨 In Development
 — This section is still being developed and may change.


**POST** `/v1/auth/password/reset` - Initiate a password reset flow by requesting a reset link or code to be sent to the user's email address. This endpoint is safe to call for unknown emails and always responds generically to avoid information disclosure.

Sends a password reset email with a secure, time-limited token to the user's email address if the account exists. The response is intentionally generic to prevent email enumeration attacks.

#### Request Body

**`email`** string required

User's email address for password reset.

## Returns

A Password Reset Response object containing confirmation message for the reset request.

**`success`** boolean

Indicates if the password reset request was processed successfully. Always `true` for valid requests.

**`message`** string

Generic success message. The same message is returned regardless of whether the email exists to prevent email enumeration attacks.

Request Password Reset

```bash
curl -X POST https://api.freddy.aitronos.com/v1/auth/password/reset \
-H "Content-Type: application/json" \
-d '{
  "email": "user@example.com"
}'
```


```python
import requests

response = requests.post(
  "https://api.freddy.aitronos.com/v1/auth/password/reset",
  headers={"Content-Type": "application/json"},
  json={
      "email": "user@example.com"
  }
)

result = response.json()
if result["success"]:
print(result["message"])
  # Generic message: "If the account exists, a password reset email has been sent"
else:
  print("Password reset request failed")
```


```javascript
const response = await fetch('https://api.freddy.aitronos.com/v1/auth/password/reset', {
method: 'POST',
headers: {
  'Content-Type': 'application/json'
},
body: JSON.stringify({
  email: 'user@example.com'
})
});

const result = await response.json();
if (result.success) {
console.log(result.message);
// Generic message: "If the account exists, a password reset email has been sent"
} else {
console.error('Password reset request failed');
}
```

Password Reset Flow

```python
import requests

class PasswordResetFlow:
  def __init__(self, base_url: str = "https://api.freddy.aitronos.com/v1"):
      self.base_url = base_url

  def request_reset(self, email: str) -> dict:
      """Step 1: Request password reset email"""
      response = requests.post(
          f"{self.base_url}/auth/password/reset",
          headers={"Content-Type": "application/json"},
          json={"email": email}
      )
      
      result = response.json()
      if result.get("success"):
          print("If the account exists, a password reset email has been sent.")
          print("Please check your email for reset instructions.")
          return result
      else:
          raise ValueError(f"Password reset request failed: {result.get('detail', 'Unknown error')}")

# Usage
reset_flow = PasswordResetFlow()
try:
  reset_flow.request_reset("user@example.com")
  print("Check your email for password reset instructions")
except ValueError as e:
  print(f"Error: {e}")
```


```javascript
class PasswordResetFlow {
constructor(baseUrl = 'https://api.freddy.aitronos.com/v1') {
  this.baseUrl = baseUrl;
}

async requestReset(email) {
  const response = await fetch(`${this.baseUrl}/auth/password/reset`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ email })
  });

  const result = await response.json();
  if (result.success) {
    console.log('If the account exists, a password reset email has been sent.');
    console.log('Please check your email for reset instructions.');
    return result;
  } else {
    throw new Error(result.detail || 'Password reset request failed');
  }
}
}

// Usage
const resetFlow = new PasswordResetFlow();
try {
await resetFlow.requestReset('user@example.com');
console.log('Check your email for password reset instructions');
} catch (error) {
console.error('Error:', error.message);
}
```

Response examples

```json
{
"success": true,
"message": "If the account exists, a password reset email has been sent"
}
```


```json
{
"detail": "Invalid email format"
}
```


```json
{
"detail": "Too many reset requests. Please try again later."
}
```