Sync changes from upstream repository

Hubot · Hubot · commit 905164e65884 · 2016-05-27T07:16:34.000-07:00
diff --git a/content/v3/oauth.md b/content/v3/oauth.md
@@ -6,7 +6,7 @@ title: OAuth
 
 {:toc}
 
-OAuth2 is a protocol that lets external apps request authorization to
+OAuth2 is a protocol that lets external applications request authorization to
 private details in a user's {{ site.data.variables.product.product_name }} account without getting their
 password. This is preferred over [Basic Authentication](/v3/auth#basic-authentication) because tokens can
 be limited to specific types of data, and can be revoked by users at any
@@ -34,8 +34,8 @@ This is a description of the OAuth2 flow from 3rd party web sites.
 Name | Type | Description
 -----|------|--------------
 `client_id`|`string` | **Required**. The client ID you received from GitHub when you [registered](https://github.com/settings/applications/new).
-`redirect_uri`|`string` | The URL in your app where users will be sent after authorization. See details below about [redirect urls](#redirect-urls).
-`scope`|`string` | A space delimited list of [scopes](#scopes). If not provided, `scope` defaults to an empty list of scopes for users that don't have a valid token for the app. For users who do already have a valid token for the app, the user won't be shown the OAuth authorization page with the list of scopes. Instead, this step of the flow will automatically complete with the same scopes that were used last time the user completed the flow.
+`redirect_uri`|`string` | The URL in your application where users will be sent after authorization. See details below about [redirect urls](#redirect-urls).
+`scope`|`string` | A space delimited list of [scopes](#scopes). If not provided, `scope` defaults to an empty list for users that have not authorized any scopes for the application. For users who have authorized scopes for the application, the user won't be shown the OAuth authorization page with the list of scopes. Instead, this step of the flow will automatically complete with the set of scopes the user has authorized for the application. For example, if a user has already performed the web flow twice and has authorized one token with `user` scope and another token with `repo` scope, a third web flow that does not provide a `scope` will receive a token with `user` and `repo` scope.
 `state`|`string` | An unguessable random string. It is used to protect against cross-site request forgery attacks.
 `allow_signup`|`string` | Whether or not unauthenticated users will be offered an option to sign up for GitHub during the OAuth flow. The default is `true`. Use `false` in the case that a policy prohibits signups.
 
@@ -57,7 +57,7 @@ Name | Type | Description
 `client_id`|`string` | **Required**. The client ID you received from GitHub when you [registered](https://github.com/settings/applications/new).
 `client_secret`|`string` | **Required**. The client secret you received from GitHub when you [registered](https://github.com/settings/applications/new).
 `code`|`string` | **Required**. The code you received as a response to [Step 1](#1-redirect-users-to-request-github-access).
-`redirect_uri`|`string` | The URL in your app where users will be sent after authorization. See details below about [redirect urls](#redirect-urls).
+`redirect_uri`|`string` | The URL in your application where users will be sent after authorization. See details below about [redirect urls](#redirect-urls).
 `state`|`string` | The unguessable random string you optionally provided in [Step 1](#1-redirect-users-to-request-github-access).
 
 ### Response
@@ -79,6 +79,19 @@ header:
       <access_token>e72e16c7e42f292c6912e7710c838347ae178b4a</access_token>
     </OAuth>
 
+#### Multiple tokens
+
+GitHub allows multiple tokens to exist for a user/application/scope combination.
+This can be used to create tokens for specific use cases. For example, your
+application might support one workflow that uses GitHub for sign in, and only
+requires basic user information. And, your application might support a different
+workflow that requires access to a user's private repositories. Using multiple
+tokens, your application can perform the web flow for each use case, requesting
+only the scopes needed. If a user only uses your application to sign in, they
+are never required to grant your application access to their private
+repositories. Note, there is a limit to the number of tokens that are issued per
+user/application/scope combination. If your application requests enough tokens
+to go over one of the limits, older tokens will stop working.
 
 #### Requested scopes vs. granted scopes
 
@@ -319,7 +332,7 @@ and get a new code.
 Users can review and revoke their application authorizations from the [settings
 screen within GitHub][authorized-apps]. A user's organizations [control whether
 an application can access organization data][org-app-policies]. Integrators can
-deep link to the authorization information for their particular app to let their
+deep link to the authorization information for their particular application to let their
 end users review these details.
 
 To build this link, you'll need your OAuth application's `client_id` you
