Swaggerify /account

2015-12-01 13:53:03 +00:00 · 2015-12-01 13:53:03 +00:00 · c6e0322a9e
commit c6e0322a9e
parent 79244e8065
2 changed files with 160 additions and 50 deletions
--- a/api/client-server/administrative_contact.yaml
+++ b/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."
+              }