Skip to main content
Change Password
Changes the password for the currently authenticated user. The user must provide their current password for verification. Requires a valid access token in the Authorization header.
This endpoint is only available to users who signed up with email and password. OAuth-only users who have no password will receive a 400 error.

What a password change ends

A password change is what someone reaches for when they think their account has been taken, so it ends sessions rather than only rotating a secret. In one transaction, the server:
  • writes the new password;
  • deletes every push binding this user holds, on every device, so notification content stops routing to a device an intruder may hold — except the device named by the optional pushDevice field below. Projects without the push bundle skip this step and are otherwise unaffected;
  • destroys every refresh-token family for this user except the caller’s own.
Either all three land or none does.
The caller’s own session survives, and nothing has to be sent for that. The access token this route is authenticated by carries the id of the session it was minted from, so the server can tell which of the user’s sessions is asking. The user stays signed in where they are standing; every other device must sign in again with the new password.A service or master key is not a session, so a call made with one has nothing to spare and ends every session for the user.
Name your device or it stops notifying. Nothing re-binds a device to push from its live session — repair happens on a cold start, an account switch or a token rotation, which on a resident mobile app can be days away. So a client that does not send pushDevice keeps its session but loses its notifications until one of those happens.
Existing access tokens are not revoked by this: an access token minted before the change keeps working until it expires, up to 30 minutes. It is the refresh families that go, so no other device can mint a new one.

Body Parameters

string
required
The user’s current password.
string
required
The new password. Must be different from the current password.
object
The physical device making the call, so its push binding survives while every other device this user is bound to loses theirs.The same shape Register Device and Sign Out take: { platform: "ios" | "android", token } for native, { platform: "web", subscription } for Web Push. It only ever spares a binding belonging to this user, so it cannot keep another account’s binding alive on a shared device.Omit it and every binding for the user is deleted, this device’s included.
string
The acting user. Service/master keys only — an end-user token infers it from the access token and may not name a different user.

Response

boolean
true on success.
string
Confirmation message: "Password updated successfully."

Error Responses

Returned when a required field is missing, when newPassword fails the password rules, when newPassword equals password, or when pushDevice is malformed — for example platform: "ios" with no token.
Returned when a service/master key calls this route without naming a userId.
Returned when an end-user token names a userId other than its own.
Nothing was committed — the password, the sessions and the push bindings are all as they were.
Rate limit: 5 requests per 5 minutes per IP. Exceeding it returns 429 with the plain-text message Too many attempts to change password, please wait 5 minutes and no code.

See Also