Skip to main content

​
Change Email

Changes the email address for an account.

​
Path Parameters

​
accountId
string (uuid)
required
Account identifier

​
Request Body

​
currentEmail
string
required
Current email address for verification
​
newEmail
string
required
New email address
​
password
string
required
Account password for verification

​
Response

​
token
string
New JWT token with updated email information

​
Response Codes

  • 200 OK - Email changed successfully
  • 400 Bad Request - Invalid email format or same as current email
  • 401 Unauthorized - Missing or invalid authentication token
  • 404 Not Found - Account not found or incorrect password

​
Examples

curl -X PATCH "https://your-server.com/api/account/3fa85f64-5717-4562-b3fc-2c963f66afa6/email" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "currentEmail": "[email protected]",
    "newEmail": "[email protected]",
    "password": "SecurePass123!"
  }'

​
Success Response

"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJlbWFpbCI6Im5ld0BleGFtcGxlLmNvbSJ9..."

​
Error Response Examples

Email Already in Use (400 Bad Request): 
"Email address is already registered to another account"
Incorrect Password (404 Not Found): 
"Current password is incorrect"

​
Change Password

Changes the password for an account.

​
Path Parameters

​
accountId
string (uuid)
required
Account identifier

​
Request Body

​
currentPassword
string
required
Current password for verification
​
newPassword
string
required
New password (must meet security requirements)

​
Response

  • 204 No Content - Password changed successfully

​
Response Codes

  • 204 No Content - Password changed successfully
  • 400 Bad Request - New password same as current or doesn’t meet requirements
  • 404 Not Found - Account not found or incorrect current password

​
Examples

curl -X PATCH "https://your-server.com/api/account/3fa85f64-5717-4562-b3fc-2c963f66afa6/password" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "currentPassword": "OldPass123!",
    "newPassword": "NewSecurePass456!"
  }'

​
Error Response Examples

Same Password (400 Bad Request): 
"New password must be different from current password"
Weak Password (400 Bad Request): 
"Password must be at least 8 characters and contain uppercase, lowercase, and numbers"
Incorrect Current Password (404 Not Found): 
"Current password is incorrect"

​
Security Best Practices

Always require the current password when changing email or password to prevent unauthorized changes.
After changing email, users receive a new JWT token with updated claims. The old token remains valid until expiration.

​
Password Requirements

Passwords should meet the following criteria:
  • Minimum 8 characters
  • At least one uppercase letter
  • At least one lowercase letter
  • At least one number
  • Special characters recommended

​
Email Change Flow

1

Verify Current Credentials

User provides current email and password
2

Validate New Email

System checks new email is valid and not already in use
3

Update Account

Email is updated in the database
4

Issue New Token

New JWT token is generated with updated email claim
5

Update Client

Client should replace the old token with the new one

​
Additional Notes

  • Email changes are immediate and don’t require verification (consider adding email verification in production)
  • Password changes take effect immediately
  • Users should be logged out from other sessions after password change for security
  • Both endpoints require valid authentication tokens
  • Account ID in the path must match the authenticated user’s account

Build docs developers (and LLMs) love

Get started for freeTalk to us