Merge pull request #190 from matrix-org/daniel/swaggeradmin

Swaggerify /account

api/client-server/administrative_contact.yaml

@@ -0,0 +1,157 @@
+swagger: '2.0'
+info:
+  title: "Matrix Client-Server v1 Account Administrative Contact API"
+  version: "1.0.0"
+host: localhost:8008
+schemes:
+  - https
+  - http
+basePath: /_matrix/client/v2_alpha
+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:
+  "/account/password":
+    post:
+      summary: Changes a user's password.
+      description: |-
+        This API endpoint uses the User-Interactive Authentication API.
+        An access token should be submitted to this endpoint if the client has
+        an active session.
+        The Home Server may change the flows available depending on whether a
+        valid access token is provided.
+      security:
+        - accessToken: []
+      parameters:
+        - in: body
+          name: body
+          schema:
+            type: object
+            example: |-
+              {
+                "new_password": "ihatebananas"
+              }
+            properties:
+              new_password:
+                type: string
+                description: The new password for the account.
+            required: ["new_password"]
+      responses:
+        200:
+          description: The password has been changed.
+          examples:
+            application/json: "{}"
+          schema:
+            type: object
+        429:
+          description: This request was rate-limited.
+          schema:
+            "$ref": "definitions/error.yaml"
+  "/account/3pid":
+    get:
+      summary: Gets a list of a user's third party identifiers.
+      description: |-
+        Gets a list of the third party identifiers that the homeserver has
+        associated with the user's account.
+
+        This is *not* the same as the list of third party identifiers bound to
+        the user's Matrix ID in Identity Servers.
+
+        Identifiers in this list may be used by the Home Server as, for example,
+        identifiers that it will accept to reset the user's account password.
+      security:
+        - accessToken: []
+      responses:
+        200:
+          description: The lookup was successful.
+          examples:
+            application/json: |-
+              {
+                "threepids": [
+                  {
+                    "medium": "email",
+                    "address": "monkey@banana.island"
+                  }
+                ]
+              }
+          schema:
+            type: object
+            properties:
+              threepids:
+                type: array
+                items:
+                  type: object
+                  title: Third party identifier
+                  properties:
+                    medium:
+                      type: string
+                      description: The medium of the third party identifier.
+                      enum: ["email"]
+                    address:
+                      type: string
+                      description: The third party identifier address.
+    post:
+      summary: Adds contact information to the user's account.
+      description: Adds contact information to the user's account.
+      security:
+        - accessToken: []
+      parameters:
+        - in: body
+          name: body
+          schema:
+            type: object
+            properties:
+              threePidCreds:
+                title: "ThreePidCredentials"
+                type: object
+                description: The third party credentials to associate with the account.
+                properties:
+                  client_secret:
+                    type: string
+                    description: The client secret used in the session with the Identity Server.
+                  id_server:
+                    type: string
+                    description: The Identity Server to use.
+                  sid:
+                    type: string
+                    description: The session identifier given by the Identity Server.
+                required: ["client_secret", "id_server", "sid"]
+              bind:
+                type: boolean
+                description: |-
+                  Whether the home server should also bind this third party
+                  identifier to the account's Matrix ID with the passed identity
+                  server. Default: ``false``.
+                x-example: true
+            required: ["threePidCreds"]
+            example: |-
+              {
+                "threePidCreds": {
+                  "id_server": "matrix.org",
+                  "sid": "abc123987",
+                  "client_secret": "d0n'tT3ll"
+                },
+                "bind": false
+              }
+      responses:
+        200:
+          description: The addition was successful.
+          examples:
+            application/json: "{}"
+            schema:
+              type: object
+        403:
+          description: The credentials could not be verified with the identity server.
+          examples:
+            application/json: |-
+              {
+                "errcode": "M_THREEPID_AUTH_FAILED",
+                "error": "The third party credentials could not be verified by the identity server."
+              }

specification/client_server_api.rst

@@ -510,58 +510,11 @@ database.
 
 Adding Account Administrative Contact Information
 +++++++++++++++++++++++++++++++++++++++++++++++++
-Request::
-
-  POST $V2PREFIX/account/3pid
-
-Used to add contact information to the user's account.
-
-The body of the POST request is a JSON object containing:
-
-threePidCreds
-  An object containing contact information.
-bind
-  Optional. A boolean indicating whether the Home Server should also bind this
-  third party identifier to the account's matrix ID with the Identity Server. If
-  supplied and true, the Home Server must bind the 3pid accordingly.
-
-The contact information object comprises:
-
-id_server
-  The colon-separated hostname and port of the Identity Server used to
-  authenticate the third party identifier. If the port is the default, it and the
-  colon should be omitted.
-sid
-  The session ID given by the Identity Server
-client_secret
-  The client secret used in the session with the Identity Server.
-
-On success, the empty JSON object is returned.
-
-May also return error codes:
-
-M_THREEPID_AUTH_FAILED
-  If the credentials provided could not be verified with the ID Server.
-
-Fetching Currently Associated Contact Information
-+++++++++++++++++++++++++++++++++++++++++++++++++
-Request::
-
-  GET $V2PREFIX/account/3pid
-
-This returns a list of third party identifiers that the Home Server has
-associated with the user's account. This is *not* the same as the list of third
-party identifiers bound to the user's Matrix ID in Identity Servers. Identifiers
-in this list may be used by the Home Server as, for example, identifiers that it
-will accept to reset the user's account password.
 
-Returns a JSON object with the key ``threepids`` whose contents is an array of
-objects with the following keys:
+A homeserver may keep some contact information for administrative use.
+This is independent of any information kept by any Identity Servers.
 
-medium
-  The medium of the 3pid (eg, ``email``)
-address
-  The textual address of the 3pid, eg. the email address
+{{administrative_contact_http_api}}
 
 Pagination
 ----------