Merge pull request #27375 from github/repo-sync

Repo sync

Author: docs-bot

content/apps/creating-github-apps/registering-a-github-app/choosing-permissions-for-a-github-app.md

@@ -54,6 +54,8 @@ For example, to use the `GET /orgs/{org}/dependabot/secrets` endpoint, your app
 
 If your app makes a REST API request with insufficient permissions, the API will return a `403` response.
 
+{% data reusables.rest-api.permission-header %}
+
 ## Choosing permissions for GraphQL API access
 
 For GraphQL requests, you should test your app to ensure that it has the required permissions for the GraphQL queries and mutations that you want to make.

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

@@ -39,6 +39,8 @@ If you try to use a REST API endpoint without a token or with a token that has i
 
 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 pat-v2 %}If you are using a {% data variables.product.pat_v2 %}, your {% data variables.product.pat_v2 %} requires specific permissions in order to access each REST API endpoint. For more information about the permissions that are required for each endpoint, see "[AUTOTITLE](/rest/overview/permissions-required-for-fine-grained-personal-access-tokens)." If you are using a {% data variables.product.pat_v1 %}, your {% else %}Your {% endif %}{% data variables.product.pat_v1 %} requires specific scopes in order to access each REST API endpoint. For general guidance about what scopes to choose, see "[AUTOTITLE](/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps#available-scopes)."
+
 {% 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`.
@@ -48,6 +50,8 @@ If you do not authorize your {% data variables.product.pat_v1 %} for SAML SSO be
 
 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)."
 
+Your {% data variables.product.prodname_github_app %} requires specific permissions in order to access each REST API endpoint. For more information about the permissions that are required for each endpoint, see "[AUTOTITLE](/rest/overview/permissions-required-for-github-apps)."
+
 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_apps %} 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 %}

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

@@ -11,6 +11,8 @@ autogenerated: github-apps
 
 When you create a {% data variables.product.pat_v2 %}, you grant it a set of permissions. Permissions define what resources the {% data variables.product.prodname_github_app %} can access via the API. For more information, see "[AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)."
 
+{% data reusables.rest-api.permission-header %}
+
 Some endpoints require additional permissions. When this is the case, the "Additional permissions" column will indicate the other permissions that are required to use the endpoint.
 
 <!-- The content of this page is rendered as a NextJS page component. -->

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

@@ -19,6 +19,8 @@ autogenerated: github-apps
 
 {% data variables.product.prodname_github_apps %} are created with a set of permissions. Permissions define what resources the {% data variables.product.prodname_github_app %} can access via the API. For more information, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/setting-permissions-for-github-apps)."
 
+{% data reusables.rest-api.permission-header %}
+
 Some endpoints require additional permissions. When this is the case, the "Additional permissions" column will indicate the other permissions that are required to use the endpoint.
 
 <!-- The content of this page is rendered as a NextJS page component. -->

content/rest/overview/troubleshooting.md

@@ -88,3 +88,19 @@ curl -H 'Authorization: Bearer YOUR-OAUTH-TOKEN' https://api.github.com/user/rep
 If  {% data variables.product.product_name %} takes more than 10 seconds to process an API request, {% data variables.product.product_name %} will terminate the request and you will receive a timeout response.
 
 {% endif %}
+
+{% ifversion rest-permissions-header %}
+
+## Insufficient permissions errors
+
+If you are using a {% data variables.product.prodname_github_app %}{% ifversion pat-v2 %} or {% data variables.product.pat_v2 %}{% endif %} and you receive an error due to your token having insufficient permissions, you can use the `X-Accepted-GitHub-Permissions` header to identify the permissions that are required to access the REST API endpoint.
+
+The value of the `X-Accepted-GitHub-Permissions` header is a comma separated list of the permissions that are required to use the endpoint. Occasionally, you can choose from multiple permission sets. In these cases, multiple comma separated lists will be separated by a semicolon.
+
+For example:
+
+- `X-Accepted-GitHub-Permissions: contents=read` means that your {% data variables.product.prodname_github_app %}{% ifversion pat-v2 %} or {% data variables.product.pat_v2 %}{% endif %} needs read access to the contents permission.
+- `X-Accepted-GitHub-Permissions: pull_requests=write,contents=read` means that your {% data variables.product.prodname_github_app %}{% ifversion pat-v2 %} or {% data variables.product.pat_v2 %}{% endif %} needs write access to the pull request permission and read access to the contents permission.
+- `X-Accepted-GitHub-Permissions: pull_requests=read,contents=read; issues=read,contents=read` means that your {% data variables.product.prodname_github_app %}{% ifversion pat-v2 %} or {% data variables.product.pat_v2 %}{% endif %} needs either read access to the pull request permission and read access to the contents permission, or read access to the issues permission and read access to the contents permission.
+
+{% endif %}

data/features/rest-permissions-header.yml

@@ -0,0 +1,6 @@
+# Issue 11209
+versions:
+  fpt: '*'
+  ghec: '*'
+  ghes: '>=3.11'
+  ghae: '>=3.11'

data/reusables/rest-api/permission-header.md

@@ -0,0 +1,5 @@
+{% ifversion rest-permissions-header %}
+
+To help you choose the correct permissions, you will receive the `X-Accepted-GitHub-Permissions` header in the REST API response. The header will tell you what permissions are required in order to access the endpoint. For more information, see "[AUTOTITLE](/rest/overview/troubleshooting#insufficient-permissions-errors)."
+
+{% endif %}