applied changes requested by wsmith

Author: hzoppetti

openapi.yaml

@@ -49,9 +49,9 @@ info:
     ## OAuth
     If all you need is a Personal Access Token, feel free to skip ahead to the next section.
 
-    For more help on OAuth see our guide on [How to Create an OAuth App with teh Linode Python API Library](https://www.linode.com/docs/platform/api/how-to-create-an-oauth-app-with-the-linode-python-api-library/#oauth-2-authentication-exchange).
+    For more help on OAuth see our guide on [How to Create an OAuth App with the Linode Python API Library](https://www.linode.com/docs/platform/api/how-to-create-an-oauth-app-with-the-linode-python-api-library/#oauth-2-authentication-exchange).
 
-    Before you begin, you need to [Create an OAuth Client](https://developers.linode.com/api/v4/account-oauth-clients/#post).
+    Before you begin, you need to creat an OAuth client. You can do this [with the API](https://developers.linode.com/api/v4/account-oauth-clients/#post) or [via the Cloud Manager](https://cloud.linode.com/profile/clients).
 
       - For this you will pass a `label` and a `redirect_uri`.
       - The return from this endpoint will give you a `client_id` and a `secret`.
@@ -67,8 +67,10 @@ info:
     | 3.  The user logs into the authorization server with their username and password. | 3.  The user logs into the authorization server with their username and password. |
     | 4.  The authorization server redirects the user to the specificed redirect URL with a temporary authorization `code` (exchange code) in the URL. | 4.  The authorization server redirects the user back to your applaction with an OAuth token in the URL hash. This is temporary and expires in 2 hours without a `refresh_token`. |
     | 5.  The application issues a POST request (*see below*) to the authentication server with the exchange code, `client_id`, and the client application's `client_secret`. In return, the server returns an OAuth token and `refresh_token`. |  |
-    | 6.  The authentication server responds to the client application with a new OAuth `access_token`. `access_token` is set to expire in 2 hours if not refreshed. |  |
-    | 7.  The refresh token can be used to get a new OAuth `access_token` for another 2 hours by contacting the authentication server again with the `client_id`, `client_secret`, and `refresh_token`. | |
+    | 6.  The authentication server responds to the client application with a new OAuth `access_token`. `access_token` is set to expire in 2 hours. |  |
+    | 7.  The `refresh_token` can be used to get a new OAuth `access_token`, good for another 2 hours, and a new `refresh_token`, which you can use to extend the session again by this same method, by contacting the authentication server again with the `client_id`, `client_secret`, and `refresh_token`. | |
+
+      The following is more information for the private workflow expanding on step 5 and beyond.
 
       Once the User has logged into Linode and you have received an exchange code,
       you will need to trade that exchange code for an Authorization token. You
@@ -81,11 +83,11 @@ info:
       Make this request as `application/x-www-form-urlencoded` or as
       `multipart/form-data` and include the following parameters in the POST body:
 
-      | PARAMETER | DESCRIPTION | FIND OR UPDATE THIS INFORMATION |
-      |-----------|-------------|---------------------------------|
-      | client_id | Your app's client ID. | [List your OAuth Clients](https://developers.linode.com/api/v4/account-oauth-clients). |
-      | client_secret | Your app's client secret. | [View your OAuth Client](https://developers.linode.com/api/v4/account-oauth-clients-client-id). [Reset Your OAuth Client Secret](https://developers.linode.com/api/v4/account-oauth-clients-client-id-reset-secret/#post). |
-      | code | The code you just received from the redirect | [View your OAuth Client](https://developers.linode.com/api/v4/account-oauth-clients-client-id). [Reset Your OAuth Client Secret](https://developers.linode.com/api/v4/account-oauth-clients-client-id-reset-secret/#post). |
+      | PARAMETER | DESCRIPTION |
+      |-----------|-------------|
+      | client_id | Your app's client ID. |
+      | client_secret | Your app's client secret. |
+      | code | The code you just received from the redirect |
 
     You'll get a reponse like this: