> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/lopiv2/invenicum/llms.txt
> Use this file to discover all available pages before exploring further.

# Change Password

> Update the authenticated user's password

## Endpoint

<ParamField path="POST /auth/change-password" type="endpoint">
  Change the password for the currently authenticated user
</ParamField>

## Authentication

<Note>
  This endpoint requires authentication. Include a valid JWT token in the `Authorization` header.
</Note>

```http theme={null}
Authorization: Bearer YOUR_JWT_TOKEN
```

## Request Body

<ParamField body="currentPassword" type="string" required>
  The user's current password for verification
</ParamField>

<ParamField body="newPassword" type="string" required>
  The new password to set. Should meet minimum security requirements.
</ParamField>

## Response

<ResponseField name="success" type="boolean" required>
  Indicates whether the password change was successful
</ResponseField>

<ResponseField name="message" type="string">
  Human-readable message describing the result
</ResponseField>

## Example Request

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://api.invenicum.example/v1/auth/change-password \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer YOUR_JWT_TOKEN" \
    -d '{
      "currentPassword": "oldPassword123",
      "newPassword": "newSecurePassword456"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.invenicum.example/v1/auth/change-password', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${token}`
    },
    body: JSON.stringify({
      currentPassword: 'oldPassword123',
      newPassword: 'newSecurePassword456'
    })
  });

  const data = await response.json();
  console.log(data.success);
  ```

  ```python Python theme={null}
  import requests

  headers = {
      'Authorization': f'Bearer {token}',
      'Content-Type': 'application/json'
  }

  response = requests.post(
      'https://api.invenicum.example/v1/auth/change-password',
      headers=headers,
      json={
          'currentPassword': 'oldPassword123',
          'newPassword': 'newSecurePassword456'
      }
  )

  data = response.json()
  ```

  ```dart Dart theme={null}
  import 'package:dio/dio.dart';

  final dio = Dio();
  dio.options.headers['Authorization'] = 'Bearer $token';

  final response = await dio.post(
    '/auth/change-password',
    data: {
      'currentPassword': 'oldPassword123',
      'newPassword': 'newSecurePassword456',
    },
  );

  final success = response.data['success'] == true || response.statusCode == 200;
  ```
</CodeGroup>

## Example Response

### Success Response (200 OK)

```json theme={null}
{
  "success": true,
  "message": "Password updated successfully"
}
```

### Error Response (400 Bad Request)

```json theme={null}
{
  "success": false,
  "message": "La contraseña actual no es correcta"
}
```

### Error Response (401 Unauthorized)

```json theme={null}
{
  "success": false,
  "message": "Authentication required"
}
```

## Error Codes

| Status Code | Description                            |
| ----------- | -------------------------------------- |
| 200         | Password changed successfully          |
| 400         | Current password is incorrect          |
| 401         | Not authenticated or invalid token     |
| 422         | Validation error (e.g., weak password) |
| 500         | Internal server error                  |

## Password Requirements

While not enforced by the API shown in the source code, follow these best practices:

<Card title="Password Security Guidelines" icon="shield-check">
  * Minimum 8 characters
  * Mix of uppercase and lowercase letters
  * At least one number
  * At least one special character
  * Should not match common passwords
  * Should not contain user's email or name
</Card>

## Implementation Details

The password change endpoint (from `api_service.dart:60-82`):

1. Validates the current password on the backend
2. If valid, updates to the new password
3. Returns success status or error message
4. Error messages can be in `message` or `error` fields

<Warning>
  After changing the password, the user's current session remains valid. The JWT token is not invalidated, so the user can continue using the application without re-logging in.
</Warning>

## Common Errors

<Accordion title="Current password is incorrect">
  The `currentPassword` field does not match the user's actual password. The error message may be in Spanish: "La contraseña actual no es correcta".

  **Solution**: Verify the user is entering their correct current password.
</Accordion>

<Accordion title="Token expired or invalid">
  The JWT token in the Authorization header is missing, malformed, or expired.

  **Solution**: Redirect the user to the login page to obtain a fresh token.
</Accordion>

<Accordion title="Connection error">
  Network connectivity issues or backend unavailability.

  **Solution**: Display a user-friendly error message and allow retry. The error is caught as "Error de conexión al cambiar contraseña".
</Accordion>

## Security Notes

* Always use HTTPS in production to protect credentials in transit
* The current password is verified before allowing changes
* Consider implementing rate limiting to prevent brute force attacks
* Log password change events for security auditing
* Consider requiring re-authentication after password change for sensitive accounts

## Related Endpoints

* [Login](/api/auth/login) - Authenticate and obtain token