Password Reset API Documentation¶

Overview¶

The password reset functionality allows users to reset their passwords via email. The process involves two main steps: 1. Requesting a password reset (sends email with reset link) 2. Confirming the password reset with a token

Endpoints¶

1. Request Password Reset¶

Endpoint: POST /auth/password-reset/reset_password/

Description: Sends a password reset email to the user if the email exists in the system.

Request Body:

{
  "email": "user@example.com"
}

Response: - Success (200 OK):

{
  "status": "OK"
}

Note: Always returns 200 OK to prevent email enumeration attacks.

Rate Limited (429 Too Many Requests):

{
  "error": "Too many password reset attempts. Please try again later."
}

Rate Limiting: 5 requests per hour per IP address

2. Confirm Password Reset¶

Endpoint: POST /auth/password-reset/reset_password_confirm/

Description: Resets the user's password using the token from the email.

Request Body:

{
  "token": "abc123def456...",
  "password": "NewSecurePassword123!"
}

Response: - Success (200 OK):

{
  "status": "OK"
}

Invalid Token (400 Bad Request):
```
{
  "token": ["Invalid token."]
}
```

Weak Password (400 Bad Request):

{
  "password": [
    "This password is too short. It must contain at least 8 characters.",
    "This password is too common."
  ]
}

Security Features¶

1. Email Enumeration Prevention¶

The password reset request endpoint always returns a 200 OK response, regardless of whether the email exists in the system. This prevents attackers from discovering valid email addresses.

2. Rate Limiting¶

The API limits password reset requests to 5 per hour per IP address to prevent abuse.

3. Token Security¶

Tokens are cryptographically secure random strings (20-30 characters)
Tokens expire after 2 hours
Tokens can only be used once
Tokens are stored hashed in the database

4. Password Requirements¶

Minimum 8 characters
Must contain at least one uppercase letter
Must contain at least one lowercase letter
Must contain at least one number
Validated against Django's password validators

Email Template¶

The password reset email includes: - Clear subject line: "Reset your PiqueTickets Producer Portal password" - Reset link with token - Expiration time warning (2 hours) - Security notice about one-time use - Support contact information

Frontend Integration¶

TypeScript/JavaScript Example:¶

// Request password reset
const requestPasswordReset = async (email: string) => {
  const response = await fetch('https://api.piquetickets.com/auth/password-reset/reset_password/', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ email }),
  });

  if (response.status === 429) {
    throw new Error('Too many attempts. Please try again later.');
  }

  return response.json();
};

// Confirm password reset
const confirmPasswordReset = async (token: string, password: string) => {
  const response = await fetch('https://api.piquetickets.com/auth/password-reset/reset_password_confirm/', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ token, password }),
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.token?.[0] || error.password?.[0] || 'Failed to reset password');
  }

  return response.json();
};

Testing¶

Run the password reset tests:

python manage.py test auth.tests.test_password_reset

Environment Variables¶

Add to your .env file:

PRODUCER_PORTAL_URL=https://producer.piquetickets.com

This URL is used to generate the password reset link in the email.