Merge pull request #395 from matrix-org/rav/kill_refresh_tokens

Remove references to refresh tokens and tokenrefresh

api/client-server/definitions/security.yaml

@@ -13,6 +13,6 @@
 # limitations under the License.
 accessToken:
   type: apiKey
-  description: The access_token returned by a call to ``/login`` or ``/tokenrefresh``
+  description: The access_token returned by a call to ``/login`` or ``/register``
   name: access_token
   in: query

api/client-server/login.yaml

@@ -90,15 +90,6 @@ paths:
                 description: |-
                   An access token for the account.
                   This access token can then be used to authorize other requests.
-                  The access token may expire at some point, and if so, it SHOULD come with a ``refresh_token``.
-                  There is no specific error message to indicate that a request has failed because
-                  an access token has expired; instead, if a client has reason to believe its
-                  access token is valid, and it receives an auth error, they should attempt to
-                  refresh for a new token on failure, and retry the request with the new token.
-              refresh_token:
-                type: string
-                description: |-
-                  Optional. A ``refresh_token`` may be exchanged for a new ``access_token`` using the |/tokenrefresh|_ API endpoint.
               home_server:
                 type: string
                 description: The hostname of the homeserver on which the account has been registered.
@@ -123,67 +114,3 @@ paths:
             "$ref": "definitions/error.yaml"
       tags:
         - Session management
-  "/tokenrefresh":
-    post:
-      summary: Exchanges a refresh token for an access token.
-      description: |-
-        Exchanges a refresh token for a new access token.
-        This is intended to be used if the access token has expired.
-
-        The server MUST invalidate the supplied ``refresh_token`` if the
-        request is successful. It MUST also invalidate the ``access_token``
-        which was issued at the same time as the ``refresh_token``, if it
-        has not already expired.
-      security:
-        - accessToken: []
-      parameters:
-        - in: body
-          name: body
-          schema:
-            type: object
-            example: |-
-              {
-                "refresh_token": "a1b2c3"
-              }
-            properties:
-              refresh_token:
-                type: string
-                description: The refresh token which was issued by the server.
-            required: ["refresh_token"]
-      responses:
-        200:
-          description: |-
-            The refresh token was accepted, and a new access token has been issued.
-            The passed refresh token is no longer valid and cannot be used.
-            A new refresh token will have been returned unless some policy does
-            not allow the user to continue to renew their session.
-          examples:
-            application/json: |-
-              {
-                "access_token": "bearwithme123",
-                "refresh_token": "exchangewithme987"
-              }
-          schema:
-            type: object
-            properties:
-              access_token:
-                type: string
-                description: |-
-                  An access token for the account.
-                  This access token can then be used to authorize other requests.
-                  The access token may expire at some point, and if so, it SHOULD come with a ``refresh_token``.
-              refresh_token:
-                type: string
-                description: Optional. A new ``refresh_token`` which may be exchanged for another new ``access_token``.
-        403:
-          description: |-
-            The exchange attempt failed. For example, the refresh token may have already been used.
-          examples:
-            application/json: |-
-              {"errcode": "M_FORBIDDEN"}
-        429:
-          description: This request was rate-limited.
-          schema:
-            "$ref": "definitions/error.yaml"
-      tags:
-        - Session management

api/client-server/registration.yaml

@@ -39,6 +39,9 @@ paths:
 
         - `guest` accounts. These accounts may have limited permissions and may not be supported by all servers.
 
+        If registration is successful, this endpoint will issue an access token
+        the client can use to authorize itself in subsequent requests.
+
       parameters:
         - in: query
           name: kind
@@ -90,8 +93,7 @@ paths:
               {
                 "user_id": "@cheeky_monkey:matrix.org",
                 "access_token": "abc123",
-                "home_server": "matrix.org",
-                "refresh_token": "def456"
+                "home_server": "matrix.org"
               }
           schema:
             type: object
@@ -104,16 +106,6 @@ paths:
                 description: |-
                   An access token for the account.
                   This access token can then be used to authorize other requests.
-                  The access token may expire at some point, and if so, it SHOULD come with a ``refresh_token``.
-                  There is no specific error message to indicate that a request has failed because
-                  an access token has expired; instead, if a client has reason to believe its
-                  access token is valid, and it receives an auth error, they should attempt to
-                  refresh for a new token on failure, and retry the request with the new token.
-              refresh_token:
-                type: string
-                # TODO: Work out how to linkify /tokenrefresh
-                description: |-
-                  (optional) A ``refresh_token`` may be exchanged for a new ``access_token`` using the /tokenrefresh API endpoint.
               home_server:
                 type: string
                 description: The hostname of the homeserver on which the account has been registered.