From 1d33adf62d8d56d1bfb88a0ff13da7e00fb0cc60 Mon Sep 17 00:00:00 2001
From: Travis Ralston <travpc@gmail.com>
Date: Sun, 26 May 2019 21:20:04 -0600
Subject: [PATCH] Add rationale for UIA on change password, and how access
 tokens behave

Fixes https://github.com/matrix-org/matrix-doc/issues/680
---
 api/client-server/registration.yaml                       | 8 ++++++--
 changelogs/client_server/newsfragments/2027.clarification | 1 +
 2 files changed, 7 insertions(+), 2 deletions(-)
 create mode 100644 changelogs/client_server/newsfragments/2027.clarification

diff --git a/api/client-server/registration.yaml b/api/client-server/registration.yaml
index e2d35d2c..3195ab41 100644
--- a/api/client-server/registration.yaml
+++ b/api/client-server/registration.yaml
@@ -326,13 +326,17 @@ paths:
       description: |-
         Changes the password for an account on this homeserver.
 
-        This API endpoint uses the `User-Interactive Authentication API`_.
+        This API endpoint uses the `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.
+        valid access token is provided. The homeserver SHOULD NOT revoke the
+        access token provided in the request, however all other access tokens
+        for the user should be revoked if the request succeeds.
       security:
         - accessToken: []
       operationId: changePassword
diff --git a/changelogs/client_server/newsfragments/2027.clarification b/changelogs/client_server/newsfragments/2027.clarification
new file mode 100644
index 00000000..db74ea56
--- /dev/null
+++ b/changelogs/client_server/newsfragments/2027.clarification
@@ -0,0 +1 @@
+Clarify why User Interactive Auth is used on password changes and how access tokens are handled.