Password Management

Manage passwords including changes, resets, and understanding password policies.

Change Password

Authenticated users can change their own password.

Endpoint

POST /auth/change-password

Request

{
  "currentPassword": "OldP@ssword123",
  "newPassword": "NewSecureP@ss456"
}

Response (200 OK)

{
  "message": "Password changed successfully"
}

Error Responses

400 Bad Request — Invalid Current Password

{
  "type": "https://api.cortex.purplelab.ai/errors/invalid-password",
  "title": "Invalid Password",
  "status": 400,
  "detail": "Current password is incorrect",
  "instance": "/auth/change-password"
}

400 Bad Request — Password Policy Violation

{
  "type": "https://api.cortex.purplelab.ai/errors/validation",
  "title": "Validation Error",
  "status": 400,
  "detail": "New password must contain at least one special character",
  "instance": "/auth/change-password"
}

Password Policy

All passwords must meet these requirements:

Requirement	Description
Minimum length	8 characters
Maximum length	128 characters
Uppercase	At least 1 character (A-Z)
Lowercase	At least 1 character (a-z)
Number	At least 1 digit (0-9)
Special character	At least 1 of: !@#$%^&*()_+-=[]{}

Valid Password Examples

SecureP@ss123      ✓
MyStr0ng!Password  ✓
C0mplex&Secure     ✓

Invalid Password Examples

password           ✗ (no uppercase, number, or special char)
PASSWORD123        ✗ (no lowercase or special char)
Pass@word          ✗ (no number)
12345678           ✗ (no letters or special char)
Short1!            ✗ (less than 8 characters)

Code Examples

TypeScript

async function changePassword(
  accessToken: string,
  currentPassword: string,
  newPassword: string
): Promise<void> {
  const response = await fetch('http://localhost:8091/auth/change-password', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${accessToken}`,
    },
    body: JSON.stringify({ currentPassword, newPassword }),
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.detail);
  }
}

// Usage
try {
  await changePassword(accessToken, 'OldP@ss123', 'NewP@ss456');
  console.log('Password changed successfully');
} catch (error) {
  console.error('Failed to change password:', error.message);
}

cURL

curl -X POST http://localhost:8091/auth/change-password \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access-token>" \
  -d '{
    "currentPassword": "OldP@ssword123",
    "newPassword": "NewSecureP@ss456"
  }'

Password Validation Utility

Use this regex pattern for client-side validation:

const PASSWORD_REGEX = /^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)(?=.*[!@#$%^&*()_+\-=\[\]{}|;:,.<>?]).{8,128}$/;

function isValidPassword(password: string): boolean {
  return PASSWORD_REGEX.test(password);
}

function getPasswordErrors(password: string): string[] {
  const errors: string[] = [];

  if (password.length < 8) {
    errors.push('Password must be at least 8 characters');
  }
  if (password.length > 128) {
    errors.push('Password must be at most 128 characters');
  }
  if (!/[a-z]/.test(password)) {
    errors.push('Password must contain at least one lowercase letter');
  }
  if (!/[A-Z]/.test(password)) {
    errors.push('Password must contain at least one uppercase letter');
  }
  if (!/\d/.test(password)) {
    errors.push('Password must contain at least one number');
  }
  if (!/[!@#$%^&*()_+\-=\[\]{}|;:,.<>?]/.test(password)) {
    errors.push('Password must contain at least one special character');
  }

  return errors;
}

Security Considerations

1. Password Hashing: Passwords are hashed using Argon2id before storage
2. No Password Retrieval: Passwords cannot be retrieved — only reset
3. Session Invalidation: Consider invalidating other sessions after password change
4. Rate Limiting: Password change endpoint is rate-limited