Update REST API authentication article (#35376)

Co-authored-by: Jess Hosman <1183847+jhosman@users.noreply.github.com>

content/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps.md

@@ -256,17 +256,7 @@ For more information, see the "[OAuth 2.0 Device Authorization Grant](https://to
 
 ## Non-Web application flow
 
-Non-web authentication is available for limited situations like testing. If you need to, you can use [Basic Authentication](/rest/overview/other-authentication-methods#basic-authentication) to create a {% data variables.product.pat_generic %} using your [{% data variables.product.pat_generic %}s settings page](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token). This technique enables the user to revoke access at any time.
-
-{% ifversion fpt or ghes or ghec %}
-{% note %}
-
-**Note:** When using the non-web application flow to create an OAuth2 token, make sure to understand how to [work with
-two-factor authentication](/rest/overview/other-authentication-methods#working-with-two-factor-authentication) if
-you or your users have two-factor authentication enabled.
-
-{% endnote %}
-{% endif %}
+Non-web authentication is available for limited situations like testing. If you need to, you can use [Basic Authentication](/rest/overview/authenticating-to-the-rest-api#using-basic-authentication) to create a {% data variables.product.pat_generic %} using your [{% data variables.product.pat_generic %}s settings page](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token). This technique enables the user to revoke access at any time.
 
 ## Redirect URLs
 

content/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token.md

@@ -28,7 +28,7 @@ shortTitle: 'Create a {% data variables.product.pat_generic %}'
 
 ## About {% data variables.product.pat_generic %}s
 
-{% data variables.product.pat_generic_caps %}s 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).
+{% data variables.product.pat_generic_caps %}s are an alternative to using passwords for authentication to {% data variables.product.product_name %} when using the [GitHub API](/rest/overview/authenticating-to-the-rest-api) or the [command line](#using-a-token-on-the-command-line).
 
 {% data variables.product.pat_generic_caps %}s are intended to access {% data variables.product.company_short %} resources on behalf of yourself. To access resources on behalf of an organization, or for long-lived integrations, you should use a {% data variables.product.prodname_github_app %}. For more information, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/about-apps)."
 

content/rest/enterprise-admin/admin-stats.md

@@ -12,7 +12,7 @@ autogenerated: rest
 
 ## About admin stats
 
-These endpoints are only available to [authenticated](/rest/overview/resources-in-the-rest-api#authentication) site administrators. Normal users will receive a `404` response.
+These endpoints are only available to [authenticated](/rest/overview/authenticating-to-the-rest-api) site administrators. Normal users will receive a `404` response.
 
 {% data reusables.user-settings.enterprise-admin-api-classic-pat-only %}
 

content/rest/enterprise-admin/global-webhooks.md

@@ -11,7 +11,7 @@ autogenerated: rest
 
 ## About global webhooks
 
-These endpoints are only available to [authenticated](/rest/overview/resources-in-the-rest-api#authentication) site administrators Normal users will receive a `404` response. To learn how to configure global webhooks, see [About global webhooks](/admin/monitoring-activity-in-your-enterprise/exploring-user-activity/managing-global-webhooks).
+These endpoints are only available to [authenticated](/rest/overview/authenticating-to-the-rest-api) site administrators Normal users will receive a `404` response. To learn how to configure global webhooks, see [About global webhooks](/admin/monitoring-activity-in-your-enterprise/exploring-user-activity/managing-global-webhooks).
 
 Global webhooks are automatically installed on your enterprise. You can use global webhooks to automatically monitor, respond to, or enforce rules for users, organizations, teams, and repositories on your enterprise.
 

content/rest/enterprise-admin/index.md

@@ -67,10 +67,11 @@ http(s)://HOSTNAME/
 {% ifversion ghae or ghes %}
 ## Authentication
 
-Your {% data variables.product.product_name %} installation's API endpoints accept [the same authentication methods](/rest/overview/resources-in-the-rest-api#authentication) as the {% data variables.product.prodname_dotcom %} API. You can authenticate yourself with [OAuth tokens](/apps/oauth-apps/building-oauth-apps) {% ifversion ghes %}(which can be created using the [Authorizations API](/rest/oauth-authorizations#create-a-new-authorization)) {% endif %}or [basic authentication](/rest/overview/resources-in-the-rest-api#basic-authentication). {% ifversion ghes %}
-OAuth tokens must have the `site_admin` [OAuth scope](/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps#available-scopes) when used with Enterprise-specific endpoints.{% endif %}
+Your {% data variables.product.product_name %} installation's API endpoints accept the same authentication methods as the {% data variables.product.prodname_dotcom %} API. For more information, see "[AUTOTITLE](/rest/overview/authenticating-to-the-rest-api)."
 
-These endpoints are only accessible to authenticated {% data variables.product.product_name %} site administrators{% ifversion ghes %}, except for the [Management Console](#management-console) endpoints, which requires the [Management Console password](/admin/configuration/administering-your-instance-from-the-management-console){% endif %}.
+{% ifversion ghes %}OAuth tokens must have the `site_admin` [OAuth scope](/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps#available-scopes) when used with Enterprise-specific endpoints.{% endif %}
+
+These endpoints are only accessible to authenticated {% data variables.product.product_name %} site administrators{% ifversion ghes %}, except for the [Management Console](/rest/enterprise-admin/management-console) endpoints, which requires the [Management Console password](/admin/configuration/administering-your-instance-from-the-management-console){% endif %}.
 
 {% endif %}
 

content/rest/enterprise-admin/license.md

@@ -10,7 +10,7 @@ topics:
 autogenerated: rest
 ---
 
-These endpoints are only available to [authenticated](/rest/overview/resources-in-the-rest-api#authentication) site administrators. Normal users will receive a `404` response.
+These endpoints are only available to [authenticated](/rest/overview/authenticating-to-the-rest-api) site administrators. Normal users will receive a `404` response.
 
 {% data reusables.user-settings.enterprise-admin-api-classic-pat-only %}
 

content/rest/enterprise-admin/orgs.md

@@ -12,7 +12,7 @@ autogenerated: rest
 
 ## About organization administration
 
-These endpoints are only available to [authenticated](/rest/overview/resources-in-the-rest-api#authentication) site administrators. Normal users will receive a `404` response.
+These endpoints are only available to [authenticated](/rest/overview/authenticating-to-the-rest-api) site administrators. Normal users will receive a `404` response.
 
 {% data reusables.user-settings.enterprise-admin-api-classic-pat-only %}
 

content/rest/enterprise-admin/pre-receive-environments.md

@@ -13,7 +13,7 @@ autogenerated: rest
 
 ## About pre-receive environments
 
-These endpoints are only available to [authenticated](/rest/overview/resources-in-the-rest-api#authentication) site administrators. Normal users will receive a `404` response.
+These endpoints are only available to [authenticated](/rest/overview/authenticating-to-the-rest-api) site administrators. Normal users will receive a `404` response.
 
 {% data reusables.user-settings.enterprise-admin-api-classic-pat-only %}
 

content/rest/enterprise-admin/pre-receive-hooks.md

@@ -10,7 +10,7 @@ autogenerated: rest
 
 ## About pre-receive hooks
 
-These endpoints are only available to [authenticated](/rest/overview/resources-in-the-rest-api#authentication) site administrators. Normal users will receive a `404` response.
+These endpoints are only available to [authenticated](/rest/overview/authenticating-to-the-rest-api) site administrators. Normal users will receive a `404` response.
 
 {% data reusables.user-settings.enterprise-admin-api-classic-pat-only %}
 

content/rest/enterprise-admin/users.md

@@ -14,7 +14,7 @@ autogenerated: rest
 
 ## About user administration
 
-These endpoints are only available to [authenticated](/rest/overview/resources-in-the-rest-api#authentication) site administrators. Normal users will receive a `403` response.
+These endpoints are only available to [authenticated](/rest/overview/authenticating-to-the-rest-api) site administrators. Normal users will receive a `403` response.
 
 {% data reusables.user-settings.enterprise-admin-api-classic-pat-only %}
 

content/rest/migrations/orgs.md

@@ -18,7 +18,7 @@ autogenerated: rest
 
 ## About organization migrations
 
-These endpoints are only available to authenticated organization owners. For more information, see "[AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization#permission-levels-for-an-organization)" and "[AUTOTITLE](/rest/overview/other-authentication-methods)."
+These endpoints are only available to authenticated organization owners. For more information, see "[AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization#permission-levels-for-an-organization)" and "[AUTOTITLE](/rest/overview/authenticating-to-the-rest-api)."
 
 {% data variables.migrations.organization_migrations_intro %}
 

content/rest/migrations/users.md

@@ -17,7 +17,7 @@ autogenerated: rest
 
 ## About user migrations
 
-These endpoints are only available to authenticated account owners. For more information, see "[AUTOTITLE](/rest/overview/other-authentication-methods)".
+These endpoints are only available to authenticated account owners. For more information, see "[AUTOTITLE](/rest/overview/authenticating-to-the-rest-api)".
 
 {% data variables.migrations.user_migrations_intro %} For a list of migration data that you can download, see "[Download a user migration archive](#download-a-user-migration-archive)."
 

content/rest/oauth-authorizations.md

@@ -12,9 +12,6 @@ autogenerated: rest
 
 ## About OAuth authorizations
 
-You can use the REST API to manage the access OAuth applications have to your account. You can only access these endpoints via [Basic Authentication](/rest/overview/other-authentication-methods#basic-authentication) using your username and password, not tokens.
-
-If you or your users have two-factor authentication enabled, make sure you understand how to [work with two-factor authentication](/rest/overview/other-authentication-methods#working-with-two-factor-authentication).
-
+You can use the REST API to manage the access OAuth applications have to your account. You can only access these endpoints via basic authentication using your username and password, not tokens.
 
 <!-- Content after this section is automatically generated -->

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

@@ -0,0 +1,91 @@
+---
+title: Authenticating to the REST API
+intro: You can authenticate to the REST API to access more endpoints and have a higher rate limit.
+redirect_from:
+  - /v3/auth
+  - /rest/overview/other-authentication-methods
+versions:
+  fpt: '*'
+  ghes: '*'
+  ghae: '*'
+  ghec: '*'
+topics:
+  - API
+shortTitle: Authenticating
+---
+
+## About authentication
+
+Many REST API endpoints require authentication or return additional information if you are authenticated. Additionally, you can make more requests per hour when you are authenticated.
+
+You can authenticate your request by sending a token in the `Authorization` header of your request. In the following example, replace `YOUR-TOKEN` with a reference to your token:
+
+```shell
+curl --request GET \
+--url "{% data variables.product.api_url_code %}/octocat" \
+--header "Authorization: Bearer YOUR-TOKEN"{% ifversion api-date-versioning %}\
+--header "X-GitHub-Api-Version: {{ allVersions[currentVersion].latestApiVersion }}"{% endif %}
+```
+
+{% note %}
+
+**Note:** {% data reusables.getting-started.bearer-vs-token %}
+
+{% endnote %}
+
+If you try to use a REST API endpoint without a token or with a token that has insufficient permissions, you will receive a `404 Not Found` or `403 Forbidden` response.
+
+## Authenticating with a {% data variables.product.pat_generic %}
+
+If you want to use the {% data variables.product.company_short %} REST API for personal use, you can create a {% data variables.product.pat_generic %}.{% ifversion pat-v2 %} If possible, {% data variables.product.company_short %} recommends that you use a {% data variables.product.pat_v2 %} instead of a {% data variables.product.pat_v1 %}.{% endif %} For more information about creating a {% data variables.product.pat_generic %}, see "[AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)."
+
+{% ifversion fpt or ghec %}If you use a {% data variables.product.pat_v1 %} to access an organization that enforces SAML single sign-on (SSO) for authentication, you will need to authorize your token after creation.{% ifversion pat-v2 %} {% data variables.product.pat_v2_caps %}s are authorized during token creation, before access to the organization is granted.{% endif %} For more information, see "[AUTOTITLE](/authentication/authenticating-with-saml-single-sign-on/authorizing-a-personal-access-token-for-use-with-saml-single-sign-on)."
+
+If you do not authorize your {% data variables.product.pat_v1 %} for SAML SSO before you try to use it to access an organization that enforces SAML SSO, you may receive a `404 Not Found` or a `403 Forbidden` error. If you receive a `403 Forbidden` error, you can follow the URL in the `X-GitHub-SSO` header to authorize your token. The URL expires after one hour. If you requested data that could come from multiple organizations, the API will not return results from the organizations that require SAML SSO. The `X-GitHub-SSO` header will indicate the ID of the organizations that require SAML SSO authorization of your {% data variables.product.pat_v1 %}. For example: `X-GitHub-SSO: partial-results; organizations=21955855,20582480`.
+{% endif %}
+
+## Authenticating with a token generated by an app
+
+If you want to use the API for an organization or on behalf of another user, {% data variables.product.company_short %} recommends that you use a {% data variables.product.prodname_github_app %}. For more information, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/about-authentication-with-a-github-app)."
+
+You can also create an OAuth token with an {% data variables.product.prodname_oauth_app %} to access the REST API. However, {% data variables.product.company_short %} recommends that you use a {% data variables.product.prodname_github_app %} instead. {% data variables.product.prodname_github_app %}s allow more control over the access and permission that the app has.
+
+{% ifversion fpt or ghec %}Access tokens created by apps are automatically authorized for SAML SSO.{% endif %}
+
+### Using basic authentication
+
+Some REST API endpoints for {% data variables.product.prodname_github_app %}s and {% data variables.product.prodname_oauth_app %}s require you to use basic authentication to access the endpoint. You will use the app's client ID as the username and the app's client secret as the password.
+
+For example:
+
+```shell
+curl --request POST \
+--url "{% data variables.product.api_url_code %}/authorizations"
+--user CLIENT_ID:CLIENT_SECRET{% ifversion api-date-versioning %}\
+--header "X-GitHub-Api-Version: {{ allVersions[currentVersion].latestApiVersion }}"{% endif %}
+```
+
+You can find the client ID and generate a client secret on the settings page for your app. For user-owned {% data variables.product.prodname_github_app %}s, the settings page is `https://github.com/settings/apps/APP-SLUG`. For organization-owned {% data variables.product.prodname_github_app %}s, the settings page is `https://github.com/organizations/ORGANIZATION/settings/apps/APP-SLUG`. Replace `APP-SLUG` with the sluggified name of your app and `ORGANIZATION` with the sluggified name of your organization. For example, `https://github.com/organizations/octo-org/settings/apps/octo-app`.
+
+## Authenticating 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)."
+
+## Authenticating with username and password
+
+{% ifversion ghes %}
+
+{% data variables.product.company_short %} recommends that you use a token to authenticate to the REST API instead of your password. You have more control over what a token can do, and you can revoke a token at anytime. However, you can also authenticate to the REST API using your username and password for basic authentication. To do so, you will pass your username and password with the `--user` option:
+
+```shell
+curl --request GET \
+--url "{% data variables.product.api_url_code %}/user"
+--user USERNAME:PASSWORD{% ifversion api-date-versioning %}\
+--header "X-GitHub-Api-Version: {{ allVersions[currentVersion].latestApiVersion }}"{% endif %}
+```
+
+{% else %}
+
+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 %}

content/rest/overview/index.md

@@ -14,7 +14,7 @@ children:
   - /resources-in-the-rest-api
   - /api-versions
   - /media-types
-  - /other-authentication-methods
+  - /authenticating-to-the-rest-api
   - /troubleshooting
   - /libraries
   - /openapi-description
@@ -26,3 +26,4 @@ children:
 redirect_from:
   - /developers/overview
 ---
+