Clarify guest accounts and `auth` usage on /register

Fixes https://github.com/matrix-org/matrix-doc/issues/1980
Fixes https://github.com/matrix-org/matrix-doc/issues/1984

api/client-server/registration.yaml

@@ -29,7 +29,8 @@ paths:
     post:
       summary: Register for an account on this homeserver.
       description: |-
-        This API endpoint uses the `User-Interactive Authentication API`_.
+        This API endpoint uses the `User-Interactive Authentication API`_, except in
+        the cases where a guest account is being registered.
 
         Register for an account on this homeserver.
 
@@ -59,6 +60,11 @@ paths:
         supplied by the client or generated by the server. The server may
         invalidate any access token previously associated with that device. See
         `Relationship between access tokens and devices`_.
+
+        When registering a guest account, all parameters in the request body
+        with the exception of ``initial_device_display_name`` are ignored by
+        the server. The server will pick a ``device_id`` for the account
+        regardless of input.
       operationId: register
       parameters:
         - in: query
@@ -72,7 +78,7 @@ paths:
           enum:
             - guest
             - user
-          description: The kind of account to register. Defaults to `user`.
+          description: The kind of account to register. Defaults to ``user``.
         - in: body
           name: body
           schema:
@@ -80,13 +86,11 @@ paths:
             properties:
               auth:
                 description: |-
-                    Additional authentication information for the
-                    user-interactive authentication API. Note that this
-                    information is *not* used to define how the registered user
-                    should be authenticated, but is instead used to
-                    authenticate the ``register`` call itself. It should be
-                    left empty, or omitted, unless an earlier call returned an
-                    response with status code 401.
+                  Additional authentication information for the
+                  user-interactive authentication API. Note that this
+                  information is *not* used to define how the registered user
+                  should be authenticated, but is instead used to
+                  authenticate the ``register`` call itself.
                 "$ref": "definitions/auth_data.yaml"
               bind_email:
                 type: boolean
@@ -194,6 +198,18 @@ paths:
             The homeserver requires additional authentication information.
           schema:
             "$ref": "definitions/auth_response.yaml"
+        403:
+          description: |-
+            The homeserver does not permit registering the account. This response
+            can be used to identify that a particular ``kind`` of account is not
+            allowed, or that registration is generally not supported by the homeserver.
+          examples:
+            application/json: {
+                "errcode": "M_FORBIDDEN",
+                "error": "Registration is disabled"
+            }
+          schema:
+            "$ref": "definitions/errors/error.yaml"
         429:
           description: This request was rate-limited.
           schema:

changelogs/client_server/newsfragments/2055.clarification

@@ -0,0 +1 @@
+Clarify which parameters apply in what scenarios on ``/register``.