Merge pull request #527 from zapier/auth-wording-cleanup

[SUPPORTESC-307] docs(cli): Auth link update and wording cleanup

docs/index.html

@@ -1137,9 +1137,7 @@ <h2 id="authentication">Authentication</h2>
 </div><div class="row">
   <div class="row-height">
     <div class="col-md-5 col-sm-12 col-height  docs-primary">
-      <p>Most applications require some sort of authentication - and Zapier provides a handful of methods for helping your users authenticate with your application. Zapier will provide some of the core behaviors, but you&apos;ll likely need to handle the rest.</p><blockquote>
-<p>Hint: You can access the data tied to your authentication via the <code>bundle.authData</code> property in any method called in your app. Exceptions exist in OAuth and Session auth. Please see them below.</p>
-</blockquote>
+      <p>Most applications require some sort of authentication. The Zapier platform provides core behaviors for several common authentication methods that might be used with your application, as well as the ability to customize authentication further.</p><p>When a user authenticates to your application through Zapier, a &quot;connection&quot; is created representing their authentication details. Data tied to a specific authentication connection is included in the <a href="#bundle-object">bundle object</a> under <code>bundle.authData</code>.</p>
     </div>
     <div class="col-md-7 col-sm-12 col-height is-empty docs-code">
 
@@ -1193,10 +1191,10 @@ <h3 id="digest">Digest</h3>
 </div><div class="row">
   <div class="row-height">
     <div class="col-md-5 col-sm-12 col-height  docs-primary">
-      <p><em>New in v7.4.0.</em></p><p>The setup and user experience of Digest Auth is identical to Basic Auth. Users will provide Zapier their username and password and Zapier will handle all the nonce and quality of protection details automatically.</p><blockquote>
+      <p><em>New in v7.4.0.</em></p><p>The setup and user experience of Digest Auth is identical to Basic Auth. Users provide Zapier their username and password, and Zapier handles all the nonce and quality of protection details automatically.</p><blockquote>
 <p>Example App: Check out <a href="https://github.com/zapier/zapier-platform/tree/master/example-apps/digest-auth">https://github.com/zapier/zapier-platform/tree/master/example-apps/digest-auth</a> for a working example app for digest auth.</p>
 </blockquote><blockquote>
-<p>Limitation: Currently, MD5-sess and SHA are not implemented. Only the MD5 algorithm is supported. In addition, server nonces are not reused. That means for every <code>z.request</code> call, Zapier will sends an additional request beforehand to get the server nonce.</p>
+<p>Limitation: Currently, MD5-sess and SHA are not implemented. Only the MD5 algorithm is supported. In addition, server nonces are not reused. That means for every <code>z.request</code> call, Zapier will send an additional request beforehand to get the server nonce.</p>
 </blockquote>
     </div>
     <div class="col-md-7 col-sm-12 col-height  docs-code">
@@ -1237,7 +1235,7 @@ <h3 id="custom">Custom</h3>
 </div><div class="row">
   <div class="row-height">
     <div class="col-md-5 col-sm-12 col-height  docs-primary">
-      <p>This is what most &quot;API Key&quot; driven apps should default to using. You&apos;ll likely provide some custom <code>beforeRequest</code> middleware or a <code>requestTemplate</code> to complete the authentication by adding/computing needed headers.</p><blockquote>
+      <p>Custom auth is most commonly used for apps that authenticate with API keys, although it also provides flexibility for any unusual authentication setup. You&apos;ll likely provide some custom <code>beforeRequest</code> middleware or a <code>requestTemplate</code> (see <a href="#making-http-requests">Making HTTP Requests</a>) to pass in data returned from the authentication process, most commonly by adding/computing needed headers.</p><blockquote>
 <p>Example App: Check out <a href="https://github.com/zapier/zapier-platform/tree/master/example-apps/custom-auth">https://github.com/zapier/zapier-platform/tree/master/example-apps/custom-auth</a> for a working example app for custom auth.</p>
 </blockquote>
     </div>
@@ -1296,7 +1294,7 @@ <h3 id="session">Session</h3>
 </div><div class="row">
   <div class="row-height">
     <div class="col-md-5 col-sm-12 col-height  docs-primary">
-      <p>Probably the most &quot;powerful&quot; mechanism for authentication - it gives you the ability to exchange some user provided data for some authentication data (IE: username &amp; password for a session key).</p><blockquote>
+      <p>Session auth gives you the ability to exchange some user-provided data for some authentication data; for example, username and password for a session key. It can be used to implement almost any authentication method that uses that pattern - for example, alternative OAuth flows.</p><blockquote>
 <p>Example App: Check out <a href="https://github.com/zapier/zapier-platform/tree/master/example-apps/session-auth">https://github.com/zapier/zapier-platform/tree/master/example-apps/session-auth</a> for a working example app for session auth.</p>
 </blockquote>
     </div>
@@ -1370,9 +1368,7 @@ <h3 id="session">Session</h3>
 </div><div class="row">
   <div class="row-height">
     <div class="col-md-5 col-sm-12 col-height  docs-primary">
-      <blockquote>
-<p>Note: For Session auth, <code>authentication.sessionConfig.perform</code> will have the provided fields in <code>bundle.inputData</code> instead of <code>bundle.authData</code> because <code>bundle.authData</code> will only have &quot;previously existing&quot; values, which will be empty the first time the Zap runs.</p>
-</blockquote>
+      <p>For Session auth, the function that fetches the additional authentication data needed to make API calls (<code>authentication.sessionConfig.perform</code>) has the user-provided fields in <code>bundle.inputData</code>. Afterwards, <code>bundle.authData</code> contains the data returned by that function (usually the session key or token).</p>
     </div>
     <div class="col-md-7 col-sm-12 col-height is-empty docs-code">
 
@@ -1390,7 +1386,7 @@ <h3 id="oauth1">OAuth1</h3>
 </div><div class="row">
   <div class="row-height">
     <div class="col-md-5 col-sm-12 col-height  docs-primary">
-      <p><em>New in <code>v7.5.0</code>.</em></p><p>Zapier&apos;s OAuth1 implementation matches <a href="https://developer.twitter.com/en/docs/basics/authentication/overview">Twitter&apos;s</a> and <a href="https://developers.trello.com/page/authorization">Trello&apos;s</a> implementation of the 3-legged OAuth flow.</p><blockquote>
+      <p><em>New in <code>v7.5.0</code>.</em></p><p>Zapier&apos;s OAuth1 implementation matches <a href="https://developer.twitter.com/en/docs/tutorials/authenticating-with-twitter-api-for-enterprise/authentication-method-overview#oauth1.0a">Twitter</a> and <a href="https://developer.atlassian.com/cloud/trello/guides/rest-api/authorization/#using-basic-oauth">Trello</a> implementations of the 3-legged OAuth flow.</p><blockquote>
 <p>Example Apps: Check out <a href="https://github.com/zapier/zapier-platform/tree/master/example-apps/oauth1-trello">oauth1-trello</a>, <a href="https://github.com/zapier/zapier-platform/tree/master/example-apps/oauth1-tumblr">oauth1-tumblr</a>, and <a href="https://github.com/zapier/zapier-platform/tree/master/example-apps/oauth1-twitter">oauth1-twitter</a> for working example apps with OAuth1.</p>
 </blockquote><p>The flow works like this:</p><ol>
 <li>Zapier makes a call to your API requesting a &quot;request token&quot; (also known as &quot;temporary credentials&quot;).</li>
@@ -1506,9 +1502,7 @@ <h3 id="oauth1">OAuth1</h3>
 </div><div class="row">
   <div class="row-height">
     <div class="col-md-5 col-sm-12 col-height  docs-primary">
-      <blockquote>
-<p>Note: For OAuth1, <code>authentication.oauth1Config.getRequestToken</code>, <code>authentication.oauth1Config.authorizeUrl</code>, and <code>authentication.oauth1Config.getAccessToken</code> will have the provided fields in <code>bundle.inputData</code> instead of <code>bundle.authData</code> because <code>bundle.authData</code> will only have &quot;previously existing&quot; values, which will be empty when the user hasn&apos;t connected their account on your service to Zapier. Also note that <code>authentication.oauth1Config.getAccessToken</code> has access to the users return values in <code>rawRequest</code> and <code>cleanedRequest</code> should you need to extract other values (for example from the query string).</p>
-</blockquote>
+      <p>For OAuth1, <code>authentication.oauth1Config.getRequestToken</code>, <code>authentication.oauth1Config.authorizeUrl</code>, and <code>authentication.oauth1Config.getAccessToken</code> have fields like <code>redirect_uri</code> and the temporary credentials in <code>bundle.inputData</code>. After <code>getAccessToken</code> runs, the resulting token value(s) will be stored in <code>bundle.authData</code> for the connection.</p><p>Also, <code>authentication.oauth1Config.getAccessToken</code> has access to the additional return values in <code>rawRequest</code> and <code>cleanedRequest</code> should you need to extract other values (for example, from the query string).</p>
     </div>
     <div class="col-md-7 col-sm-12 col-height is-empty docs-code">
 
@@ -1537,7 +1531,7 @@ <h3 id="oauth2">OAuth2</h3>
 </ol><p>You are required to define:</p><ul>
 <li><code>authorizeUrl</code>: The authorization URL</li>
 <li><code>getAccessToken</code>: The API call to fetch the access token</li>
-</ul><p>If the access token has a limited life and you want to refresh the token when it expires, you&apos;ll also need to define the API call to perform that refresh. You can choose to set <code>autoRefresh: true</code>, as in the example app, if you want Zapier to automatically make a call to refresh the token after receiving a 401. See <a href="#stale-authentication-credentials">Stale Authentication Credentials</a> for more details on handling auth refresh.</p><p>You&apos;ll also likely want to set your <code>CLIENT_ID</code> and <code>CLIENT_SECRET</code> as environment variables:</p>
+</ul><p>If the access token has a limited life and you want to refresh the token when it expires, you&apos;ll also need to define the API call to perform that refresh (<code>refreshAccessToken</code>). You can choose to set <code>autoRefresh: true</code>, as in the example app, if you want Zapier to automatically make a call to refresh the token after receiving a 401. See <a href="#stale-authentication-credentials">Stale Authentication Credentials</a> for more details on handling auth refresh.</p><p>You&apos;ll also likely want to set your <code>CLIENT_ID</code> and <code>CLIENT_SECRET</code> as environment variables:</p>
     </div>
     <div class="col-md-7 col-sm-12 col-height  docs-code">
       <pre><code class="lang-bash"><span class="hljs-comment"># setting the environment variables on Zapier.com</span>
@@ -1627,9 +1621,7 @@ <h3 id="oauth2">OAuth2</h3>
 </div><div class="row">
   <div class="row-height">
     <div class="col-md-5 col-sm-12 col-height  docs-primary">
-      <blockquote>
-<p>Note: For OAuth2, <code>authentication.oauth2Config.authorizeUrl</code>, <code>authentication.oauth2Config.getAccessToken</code>, and <code>authentication.oauth2Config.refreshAccessToken</code>  will have the provided fields in <code>bundle.inputData</code> instead of <code>bundle.authData</code> because <code>bundle.authData</code> will only have &quot;previously existing&quot; values, which will be empty when the user hasn&apos;t connected their account on your service to Zapier. Also note that <code>authentication.oauth2Config.getAccessToken</code> has access to the users return values in <code>rawRequest</code> and <code>cleanedRequest</code> should you need to extract other values (for example from the query string).</p>
-</blockquote>
+      <p>For OAuth2, <code>authentication.oauth2Config.authorizeUrl</code>, <code>authentication.oauth2Config.getAccessToken</code>, and <code>authentication.oauth2Config.refreshAccessToken</code> have fields like <code>redirect_uri</code> and <code>state</code> in <code>bundle.inputData</code>. After the code is exchanged for an access token and/or refresh token, those tokens are stored in <code>bundle.authData</code> for the connection.</p><p>Also, <code>authentication.oauth2Config.getAccessToken</code> has access to the additional return values in <code>rawRequest</code> and <code>cleanedRequest</code> should you need to extract other values (for example, from the query string).</p>
     </div>
     <div class="col-md-7 col-sm-12 col-height is-empty docs-code">
 
@@ -3392,7 +3384,7 @@ <h2 id="making-http-requests">Making HTTP Requests</h2>
 <li><strong>Shorthand HTTP Requests</strong> - these are simple object literals that make it easy to define simple requests.</li>
 <li><strong>Manual HTTP Requests</strong> - you use <code>z.request([url], options)</code> to make the requests and control the response. Use this when you need to change options for certain requests (for all requests, use middleware).</li>
 </ol><p>There are also a few helper constructs you can use to reduce boilerplate:</p><ol>
-<li><code>requestTemplate</code> which is an shorthand HTTP request that will be merged with every request.</li>
+<li><code>requestTemplate</code> which is a shorthand HTTP request that will be merged with every request.</li>
 <li><code>beforeRequest</code> middleware which is an array of functions to mutate a request before it is sent.</li>
 <li><code>afterResponse</code> middleware which is an array of functions to mutate a response before it is completed.</li>
 </ol><blockquote>
@@ -3415,7 +3407,7 @@ <h3 id="shorthand-http-requests">Shorthand HTTP Requests</h3>
 </div><div class="row">
   <div class="row-height">
     <div class="col-md-5 col-sm-12 col-height  docs-primary">
-      <p>For simple HTTP requests that do not require special pre or post processing, you can specify the HTTP options as an object literal in your app definition.</p><p>This features:</p><ol>
+      <p>For simple HTTP requests that do not require special pre- or post-processing, you can specify the HTTP options as an object literal in your app definition.</p><p>This features:</p><ol>
 <li>Lazy <code>{{curly}}</code> replacement.</li>
 <li>JSON and form body de-serialization.</li>
 <li>Automatic non-2xx error raising.</li>