From 923afd71d4bf1c0854deae96d3af7fd6d268646e Mon Sep 17 00:00:00 2001
From: David Lawrence <dkl@mozilla.com>
Date: Thu, 24 Sep 2015 14:47:18 +0000
Subject: Bug 1204683: Add whoami endpoint

---
 docs/en/rst/api/core/v1/user.rst            | 35 +++++++++++++++++++++++++++++
 docs/en/rst/integrating/auth-delegation.rst |  6 ++---
 2 files changed, 38 insertions(+), 3 deletions(-)

(limited to 'docs/en')

diff --git a/docs/en/rst/api/core/v1/user.rst b/docs/en/rst/api/core/v1/user.rst
index e27211a7f..7f835cc8a 100644
--- a/docs/en/rst/api/core/v1/user.rst
+++ b/docs/en/rst/api/core/v1/user.rst
@@ -378,3 +378,38 @@ and not in 'editusers' group, you will only be returned the ``id``, ``name``,
 returned are filtered based on your permission to bless each group. The
 ``saved_searches`` and ``saved_reports`` items are only returned if you are
 querying your own account, even if you are in the editusers group.
+
+.. _rest_user_whoami:
+
+Who Am I
+--------
+
+Allows for validating a user's API key, token, or username and password.
+If sucessfully authenticated, it returns simple information about the
+logged in user.
+
+**Request**
+
+.. code-block:: text
+
+   GET /rest/whoami
+
+**Response**
+
+.. code-block:: js
+
+   {
+     "id" : "1234",
+     "name" : "user@bugzulla.org",
+     "real_name" : "Test User",
+   }
+
+========== ======  =====================================================
+name       type    description
+========== ======  =====================================================
+id         int     The unique integer ID that Bugzilla uses to represent
+                   this user. Even if the user's login name changes,
+                   this will not change.
+real_name  string  The actual name of the user. May be blank.
+name       string  string  The login name of the user.
+========== ======  =====================================================
diff --git a/docs/en/rst/integrating/auth-delegation.rst b/docs/en/rst/integrating/auth-delegation.rst
index 403f01e2f..bff460e4a 100644
--- a/docs/en/rst/integrating/auth-delegation.rst
+++ b/docs/en/rst/integrating/auth-delegation.rst
@@ -12,9 +12,9 @@ Authentication Flow
 
 The authentication process begins by directing the user to th the Bugzilla site's auth.cgi.
 For the sake of this example, our application's URL is `http://app.example.org`
-and the Bugzilla site is `http://bugs.example.org`.
+and the Bugzilla site is `http://bugzilla.mozilla.org`.
 
-1. Provide a link or redirect the user to `http://bugs.example.org/auth.cgi?callback=http://app.example.org/callback&description=app%description`
+1. Provide a link or redirect the user to `http://bugzilla.mozilla.org/auth.cgi?callback=http://app.example.org/callback&description=app%description`
 2. Assuming the user is agreeable, the following will happen:
   1. Bugzilla will issue a POST request to `http://app.example.org/callback`
      with a the request body data being a JSON object with keys `client_api_key` and `client_api_login`.
@@ -24,7 +24,7 @@ and the Bugzilla site is `http://bugs.example.org`.
      with additional query string parameters `client_api_login` and `callback_result`.
   4. At this point, the consumer now has the api key and login information. Be sure to compare the `callback_result` to whatever result was initially sent back
      to Bugzilla.
-3. Finally, you should check that the API key and login are valid, using the :ref:`rest_user_valid_login` REST
+3. Finally, you should check that the API key and login are valid, using the :ref:`rest_user_whoami` REST
    resource.
 
 Your application should take measures to ensure when receiving a user at your
-- 
cgit v1.2.3-24-g4f1b