Reformat text and subheaders

Author: Grace Yim

README.md

@@ -14,6 +14,9 @@ First off, to access the Toopher API you'll need to sign up for an account at th
 ### The Toopher Two-Step
 Interacting with the Toopher web service involves two steps: pairing, and authenticating.
 
+#### Step 0: Create an API Object
+Using your consumer key and consumer secret, create a ToopherApi object which will be used to generate an authentication or user management url and process the postback data.
+
 #### Step 1: Pair
 Before you can enhance your website's actions with Toopher, your customers will need to pair their phone's Toopher app with your website.  To do this, they generate a unique, nonsensical "pairing phrase" from within the app on their phone.  You will need to prompt them for a pairing phrase as part of the Toopher enrollment process.  Once you have a pairing phrase, just send it to the Toopher web service and we'll return a pairing ID that you can use whenever you want to authenticate an action for that user.
 
@@ -26,7 +29,7 @@ This library makes it super simple to do the Toopher two-step.  Check it out:
 ```python
 from toopher import *
 
-# Create an API Object Using Your Credentials
+# Step 0 - Create an API Object Using Your Credentials
 api = toopher.ToopherApi("<your consumer key>", "<your consumer secret>")
 
 # Step 1 - Pair with their phone's Toopher app
@@ -106,60 +109,58 @@ $ nosetests test
 ```
 
 #Using the Toopher IFRAME
-Toopher's IFRAME-based authentication flow is the simplest way for web developers to integrate Toopher Two-Factor Authentication into an application.
+Toopher's IFRAME-based flow is the simplest way for web developers to integrate Toopher Two-Factor Authentication into an application.
+
+### Toopher IFRAME Overview
+
+The IFRAME-based flow works by inserting an `<iframe>` element into the HTML displayed to the user after a successful username/password validation (but before they are actually logged-in to the service).  The IFRAME URL is generated by our library and its content is served from the Toopher API server.
 
-### Toopher IFRAME Authentication Overview
+The Authentication IFRAME guides the user through the process of pairing (if the user is not paired already) and authenticating with Toopher.  Once complete, the IFRAME will return the result of the authentication to your server by `POST`ing the response via HTML to an endpoint of your choice.  Your server validates the cryptographic signature using our library which determines whether or not the user successfully authenticated.
 
-The IFRAME-based authentication flow works by inserting an `<iframe>` element into the HTML displayed to the user after a successful username/password validation (but before they are actually logged-in to the service).  The IFRAME URL is generated by our library and its content is served from the Toopher API server.  The IFRAME guides the user through the process of pairing and authenticating with Toopher.  Once complete, the IFRAME will return the result of the authentication to your server by `POST`ing the response via HTML to an endpoint of your choice.  Your server validates the cryptographic signature using our library which determines whether or not the user successfully authenticated.
+The User Management IFRAME is available if you would like to manage users separately from the authentication process. Once complete, the IFRAME will return the result of the pairing to your server by POSTing the response via HTML to an endpoint of your choice. Your server validates the cryptographic signature using our library which determines whether or not the user successfully paired.
 
-Two distinct IFRAME flows are required:
+### HTML Markup
+There is no difference in the markup required for an authentication vs. a user management IFRAME request (the generated URL embeds all relevant information).
 
-* the *Pairing* request is used to pair a user account with a particular mobile device (this is typically a one-time process)
-* the *Authentication* request is used to authenticate a particular action on behalf of a user
+The IFRAME element must have an id of `toopher_iframe`. Pages that include the Toopher IFRAME must include the accompanying javascript library `toopher-web.js` (located in `/assets/js/` in this repository).  Toopher's IFRAME content is designed for a minimum size of 400x300 px.  In the example below, `{{IFRAME_REQUEST_URL}}` is the authentication or user management URL generated by the ToopherIframe library.  `{{POSTBACK_URL}}` is the path on your server where the Toopher-Iframe will submit the result of the authentication when it is finished.
+
+```html
+<!-- toopher-web.js requires jQuery.  uncomment the following line to source it from CDNJS if it is not already included in your page -->
+<!-- <script src="//cdnjs.cloudflare.com/ajax/libs/jquery/1.11.0/jquery.min.js"></script> -->
+<script src="/js/toopher-web.js"></script>
+<iframe id="toopher_iframe" src="{{IFRAME_REQUEST_URL}}" toopher_postback="{{POSTBACK_URL}}" style="display:inline-block; height:300px; width:100%;"></iframe>
+```
 
 ### Authentication IFRAME Workflow
 #### Primary Authentication
 We recommend using some form of primary authentication before initiating a Toopher authentication request.  Typical primary authentication methods involve verifying that the user has a valid username and password to access the resource being protected.
 
 #### Step 1: Embed a request in an IFRAME
-After verifying the user's primary authentication, but before Assuming the user's primary authentication checks out, the next step is to kickoff Toopher authentication.
+After verifying the user's primary authentication, but before assuming the user's primary authentication checks out, the next step is to kickoff Toopher authentication.
+
+1. Generate an authentication URL by specifying the request parameters to the library as detailed below
+2. Display a webpage to your user that embeds this URL within an `<iframe>` element.  The markup requirements for the IFRAME element are described in the "HTML Markup" section above.
 
-1. Generate a URL by specifying the request parameters to the library as detailed below
-2. Display a webpage to your user that embeds this URL within an `<iframe>` element.  The markup requirements for the IFRAME element are described in the "HTML Markup" section.
+#### Step 2: Validate the postback data
 
-#### Step 2a: Validate the result by processing the postback
+##### Option 1: Process the postback
 1. Toopher-IFRAME results posted back to server.
-2. Call `ToopherIframe.process_postback()` to verify that result is valid. `process_postback()` returns one of the following:
+2. Call `process_postback()` to verify that the result is valid. `process_postback()` returns one of the following:
   * an AuthenticationRequest object if the signature is valid (authentication url)
-  * a Pairing or User if the signature is valid (user management url)
-  * a `ToopherAPIError` or `SignatureValidationError` if the server encounters an error while processing postback
+  * a `UserDisabledError`, `SignatureValidationError` or `ToopherAPIError` if the server encounters an error while processing postback
 3. If no errors were returned, the result of the authentication can be checked by evaluating `not authentication_request.pending and authentication_request.granted`.
 
-#### Step 2b: Validate the result by checking the authentication request status
+##### Option 2: Check the authentication request status
 1. Toopher-IFRAME results posted back to server.
 2. Call `ToopherIframe.is_authentication_granted` to check if the authentication request was granted.
 
 
-### HTML Markup
-The IFRAME element must have an id of `toopher_iframe`.
+#### Examples
 
-Pages that include the Toopher IFRAME must include the accompanying javascript library `toopher-web.js` (located in `/assets/js/` in this repository).  Toopher's IFRAME content is designed for a minimum size of 400x300 px.  In the example below, `{{IFRAME_REQUEST_URL}}` is the Authentication or Pairing URL generated by the ToopherIframe library.  `{{POSTBACK_URL}}` is the path on your server where the Toopher-Iframe will submit the result of the authentication when it is finished.
+##### Generating an Authentication IFRAME URL
+Though it is not required, every Toopher Authentication session can include a unique `request_token` - a randomized string that is included in the signed request to the Toopher API and returned in the signed response from the Toopher IFRAME.  To guard against potential replay attacks, your code should validate that the returned `request_token` is the same one used to create the request.
 
-```html
-<!-- toopher-web.js requires jQuery.  uncomment the following line to source it from CDNJS if it is not already included in your page -->
-<!-- <script src="//cdnjs.cloudflare.com/ajax/libs/jquery/1.11.0/jquery.min.js"></script> -->
-<script src="/js/toopher-web.js"></script>
-<iframe id="toopher_iframe" src="{{IFRAME_REQUEST_URL}}" toopher_postback="{{POSTBACK_URL}}" style="display:inline-block; height:300px; width:100%;"></iframe>
-```
-
-There is no difference in the markup required for an authentication vs. a user management IFRAME request (the generated URL embeds all relevant information).
-
-### Examples
-
-#### Generating an Authentication IFRAME URL
-Every Toopher Authentication session should include a unique `request_token` - a randomized string that is included in the signed request to the Toopher API and returned in the signed response from the Toopher IFRAME.  To guard against potential replay attacks, your code should validate that the returned `request_token` is the same one used to create the request.
-
-Creating a random request token and storing it in the server-side session using Django:
+Here's an example of creating a random request token and storing it in the server-side session using Django:
 
 ```python
 import random, string
@@ -170,7 +171,7 @@ request.session['ToopherRequestToken'] = request_token
 The Toopher Authentication API provides the requester a rich set of controls over authentication parameters.
 
 ```python
-# optional parameters: reset_email, request_token, action_name, requester_metadata, automation_allowed, challenge_required, and ttl
+# Optional parameters: reset_email, request_token, action_name, requester_metadata, automation_allowed, challenge_required, and ttl
 auth_iframe_url = iframe_api.get_authentication_url(username, reset_email='email', request_token='token', action_name='action', requester_metadata, automation_allowed=automation_allowed, challenge_required=challenge_required, ttl=ttl);
 ```
 
@@ -180,16 +181,15 @@ For the simple case of authenticating a user at login, use `get_authentication_u
 login_iframe_url = iframe_api.get_authentication_url(username)
 ```
 
-#### Validating Postback Data from Authentication IFRAME & Parsing Errors
+##### Validating Postback Data from Authentication IFRAME & Parsing Errors
 In this example, `data` is a `dict` of the form data POSTed to your server from the Toopher Authentication IFRAME.  You should replace the commented blocks in the `except` with code appropriate for the condition described in the comment.
 
-There are two ways to validate postback data:
+There are two ways to validate postback data from an authentication IFRAME:
 
-#####Process Postback
+######Process Postback
 ```python
 try:
-    # Try to process the postback from the Toopher IFRAME
-    # and receive an AuthenticationRequest object.
+    # Try to process the postback from the Toopher IFRAME and receive an AuthenticationRequest object.
     authentication_request = iframe_api.process_postback(form_data)
 
     # If you got here, you just need to check the status of the authentication request.
@@ -206,37 +206,56 @@ except toopher.ToopherApiError as e:
     # The postback resource type was not valid.
 ```
 
-#####Check AuthenticationRequest Status
+######Check Authentication Request Status
 ```python
-# returns boolean indicating if user should be granted access
+# Returns boolean indicating if user should be granted access
 authentication_request_granted = iframe_api.is_authentication_granted(form_data)
 
 if authentication_request_granted:
     # Success!
 ```
 
-#### Generating a User Management IFRAME URL
+###User Management IFRAME Workflow
+#### Primary Authentication
+We recommend using some form of primary authentication before initiating a Toopher pairing.  Typical primary authentication methods involve verifying that the user has a valid username and password to access the resource being protected.
+
+#### Step 1: Embed a request in an IFRAME
+After verifying the user's primary authentication, the next step is to kickoff Toopher pairing.
+
+1. Generate a user management URL by specifying the request parameters to the library as detailed below
+2. Display a webpage to your user that embeds this URL within an `<iframe>` element.  The markup requirements for the IFRAME element are described in the "HTML Markup" section above.
+
+#### Step 2: Validate the postback data
+1. Toopher-IFRAME results posted back to server.
+2. Call `process_postback()` to verify that the result is valid. `process_postback()` returns one of the following:
+  * a Pairing or User object if the signature is valid (authentication url)
+  * a `UserDisabledError`, `SignatureValidationError` or `ToopherAPIError` if the server encounters an error while processing postback
+3. If no errors were returned and you received a Pairing object, the result of the pairing can be checked by evaluating `pairing.enabled`.
+
+#### Examples
+##### Generating a User Management IFRAME URL
 The Toopher Authentication API provides the requester a rich set of controls over user management parameters.
 
 ```python
-# optional parameter: reset_email
+# Optional parameter: reset_email
 pair_iframe_url = iframe_api.get_user_management_url(username, 'email')
 ```
 
-For the simple case of pairing a user, use `get_user_management_url` in this simple way:
+For the simple case of pairing a user, use `get_user_management_url()` in this simple way:
 
 ```python
 pair_iframe_url = iframe_api.get_user_management_url(username)
 ```
 
-#### Validating Postback Data from Pairing IFRAME & Parsing Errors
+##### Validating Postback Data from User Management IFRAME & Parsing Errors
 In this example, `data` is a `dict` of the form data POSTed to your server from the Toopher Pairing IFRAME.  You should replace the commented blocks in the `except` with code appropriate for the condition described in the comment.
 
-#####Process Postback
+There is one way to validate postback data from a user management IFRAME:
+
+######Process Postback
 ```python
 try:
-    # Try to process the postback from the Toopher IFRAME
-    # and receive a Pairing or User object.
+    # Try to process the postback from the Toopher IFRAME and receive a Pairing or User object.
     postback_object = iframe_api.process_postback(form_data)
 
     # If you got here and you have a pairing object, you just need to check the status of the pairing.