---
title: "Changes a user's password."
method: POST
path: "/_matrix/client/v3/account/password"
tags: ["Account management"]
---

# Changes a user's password.

`POST /_matrix/client/v3/account/password`

## Request

- Base URL: `https://matrix.org`
- URL: `https://matrix.org/_matrix/client/v3/account/password`
- Auth: one of:
  - none
  - API key in query parameter `access_token`
  - HTTP bearer
- TypeScript: <https://skmtc.dev/matrix/apis/matrix-client-server-api/docs/_matrix/client/v3/account/password/post.ts> (a function with typed inputs; its response is checked against the schema)

Changes the password for an account on this homeserver.

This API endpoint uses the [User-Interactive Authentication API](https://spec.matrix.org/v1.19/client-server-api/#user-interactive-authentication-api) to
ensure the user changing the password is actually the owner of the
account.

An access token should be submitted to this endpoint if the client has
an active session.

The homeserver may change the flows available depending on whether a
valid access token is provided. The homeserver SHOULD NOT revoke the
access token provided in the request. Whether other access tokens for
the user are revoked depends on the request parameters.

This endpoint uses [capabilities negotiation](https://spec.matrix.org/v1.19/client-server-api/#capabilities-negotiation).
Clients SHOULD check the value of the [`m.change_password` capability](https://spec.matrix.org/v1.19/client-server-api/#mchange_password-capability)
to determine if this endpoint is available.

## Request body

- object
  - `auth` object: Used by clients to submit authentication information to the interactive-authentication API
    - `session` string: The value of the session key given by the homeserver.
    - `type` string: The authentication type that the client is attempting to complete. May be omitted if `session` is given, and the client is reissuing a request which it believes has been completed out-of-band (for example, via the [fallback mechanism](https://spec.matrix.org/v1.19/client-server-api/#fallback)).
  - `logout_devices` boolean: Whether the user's other access tokens, and their associated devices, should be revoked if the request succeeds. Defaults to `true`. When `false`, the server can still take advantage of the [soft logout method](https://spec.matrix.org/v1.19/client-server-api/#soft-logout) for the user's remaining devices.
  - `new_password` string, required: The new password for the account.

## Response `200`

The password has been changed.

- object

## Other responses

- `401`: The homeserver requires additional authentication information.
- `429`: This request was rate-limited.

---

[API](https://skmtc.dev/matrix/apis/matrix-client-server-api.md) - [All operations](https://skmtc.dev/matrix/apis/matrix-client-server-api/llms.txt) - [OpenAPI document](https://skmtc.dev/matrix/apis/matrix-client-server-api/revisions/c7fe4072c681?raw)