New article about keeping your API credentials secure (#37076)

Co-authored-by: Sarah Edwards <skedwards88@github.com>

content/authentication/keeping-your-account-and-data-secure/about-authentication-to-github.md

@@ -94,7 +94,11 @@ You can also create an OAuth token with an {% data variables.product.prodname_oa
 
 ### Authenticating to the API in a {% data variables.product.prodname_actions %} workflow
 
-If you want to use the API in a {% data variables.product.prodname_actions %} workflow, {% data variables.product.company_short %} recommends that you authenticate with the built-in `GITHUB_TOKEN` instead of creating a token. You can grant permissions to the `GITHUB_TOKEN` with the `permissions` key. For more information, see "[AUTOTITLE](/actions/security-guides/automatic-token-authentication#permissions-for-the-github_token)."
+If you want to use the API in a {% data variables.product.prodname_actions %} workflow, {% data variables.product.company_short %} recommends that you authenticate with the built-in `GITHUB_TOKEN` instead of creating a token. You can grant permissions to the `GITHUB_TOKEN` with the `permissions` key.
+
+Note that `GITHUB_TOKEN` can only access resources within the repository that contains the workflow. If you need to make changes to resources outside of the workflow repository, you will need to use a {% data variables.product.pat_generic %} or {% data variables.product.prodname_github_app %}.
+
+For more information, see "[AUTOTITLE](/actions/security-guides/automatic-token-authentication#permissions-for-the-github_token)."
 
 ## Authenticating with the command line
 

content/authentication/keeping-your-account-and-data-secure/index.md

@@ -16,7 +16,7 @@ children:
   - /about-authentication-to-github
   - /creating-a-strong-password
   - /updating-your-github-access-credentials
-  - /creating-a-personal-access-token
+  - /managing-your-personal-access-tokens
   - /reviewing-your-ssh-keys
   - /reviewing-your-deploy-keys
   - /token-expiration-and-revocation
@@ -31,3 +31,4 @@ children:
   - /viewing-and-managing-your-sessions
 shortTitle: Account security
 ---
+

content/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens.md

@@ -1,6 +1,7 @@
 ---
-title: Creating a personal access token
-intro: 'Use a {% data variables.product.pat_generic %} in place of a password when authenticating to GitHub in the command line or with the API.'
+title: Managing your personal access tokens
+shortTitle: 'Manage {% data variables.product.pat_generic %}s'
+intro: 'You can use a {% data variables.product.pat_generic %} in place of a password when authenticating to GitHub in the command line or with the API.'
 redirect_from:
   - /articles/creating-an-oauth-token-for-command-line-use
   - /articles/creating-an-access-token-for-command-line-use
@@ -9,6 +10,7 @@ redirect_from:
   - /github/authenticating-to-github/creating-a-personal-access-token
   - /github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token
   - /github/extending-github/git-automation-with-oauth-tokens
+  - /authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token
 versions:
   fpt: '*'
   ghes: '*'
@@ -17,7 +19,6 @@ versions:
 topics:
   - Identity
   - Access management
-shortTitle: 'Create a {% data variables.product.pat_generic %}'
 ---
 
 {% warning %}
@@ -79,6 +80,8 @@ If these options are not possible, and you must create a {% data variables.produ
 
 When using a {% data variables.product.pat_generic %} in a script, you can store your token as a secret and run your script through {% data variables.product.prodname_actions %}. For more information, see "[AUTOTITLE](/actions/security-guides/encrypted-secrets)."{%- ifversion ghec or fpt %} You can also store your token as a {% data variables.product.prodname_codespaces %} secret and run your script in {% data variables.product.prodname_codespaces %}. For more information, see "[AUTOTITLE](/codespaces/managing-your-codespaces/managing-encrypted-secrets-for-your-codespaces)."{% endif %}
 
+For more information about best practices, see "[AUTOTITLE](/rest/overview/keeping-your-api-credentials-secure)."
+
 ## Creating a {% data variables.product.pat_v2 %}
 
 {% note %}
@@ -142,9 +145,24 @@ If you selected an organization as the resource owner and the organization requi
    ![Screenshot of the "{% data variables.product.pat_generic_caps_plural %}" page. Next to a blurred-out token, an icon of two overlapping squares is outlined in orange.](/assets/images/help/settings/personal_access_tokens.png){% ifversion fpt or ghec %}
 1. To use your token to access resources owned by an organization that uses SAML single sign-on, authorize the token. For more information, see "[AUTOTITLE](/enterprise-cloud@latest/authentication/authenticating-with-saml-single-sign-on/authorizing-a-personal-access-token-for-use-with-saml-single-sign-on){% ifversion fpt %}" in the {% data variables.product.prodname_ghe_cloud %} documentation.{% else %}."{% endif %}{% endif %}
 
+## Deleting a {% data variables.product.pat_generic %}
+
+{% data reusables.user-settings.access_settings %}
+{% data reusables.user-settings.developer_settings %}
+{% ifversion pat-v2 %}1. In the left sidebar, under **{% octicon "key" aria-hidden="true" %} {% data variables.product.pat_generic_caps %}s**, click either **Fine-grained tokens** or **Tokens (classic)**, depending on which type of {% data variables.product.pat_generic %} you'd like to delete.{% else %}{% data reusables.user-settings.personal_access_tokens %}{% endif %}
+1. To the right of the {% data variables.product.pat_generic %} you want to delete, click **Delete**.
+
 ## Using a {% data variables.product.pat_generic %} on the command line
 
-{% data reusables.command_line.providing-token-as-password %}
+Once you have a {% data variables.product.pat_generic %}, you can enter it instead of your password when performing Git operations over HTTPS.
+
+For example, to clone a repository on the command line you would enter the following `git clone` command. You would then be prompted to enter your username and password. When prompted for your password, enter your {% data variables.product.pat_generic %} instead of a password.
+
+```shell
+$ git clone https://{% data variables.command_line.codeblock %}/USERNAME/REPO.git
+Username: YOUR_USERNAME
+Password: YOUR_PERSONAL_ACCESS_TOKEN
+```
 
 {% data variables.product.pat_generic_caps %}s can only be used for HTTPS Git operations. If your repository uses an SSH remote URL, you will need to [switch the remote from SSH to HTTPS](/get-started/getting-started-with-git/managing-remote-repositories#switching-remote-urls-from-ssh-to-https).
 

content/rest/guides/getting-started-with-the-rest-api.md

@@ -104,6 +104,8 @@ If you want to use the API on behalf of an organization or another user, {% data
 
 If you want to use the API in a {% data variables.product.prodname_actions %} workflow, {% data variables.product.company_short %} recommends that you authenticate with the built-in `GITHUB_TOKEN` instead of creating a token. You can grant permissions to the `GITHUB_TOKEN` with the `permissions` key. For more information, see "[AUTOTITLE](/actions/security-guides/automatic-token-authentication#permissions-for-the-github_token)."
 
+For more information about best practices you can use to keep your tokens secure, see "[AUTOTITLE](/rest/overview/keeping-your-api-credentials-secure)."
+
 ### Authentication example
 
 {% cli %}

content/rest/index.md

@@ -19,7 +19,7 @@ featuredLinks:
     - /rest/overview/other-authentication-methods
     - /rest/overview/troubleshooting
     - /rest/guides/scripting-with-the-rest-api-and-javascript
-    - /rest/overview/openapi-description
+    - /rest/overview/keeping-your-api-credentials-secure
   guideCards:
     - /rest/guides/delivering-deployments
     - /rest/guides/using-the-rest-api-to-interact-with-checks

content/rest/overview/authenticating-to-the-rest-api.md

@@ -89,3 +89,7 @@ curl --request GET \
 Authentication with username and password is not supported. If you try to authenticate with user name and password, you will receive a 4xx error.
 
 {% endif %}
+
+## Further reading
+
+- "[AUTOTITLE](/rest/overview/keeping-your-api-credentials-secure)."

content/rest/overview/endpoints-available-for-fine-grained-personal-access-tokens.md

@@ -3,7 +3,7 @@ title: Endpoints available for fine-grained personal access tokens
 intro: 'Your {% data variables.product.pat_v2 %} can make requests to the following REST endpoints.'
 versions:
   feature: pat-v2
-shortTitle: '{% data variables.product.pat_v2_caps %}-enabled endpoints'
+shortTitle: 'Endpoints for fine-grained PATs'
 ---
 
 ## actions

content/rest/overview/endpoints-available-for-github-apps.md

@@ -12,7 +12,7 @@ versions:
   ghec: '*'
 topics:
   - API
-shortTitle: GitHub App-enabled endpoints
+shortTitle: Endpoints for GitHub Apps
 autogenerated: github-apps
 ---
 

content/rest/overview/index.md

@@ -15,15 +15,15 @@ children:
   - /api-versions
   - /media-types
   - /authenticating-to-the-rest-api
+  - /keeping-your-api-credentials-secure
   - /troubleshooting
   - /libraries
   - /openapi-description
   - /endpoints-available-for-github-apps
   - /endpoints-available-for-fine-grained-personal-access-tokens
   - /permissions-required-for-github-apps
-  - /breaking-changes
   - /permissions-required-for-fine-grained-personal-access-tokens
+  - /breaking-changes
 redirect_from:
   - /developers/overview
 ---
-

content/rest/overview/keeping-your-api-credentials-secure.md

@@ -0,0 +1,75 @@
+---
+title: Keeping your API credentials secure
+shortTitle: Keeping API credentials secure
+intro: 'Follow these best practices to keep your API credentials and tokens secure.'
+versions:
+  fpt: '*'
+  ghes: '*'
+  ghae: '*'
+  ghec: '*'
+topics:
+  - API
+---
+
+## Choose an appropriate authentication method
+
+You should choose an authentication method that is appropriate for the task you want to accomplish.
+
+- To use the API for personal use, you can create a {% data variables.product.pat_generic %}.
+- To use the API on behalf of an organization or another user, you should create a {% data variables.product.prodname_github_app %}.
+- To use the API in a {% data variables.product.prodname_actions %} workflow, you should authenticate with the built-in `GITHUB_TOKEN`.
+
+For more information, see "[AUTOTITLE](/authentication/keeping-your-account-and-data-secure/about-authentication-to-github#authenticating-with-the-api)."
+
+## Limit the permissions of your credentials
+
+{% ifversion pat-v2 %}
+
+When creating a {% data variables.product.pat_generic %}, only select the minimum permissions or scopes needed, and set an expiration date for the minimum amount of time you'll need to use the token. {% data variables.product.company_short %} recommends that you use {% data variables.product.pat_v2 %}s instead of {% data variables.product.pat_v1_plural %}. For more information, see "[AUTOTITLE](/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#types-of-personal-access-tokens)."
+
+{% else %}
+
+When creating a {% data variables.product.pat_generic %}, only select the minimum scopes needed, and set an expiration date for the minimum amount of time you'll need to use the token. For more information, see "[AUTOTITLE](/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)."
+
+{% endif %}
+
+When creating a {% data variables.product.prodname_github_app %}, select the minimum permissions that your {% data variables.product.prodname_github_app %} will need. For more information, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/best-practices-for-creating-a-github-app)."
+
+When authenticating with `GITHUB_TOKEN` in a {% data variables.product.prodname_actions %} workflow, only give the minimum amount of permissions needed. For more information, see "[AUTOTITLE](/actions/security-guides/automatic-token-authentication#permissions-for-the-github_token)."
+
+## Store your authentication credentials securely
+
+Treat authentication credentials the same way you would treat your passwords or other sensitive credentials.
+
+- Don't share authentication credentials using an unencrypted messaging or email system.
+- Don't pass your {% data variables.product.pat_generic %} as plain text in the command line. For more information, see "[AUTOTITLE](/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#keeping-your-personal-access-tokens-secure)."
+- Don't push unencrypted authentication credentials like tokens or keys to any repository, even if the repository is private. Instead consider using a {% data variables.product.prodname_actions %} secret{% ifversion fpt or ghec %} or Codespaces secret{% endif %}. For more information, see "[AUTOTITLE](/actions/security-guides/encrypted-secrets)"{% ifversion fpt or ghec %} and "[AUTOTITLE](/codespaces/managing-your-codespaces/managing-encrypted-secrets-for-your-codespaces)"{% endif %}.
+- You can use secret scanning to discover tokens, private keys, and other secrets that were pushed to a repository, or to block future pushes that contain secrets. For more information, see "[AUTOTITLE](/code-security/secret-scanning/about-secret-scanning)."
+
+## Limit who can access your authentication credentials
+
+Don't share your {% data variables.product.pat_generic %} with others. Instead of sharing a {% data variables.product.pat_generic %}, consider creating a {% data variables.product.prodname_github_app %}. For more information, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/about-creating-github-apps)."
+
+If you need to share credentials with a team, store the credentials in a secure shared system. For example, you could store and share passwords securely using [1Password](https://1password.com/), or you could store keys in [Azure KeyVault](https://azure.microsoft.com/en-gb/products/key-vault) and manage access with your IAM (Identity and access management).
+
+If you're creating a {% data variables.product.prodname_actions %} workflow that needs to access the API, you can store your credentials in an encrypted secret, and access the encrypted secret from the workflow. For more information, see "[AUTOTITLE](/actions/security-guides/encrypted-secrets)"{% ifversion projects-v2 %} and "[AUTOTITLE](/apps/creating-github-apps/guides/making-authenticated-api-requests-with-a-github-app-in-a-github-actions-workflow)"{% endif %}.
+
+## Use authentication credentials securely in your code
+
+Never hardcode authentication credentials like tokens, keys, or app-related secrets into your code. Instead, consider using a secret manager such as [Azure Key Vault](https://azure.microsoft.com/products/key-vault) or [HashiCorp Vault](https://www.hashicorp.com/products/vault). For more information about securing {% data variables.product.prodname_github_app %} credentials, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/best-practices-for-creating-a-github-app)."
+
+When using a {% data variables.product.pat_generic %} in a script, consider storing your token as a {% data variables.product.prodname_actions %} secret and running your script through {% data variables.product.prodname_actions %}.{% ifversion fpt or ghec %}  You can also store your token as a Codespaces secret and run your script in Codespaces.{% endif %} For more information, see "[AUTOTITLE](/actions/security-guides/encrypted-secrets)"{% ifversion fpt or ghec %} and "[AUTOTITLE](/codespaces/managing-your-codespaces/managing-encrypted-secrets-for-your-codespaces)"{% endif %}.
+
+If none of these options are possible, you can store authentication credentials in a `.env` file. Make sure to encrypt your `.env` file, and never push it to any repository.
+
+## Prepare a remediation plan
+
+You should create a plan to handle any security breaches in a timely manner. In the event that your token or other authentication credential is leaked, you will need to:
+
+- Generate a new credential.
+- Replace the old credential with the new one everywhere that you are storing or accessing the credential.
+- Delete the old compromised credential.
+
+For information about rotating compromised credentials for a {% data variables.product.prodname_github_app %}, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/best-practices-for-creating-a-github-app)."
+
+For information about creating and deleting {% data variables.product.pat_generic %}s, see "[AUTOTITLE](/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)."

content/rest/overview/permissions-required-for-fine-grained-personal-access-tokens.md

@@ -3,7 +3,7 @@ title: Permissions required for fine-grained personal access tokens
 intro: 'You can find the required permissions for each {% data variables.product.pat_v2 %}-compatible endpoint.'
 versions:
   feature: pat-v2
-shortTitle: '{% data variables.product.pat_v2_caps %} permissions'
+shortTitle: 'Permissions for fine-grained PATs'
 ---
 
 ## About permissions required for {% data variables.product.pat_v2 %}

content/rest/overview/permissions-required-for-github-apps.md

@@ -11,7 +11,7 @@ versions:
   ghec: '*'
 topics:
   - API
-shortTitle: GitHub App permissions
+shortTitle: Permissions for GitHub Apps
 ---
 
 ## About {% data variables.product.prodname_github_app %} permissions

data/reusables/command_line/providing-token-as-password.md

@@ -1,9 +0,0 @@
-Once you have a token, you can enter it instead of your password when performing Git operations over HTTPS.
-
-For example, on the command line you would enter the following:
-
-```shell
-$ git clone https://{% data variables.command_line.codeblock %}/USERNAME/REPO.git
-Username: YOUR_USERNAME
-Password: YOUR_TOKEN
-```