Change User Email

POST /api/users/:id/email-change

An organization admin can change the sign-in email of a member of their own organization, a global admin of any user. The address does not change right away: a confirmation link is mailed to the new address, valid for 24 hours, and the change takes effect once it is opened. Until then the user keeps signing in with the current address. Opening the link signs nobody in. Once the change is confirmed, the old address receives a notice naming the new address and who requested it.

A new request replaces an earlier one that is still open, so only the latest link works.

API tokens cannot call this endpoint. It requires a real, logged-in user session. If the calling admin has two-step verification, they confirm their second factor first (403 mfa_step_up_required: enter the code in the dashboard dialog, then repeat the request).

Your own address is changed in your profile instead, which asks for your password.

Request BodyCopy Anchor Link

Example (cURL)Copy Anchor Link

Call this endpoint from an authenticated browser session (the admin's own login session cookie), not with an API token:

BASE_URL="https://uptimeify.io"

curl -X POST "$BASE_URL/api/users/user_123/email-change" \
  -H "Cookie: better-auth.session_token=<your-session-cookie>" \
  -H "Content-Type: application/json" \
  -d '{"newEmail": "jane.doe@example.com"}'

ResponseCopy Anchor Link

{ "ok": true, "pendingEmail": "jane.doe@example.com" }

Common errorsCopy Anchor Link

• 401 unauthorized when you are not authenticated
• 403 nonUserSessionForbidden when called with an API token or agent access token
• 403 mfa_step_up_required when your account has two-step verification and you have not confirmed it in the last five minutes
• 403 forbidden when you are not an organization admin or global admin
• 403 globalUserProtected when the target is a platform account (global admin or supporter) and you are not a global admin
• 404 userNotFound when the user does not exist or belongs to another organization
• 400 userSelfChangeForbidden when :id is your own user; change your address in your profile
• 400 emailUnchanged when the new address is the current one
• 400 emailAlreadyExists when another member of your organization already uses the address. An address held by an account outside your organization is not named: the request answers like a free one and no link is sent
• 502 emailSendFailed when the confirmation link could not be sent; the address is unchanged