[July 26 2021] Document PAT expiration (github#19469)

Steve Winton · web-flow · commit 1f2d8aa8a544 · 2021-07-26T15:52:34.000Z
diff --git a/assets/images/help/settings/token_expiration.png b/assets/images/help/settings/token_expiration.png
diff --git a/assets/images/personal_token.png b/assets/images/personal_token.png
diff --git a/content/developers/apps/getting-started-with-apps/about-apps.md b/content/developers/apps/getting-started-with-apps/about-apps.md
@@ -84,6 +84,7 @@ Keep these ideas in mind when using personal access tokens:
 * You can run personal scripts.
 * Don't set up a script for your whole team or company to use.
 * Don't set up a shared user account to act as a bot user.
+* Do set an expiration for your personal access tokens, to help keep your information secure.
 
 ## Determining which integration to build
 
diff --git a/content/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token.md b/content/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token.md
@@ -16,7 +16,7 @@ topics:
   - Access management
 shortTitle: Create a PAT
 ---
-Personal access tokens (PATs) are an alternative to using passwords for authentication to {% data variables.product.product_name %} when using the [GitHub API](/rest/overview/other-authentication-methods#via-oauth-and-personal-access-tokens) or the [command line](#using-a-token-on-the-command-line). 
+Personal access tokens (PATs) are an alternative to using passwords for authentication to {% data variables.product.product_name %} when using the [GitHub API](/rest/overview/other-authentication-methods#via-oauth-and-personal-access-tokens) or the [command line](#using-a-token-on-the-command-line).
 
 {% ifversion fpt %}If you want to use a PAT to access resources owned by an organization that uses SAML SSO, you must authorize the PAT. For more information, see "[About authentication with SAML single sign-on](/github/authenticating-to-github/about-authentication-with-saml-single-sign-on)" and "[Authorizing a personal access token for use with SAML single sign-on](/github/authenticating-to-github/authorizing-a-personal-access-token-for-use-with-saml-single-sign-on)."{% endif %}
 
@@ -31,16 +31,17 @@ Personal access tokens (PATs) are an alternative to using passwords for authenti
 4. Click **Generate new token**.
    ![Generate new token button](/assets/images/help/settings/generate_new_token.png)
 5. Give your token a descriptive name.
-   ![Token description field](/assets/images/help/settings/token_description.png)
-6. Select the scopes, or permissions, you'd like to grant this token. To use your token to access repositories from the command line, select **repo**.
+   ![Token description field](/assets/images/help/settings/token_description.png){% ifversion fpt or ghes > 3.1 or ghae-issue-4374 %}
+6. To give your token an expiration, select the **Expiration** drop-down menu, then click a default or use the calendar picker.
+   ![Token expiration field](/assets/images/help/settings/token_expiration.png){% endif %}
+7. Select the scopes, or permissions, you'd like to grant this token. To use your token to access repositories from the command line, select **repo**.
    {% ifversion fpt or ghes %}
    ![Selecting token scopes](/assets/images/help/settings/token_scopes.gif)
    {% elsif ghae %}
    ![Selecting token scopes](/assets/images/enterprise/github-ae/settings/access-token-scopes-for-ghae.png)
    {% endif %}
-7. Click **Generate token**.
+8. Click **Generate token**.
    ![Generate token button](/assets/images/help/settings/generate_token.png)
-8. Click {% octicon "clippy" aria-label="The copy to clipboard icon" %} to copy the token to your clipboard. For security reasons, after you navigate off the page, you will not be able to see the token again.
    {% ifversion fpt %}
    ![Newly created token](/assets/images/help/settings/personal_access_tokens.png)
    {% elsif ghes > 3.1 or ghae-next %}
@@ -50,7 +51,7 @@ Personal access tokens (PATs) are an alternative to using passwords for authenti
    {% endif %}
    {% warning %}
 
-   **Warning:** Treat your tokens like passwords and keep them secret. When working with the API, use tokens as environment variables instead of hardcoding them into your programs.
+   **Warning:** Treat your tokens like passwords and keep them secret. When working with the API, use tokens as environment variables instead of hardcoding them into your programs. 
 
    {% endwarning %}
 
diff --git a/content/rest/guides/getting-started-with-the-rest-api.md b/content/rest/guides/getting-started-with-the-rest-api.md
@@ -147,6 +147,14 @@ When authenticating, you should see your rate limit bumped to 5,000 requests an
 
 You can easily [create a **personal access token**][personal token] using your [Personal access tokens settings page][tokens settings]:
 
+{% ifversion fpt or ghes > 3.1 or ghae-issue-4374 %}
+{% warning %}
+
+To help keep your information secure, we highly recommend setting an expiration for your personal access tokens.
+
+{% endwarning %}
+{% endif %}
+
 {% ifversion fpt or ghes %}
 ![Personal Token selection](/assets/images/personal_token.png)
 {% endif %}
@@ -155,6 +163,10 @@ You can easily [create a **personal access token**][personal token] using your [
 ![Personal Token selection](/assets/images/help/personal_token_ghae.png)
 {% endif %}
 
+{% ifversion fpt or ghes > 3.1 or ghae-issue-4374 %}
+API requests using an expiring personal access token will return that token's expiration date via the `GitHub-Authentication-Token-Expiration` header. You can use the header in your scripts to provide a warning message when the token is close to its expiration date.
+{% endif %}
+
 ### Get your own user profile
 
 When properly authenticated, you can take advantage of the permissions
diff --git a/data/reusables/user_settings/removes-personal-access-tokens.md b/data/reusables/user_settings/removes-personal-access-tokens.md
@@ -1 +1 @@
-As a security precaution, {% data variables.product.prodname_dotcom %}  automatically removes personal access tokens that haven't been used in a year.
+As a security precaution, {% data variables.product.company_short %} automatically removes personal access tokens that haven't been used in a year.{% ifversion fpt or ghes > 3.1 or ghae-issue-4374 %} To provide additional security, we highly recommend adding an expiration to your personal access tokens.{% endif %}

Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-As a security precaution, {% data variables.product.prodname_dotcom %} automatically removes personal access tokens that haven't been used in a year.`
	`1`	`+As a security precaution, {% data variables.product.company_short %} automatically removes personal access tokens that haven't been used in a year.{% ifversion fpt or ghes > 3.1 or ghae-issue-4374 %} To provide additional security, we highly recommend adding an expiration to your personal access tokens.{% endif %}`