Skip to content

Repo sync #27375

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Aug 10, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
4 changes: 4 additions & 0 deletions content/rest/overview/authenticating-to-the-rest-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`.
Expand All @@ -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 %}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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. -->
2 changes: 2 additions & 0 deletions content/rest/overview/permissions-required-for-github-apps.md
Original file line number Diff line number Diff line change
Expand Up @@ -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. -->
16 changes: 16 additions & 0 deletions content/rest/overview/troubleshooting.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 %}
6 changes: 6 additions & 0 deletions data/features/rest-permissions-header.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
# Issue 11209
versions:
fpt: '*'
ghec: '*'
ghes: '>=3.11'
ghae: '>=3.11'
5 changes: 5 additions & 0 deletions data/reusables/rest-api/permission-header.md
Original file line number Diff line number Diff line change
@@ -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 %}