Specify account suspension

content/client-server-api/_index.md

@@ -29,7 +29,7 @@ JSON object.  Clients should supply a `Content-Type` header of
 
 The exceptions are:
 
-- [`POST /_matrix/media/v3/upload`](#post_matrixmediav3upload) and 
+- [`POST /_matrix/media/v3/upload`](#post_matrixmediav3upload) and
   [`PUT /_matrix/media/v3/upload/{serverName}/{mediaId}`](#put_matrixmediav3uploadservernamemediaid),
   both of which take the uploaded media as the request body.
 - [`POST /_matrix/client/v3/logout`](#post_matrixclientv3logout) and
@@ -103,6 +103,10 @@ No access token was specified for the request.
 `M_USER_LOCKED`
 The account has been [locked](#account-locking) and cannot be used at this time.
 
+`M_USER_SUSPENDED`
+The account has been [suspended](#account-suspension) and can only be used for
+limited actions at this time.
+
 `M_BAD_JSON`
 Request contained valid JSON, but it was malformed in some way, e.g.
 missing required keys, invalid values for keys.
@@ -1471,7 +1475,7 @@ Content-Type: application/json
 ```
 
 Servers SHOULD NOT invalidate access tokens on locked accounts unless the
-client requests a logout (using the above endpoints). This ensures that 
+client requests a logout (using the above endpoints). This ensures that
 users can retain their sessions without having to log back in if the account
 becomes unlocked.
 
@@ -1485,6 +1489,72 @@ and other APIs to detect when the lock has been lifted.
 To enable users to appeal to a lock clients MAY use
 [server contact discovery](#getwell-knownmatrixsupport).
 
+#### Account suspension
+
+{{% added-in v="1.13" %}}
+
+Similar to [locking](#account-locking), a user's account MAY be suspended to
+prevent further activity from that account. A similar effect is achieved, though
+without risk of the client losing state from a logout. Suspensions are reversible,
+like locks and unlike deactivations.
+
+The actions a user can perform while suspended is deliberately left as an
+implementation detail. Servers SHOULD permit the user to perform at least the
+following, however:
+
+* Log in and create additional sessions (which are also suspended).
+* See and receive messages, particularly through [`/sync`](#get_matrixclientv3sync)
+  and [`/messages`](#get_matrixclientv3roomsroomidmessages).
+* [Verify other devices](#device-verification) and write associated
+  [cross-signing data](#cross-signing).
+* [Populate their key backup](#server-side-key-backups).
+* Leave rooms and reject invites.
+* Redacting their own events.
+* Log out or delete any device of theirs, including the current session.
+* Deactivate their account, potentially with a time delay to discourage making
+  a new account right away.
+* Change or add [admin contacts](#adding-account-administrative-contact-information),
+  but not remove. Servers are recommended to only permit this if they keep a
+  changelog on contact information to prevent misuse.
+
+General purpose endpoints like [`/send/{eventType}`](#put_matrixclientv3roomsroomidsendeventtypetxnid)
+MAY return the error described below depending on the path parameters. For example,
+a user may be allowed to send `m.room.redaction` events but not `m.room.message`
+events through `/send`.
+
+Where a room is used to maintain communication between server administration
+teams and the suspended user, servers are recommended to allow the user to send
+events to that room specifically. Server administrators which do not want the
+user to continue receiving messages may be interested in [account locking](#account-locking)
+instead.
+
+Otherwise, the recommended set of explicitly forbidden actions is:
+
+* Joining or knocking on rooms.
+* Accepting or sending invites.
+* Sending messages to rooms.
+* Changing profile data (display name and avatar, primarily).
+* Redacting other users' events, when permission is possible in a room.
+
+When a client attempts to perform an action while suspended, the server MUST
+respond with a `403 Forbidden` error response with `M_USER_SUSPENDED` as the
+error code, as shown below:
+
+```
+HTTP/1.1 403 Forbidden
+Content-Type: application/json
+```
+
+```json
+{
+  "errcode": "M_USER_SUSPENDED",
+  "error": "You cannot perform this action while suspended."
+}
+```
+
+APIs for initiating suspension or unsuspension are not included in this version
+of the specification, and left as an implementation detail.
+
 ### Adding Account Administrative Contact Information
 
 A homeserver may keep some contact information for administrative use.