From 2e4e5e25e81d306be67a0d9bb736a504588ed775 Mon Sep 17 00:00:00 2001
From: Travis Ralston <travpc@gmail.com>
Date: Tue, 6 Mar 2018 13:41:53 -0700
Subject: [PATCH] Improve documentation around /account/whoami

Clarifies: https://github.com/matrix-org/matrix-doc/issues/1135

Signed-off-by: Travis Ralston <travpc@gmail.com>
---
 api/client-server/whoami.yaml | 36 ++++++++++++++++++++++++++++++++---
 1 file changed, 33 insertions(+), 3 deletions(-)

diff --git a/api/client-server/whoami.yaml b/api/client-server/whoami.yaml
index e3262fe4..6bf4f1fb 100644
--- a/api/client-server/whoami.yaml
+++ b/api/client-server/whoami.yaml
@@ -29,7 +29,13 @@ paths:
     get:
       summary: Gets information about the owner of an access token.
       description: |-
-        Gets information about the owner of a given access token.
+        Gets information about the owner of a given access token. 
+        
+        If the owner of the access token is an application service, 
+        the server should return the user ID making the request. The
+        server should respect the application service client/server API
+        extensions during this request. If the request is made for a 
+        virtual user, the server should verify that it is registered.
       operationId: getTokenOwner
       security:
         - accessToken: []
@@ -40,8 +46,8 @@ paths:
             The token belongs to a known user.
           examples:
             application/json: {
-                "user_id": "@joe:example.org"
-              }
+              "user_id": "@joe:example.org"
+            }
           schema:
             type: object
             required: ["user_id"]
@@ -49,5 +55,29 @@ paths:
               user_id:
                 type: string
                 description: The user id that owns the access token.
+        401:
+          description:
+            The token is not recongized
+          examples:
+            application/json: {
+              "errcode": "M_UNKNOWN_TOKEN",
+              "error": "Unrecongised access token."
+            }
+          schema:
+            "$ref": "definitions/error.yaml"
+        403:
+          description:
+            The appservice cannot masquerade the user or has not registered them.
+          examples:
+            application/json: {
+              "errcode": "M_FORBIDDEN",
+              "error": "Application service has not registered this user."
+            }
+          schema:
+            "$ref": "definitions/error.yaml"
+        429:
+          description: This request was rate-limited.
+          schema:
+            "$ref": "definitions/error.yaml"
       tags:
         - User data