Clarify guest accounts and auth usage on /register

Fixes #1980 Fixes #1984
matrix-org · May 30, 2019 · 2ed37f5 · 2ed37f5
1 parent 41a036a
commit 2ed37f5
Show file tree

Hide file tree

Showing 2 changed files with 26 additions and 9 deletions.
diff --git a/api/client-server/registration.yaml b/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,21 +78,19 @@ 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:
             type: object
             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:

diff --git a/changelogs/client_server/newsfragments/2055.clarification b/changelogs/client_server/newsfragments/2055.clarification
@@ -0,0 +1 @@
+Clarify which parameters apply in what scenarios on ``/register``.
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		Clarify which parameters apply in what scenarios on ``/register``.