Skip to content

Commit 0c05290

Browse files
authored
Merge pull request #27375 from github/repo-sync
Repo sync
2 parents e8637f1 + 5e5b8a8 commit 0c05290

File tree

7 files changed

+37
-0
lines changed

7 files changed

+37
-0
lines changed

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,8 @@ For example, to use the `GET /orgs/{org}/dependabot/secrets` endpoint, your app
5454

5555
If your app makes a REST API request with insufficient permissions, the API will return a `403` response.
5656

57+
{% data reusables.rest-api.permission-header %}
58+
5759
## Choosing permissions for GraphQL API access
5860

5961
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

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,8 @@ If you try to use a REST API endpoint without a token or with a token that has i
3939

4040
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)."
4141

42+
{% 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)."
43+
4244
{% 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)."
4345

4446
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
4850

4951
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)."
5052

53+
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)."
54+
5155
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.
5256

5357
{% 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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,8 @@ autogenerated: github-apps
1111

1212
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)."
1313

14+
{% data reusables.rest-api.permission-header %}
15+
1416
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.
1517

1618
<!-- The content of this page is rendered as a NextJS page component. -->

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,8 @@ autogenerated: github-apps
1919

2020
{% 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)."
2121

22+
{% data reusables.rest-api.permission-header %}
23+
2224
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.
2325

2426
<!-- The content of this page is rendered as a NextJS page component. -->

content/rest/overview/troubleshooting.md

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -88,3 +88,19 @@ curl -H 'Authorization: Bearer YOUR-OAUTH-TOKEN' https://api.github.com/user/rep
8888
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.
8989

9090
{% endif %}
91+
92+
{% ifversion rest-permissions-header %}
93+
94+
## Insufficient permissions errors
95+
96+
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.
97+
98+
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.
99+
100+
For example:
101+
102+
- `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.
103+
- `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.
104+
- `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.
105+
106+
{% endif %}
Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# Issue 11209
2+
versions:
3+
fpt: '*'
4+
ghec: '*'
5+
ghes: '>=3.11'
6+
ghae: '>=3.11'
Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
{% ifversion rest-permissions-header %}
2+
3+
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)."
4+
5+
{% endif %}

0 commit comments

Comments
 (0)