Change Password

Change the password for the currently authenticated user.

Request

POST /api/v1/auth/change-password

Authentication

Bearer JWT - Requires a valid access token.

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Request Body

{
  "currentPassword": "OldSecurePass123!",
  "newPassword": "NewSecurePass456!"
}

Name	Type	Required	Description
currentPassword	string	Yes	User's current password for verification
newPassword	string	Yes	New password (8-128 characters, must comply with organization password policy)

Response

Success Response (200 OK)

{}

The endpoint returns an empty response body with a 200 OK status code when the password is successfully changed.

Password Policy Validation

The new password must comply with the organization's password policy. Common requirements include:

• Minimum length: 8 characters
• Maximum length: 128 characters
• May require uppercase letters
• May require lowercase letters
• May require numbers
• May require special characters
• May prevent reuse of recent passwords

The specific requirements depend on your organization's configured password policy.

Error Responses

Status Code	Description
400 Bad Request	Invalid request body (missing fields, new password doesn't meet policy requirements, new password same as current)
401 Unauthorized	Missing, invalid, or expired access token, or incorrect current password
403 Forbidden	User or organization is suspended
422 Unprocessable Entity	New password fails organization password policy validation (response includes policy requirements)
429 Too Many Requests	Rate limit exceeded
500 Internal Server Error	Server error occurred

Password Policy Error Response Example

{
  "error": "Password does not meet policy requirements",
  "details": {
    "minLength": 8,
    "maxLength": 128,
    "requireUppercase": true,
    "requireLowercase": true,
    "requireNumbers": true,
    "requireSpecialChars": true,
    "preventReuse": 5,
    "violations": [
      "Password must contain at least one uppercase letter",
      "Password must contain at least one special character"
    ]
  }
}

Example

curl -X POST https://api.entryguard.io/api/v1/auth/change-password \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjNlNDU2Ny1lODliLTEyZDMtYTQ1Ni00MjY2MTQxNzQwMDAiLCJvcmdJZCI6IjIyM2U0NTY3LWU4OWItMTJkMy1hNDU2LTQyNjYxNDE3NDAwMSIsInJvbGVzIjpbIk9SR19BRE1JTiJdLCJpYXQiOjE3MDkwNDk2MDAsImV4cCI6MTcwOTA1MzIwMH0.xyz123" \
  -H "Content-Type: application/json" \
  -d '{
    "currentPassword": "OldSecurePass123!",
    "newPassword": "NewSecurePass456!"
  }'

Example Response (Success)

{}

Example Error Response (Invalid Current Password)

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "error": "Current password is incorrect"
}

Example Error Response (Policy Violation)

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
  "error": "Password does not meet policy requirements",
  "details": {
    "minLength": 8,
    "requireUppercase": true,
    "requireLowercase": true,
    "requireNumbers": true,
    "requireSpecialChars": true,
    "violations": [
      "Password must contain at least one special character"
    ]
  }
}

Usage Notes

Session Persistence

• Changing your password does NOT invalidate existing access tokens or refresh tokens
• Active sessions remain valid until their tokens expire
• If you want to force logout from all devices after password change, you should also revoke all refresh tokens (this requires a separate admin action)

Security Best Practices

1. Always validate the current password before allowing a change
2. Enforce strong password policies appropriate to your security requirements
3. Consider implementing rate limiting on password change attempts
4. Log password changes in the audit log for security monitoring
5. Optionally send an email notification to the user when their password is changed

Password Policy Configuration

Organization admins can configure password policies through the organization settings. The policy is enforced at the organization level and applies to all users.

Related Endpoints

• Reset Password - Reset password using email token (for forgotten passwords)
• Forgot Password - Request password reset email