Merge branch 'master' into macaroons

Conflicts:
	specification/10_client_server_api.rst

api/client-server/v1/login.yaml

@@ -0,0 +1,79 @@
+swagger: '2.0'
+info:
+  title: "Matrix Client-Server v1 Registration and Login API"
+  version: "1.0.0"
+host: localhost:8008
+schemes:
+  - https
+  - http
+basePath: /_matrix/client/api/v1
+consumes:
+  - application/json
+produces:
+  - application/json
+securityDefinitions:
+  accessToken:
+    type: apiKey
+    description: The user_id or application service access_token
+    name: access_token
+    in: query
+paths:
+  "/login":
+    post:
+      summary: Authenticates the user.
+      description: |-
+        Authenticates the user by password, and issues an access token they can
+        use to authorize themself in subsequent requests.
+      security:
+        - accessToken: []
+      parameters:
+        - in: body
+          name: body
+          required: true
+          schema:
+            type: object
+            example: |-
+              {
+                "username": "cheeky_monkey",
+                "password": "ilovebananas"
+              }
+            properties:
+              username:
+                type: string
+                description: The fully qualified user ID or just local part of the user ID, to log in.
+              password:
+                type: string
+                description: The user's password.
+            required: ["username", "password"]
+      responses:
+        200:
+          description: The user has been authenticated.
+          examples:
+            application/json: |-
+              {
+                "user_id": "@cheeky_monkey:matrix.org",
+                "access_token": "abc123",
+                "home_server": "matrix.org"
+              }
+          schema:
+            type: object
+            properties:
+              user_id:
+                type: string
+                description: The fully-qualified Matrix ID that has been registered.
+              access_token:
+                type: string
+                description: An access token for the account. This access token can then be used to authorize other requests.
+              home_server:
+                type: string
+                description: The hostname of the Home Server on which the account has been registered.
+        403:
+          description: |-
+            The login attempt failed. For example, the password may have been incorrect.
+          examples:
+            application/json: |-
+              {"errcode": "M_FORBIDDEN"}
+        429:
+          description: This request was rate-limited.
+          schema:
+            "$ref": "definitions/error.yaml"

scripts/gendoc.py

@@ -8,6 +8,8 @@ import shutil
 import subprocess
 import sys
 
+os.chdir(os.path.dirname(__file__))
+
 stylesheets = {
     "stylesheet_path": ["basic.css", "nature.css"]
 }

specification/10_client_server_api.rst

@@ -1011,60 +1011,7 @@ was registered whilst the client was performing authentication.
 
 Old V1 API docs: |register|_
 
-Login
-~~~~~
-This section refers to API Version 1.
-
-API docs: |login|_
-
-Obtaining an access token for an existing user account is done using the
-request::
-
-  POST $PREFIX/login
-
-The body of the POST request is a JSON object containing:
-
-username
-  The full qualified or local part of the Matrix ID to log in with.
-password
-  The password for the account.
-
-On success, this returns a JSON object with keys:
-
-user_id
-  The fully-qualified Matrix ID that has been registered.
-access_token
-  An access token for the account. This token may expire at some point, and if
-  so, it MAY come with a refresh_token, described below.
-refresh_token (optional)
-  A refresh token may be exchanged for a new access_token as described in
-  `Refreshing access tokens`.
-home_server
-  The hostname of the Home Server on which the account has been registered.
-
-Refreshing access tokens
-~~~~~~~~~~~~~~~~~~~~~~~~
-Exchanging a refresh token for an access token is done using the request::
-
-  POST $PREFIX/tokenrefresh
-
-The body of the POST request is a JSON object containing:
-
-refresh_token
-  The refresh token.
-
-On success, this invalidates the refresh token, so that it cannot be used again,
-and returns a JSON object with keys:
-
-access_token
-  An access token for the account, as is returned from login.
-refresh_token (optional)
-  A refresh token, as is returned from login.
-
-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.
+{{login_http_api}}
 
 Changing Password
 ~~~~~~~~~~~~~~~~~

templating/matrix_templates/sections.py

@@ -96,6 +96,12 @@ class MatrixSections(Sections):
             title_kind="~"
         )
 
+    def render_login_http_api(self):
+        return self._render_http_api_group(
+            "login",
+            title_kind="~"
+        )
+
     def render_room_events(self):
         def filterFn(eventType):
             return (