Merge pull request #2472 from Seltyk/dev

[docs] Clarify OAuth flow documentation

docs/source/login.rst

@@ -6,6 +6,10 @@ Augur implements the Oauth 2.0 specification, and each Augur instance is capable
 Prerequisites
 --------------
 
+If your Augur instance is running behind Nginx or Apache, make sure this parameter (or its Apache equivalent) is set in your ``sites-enabled`` configuration::
+
+    proxy_set_header X-Forwarded-Proto $scheme;
+
 Registering a user account on the desired Augur instance is a requirement for creating a Client Application. The developer of the application must follow the below steps:
 
 1. Navigate to the home page of the desired Augur instance.
@@ -18,10 +22,10 @@ Once you have registered an account, follow the below steps to create a new Clie
 2. Click "Profile".
 3. Click "Applications"
 4. In the create application form, fill out the application name and redirect URL
-    - The redirect URL is relative to the user-agent (IE: the user's browser), and **must** be accessible to the user-agent.
-    - If you are testing an application locally, you may use ``http://127.0.0.1/`` as the host for the redirect URL. The authorization server will *not* prevent redirection if the redirect url is unreachable.
+    - The redirect URL is relative to the user-agent (i.e. the user's browser), and **must** be accessible to the user-agent.
+    - If you are testing an application locally, you may use ``http://127.0.0.1/`` or ``http://localho.st`` as the host for the redirect URL. The authorization server will *not* prevent redirection if the redirect url is unreachable.
 
-Once the application has been created, note the Client ID and API Key, as you will need them for application authentication requests.
+Once the application has been created, note the Application ID and Client Secret, as you will need them for application authentication requests.
 
 Authorization Flow
 --------------------
@@ -34,7 +38,7 @@ Initial Request
 The authorization flow is initiated when a user clicks a link or button which redirects the user-agent (browser) to the authorization server. This request URL must be of the following format::
 
     https://augur.example.com/user/authorize?
-        client_id=[your app client ID]
+        client_id=[your application ID]
         &response_type="code"
         &state=[optional value that you define]
 
@@ -63,9 +67,9 @@ The Client Application must make the following request in order to facilitate th
     URL: https://augur.example.com/api/unstable/user/session/generate
     arguments:
         code: [the temporary authorization code]
-        grand_type: "code"
+        grant_type: "code"
     headers:
-        Authorization: Client [your app API Key]
+        Authorization: Client [your client secret]
 
 The authorization server will respond with the following on success:
 
@@ -97,9 +101,9 @@ The application may also attempt automatic reauthorization using the previously
     URL: https://augur.example.com/api/unstable/user/session/refresh
     arguments:
         refresh_token: [the previously provided refresh token]
-        grand_type: "refresh_token"
+        grant_type: "refresh_token"
     headers:
-        Authorization: Client [your app API Key]
+        Authorization: Client [your client secret]
 
 The authorization server will respond with the following on success:
 
@@ -120,8 +124,8 @@ See the rest API documentation for more specific details about these login endpo
 Making Authenticated Requests
 ------------------------------
 
-Once the User Session Token has been aqcuired, authenticated requests must be made using both the Client Application API Key and the Bearer Token. Authentication credentials must be provided in the ``Authorization`` header as such::
+Once the User Session Token has been acquired, authenticated requests must be made using both the Client Secret and the Bearer Token. Authentication credentials must be provided in the ``Authorization`` header as such::
 
-    Authorization: Client [API Key], Bearer [User Session Token]
+    Authorization: Client [Client Secret], Bearer [User Session Token]
 
-**Please note that both the Client API Key and the User Sesson Token must be included in the Authorization header for authenticated requests**
+**Please note that both the Client Secret and the User Sesson Token must be included in the Authorization header for authenticated requests**