|
| 1 | +--- |
| 2 | +title: Choosing permissions for a GitHub App |
| 3 | +shortTitle: Permissions |
| 4 | +intro: "The permissions of a GitHub App determine what the app can do with {% data variables.product.company_short %}'s APIs and what webhooks the app can receive." |
| 5 | +redirect_from: |
| 6 | + - /apps/building-integrations/setting-up-and-registering-github-apps/about-permissions-for-github-apps |
| 7 | + - /apps/building-github-apps/permissions-for-github-apps |
| 8 | + - /apps/building-github-apps/setting-permissions-for-github-apps |
| 9 | + - /developers/apps/setting-permissions-for-github-apps |
| 10 | + - /developers/apps/building-github-apps/setting-permissions-for-github-apps |
| 11 | + - /apps/creating-github-apps/creating-github-apps/setting-permissions-for-github-apps |
| 12 | +versions: |
| 13 | + fpt: '*' |
| 14 | + ghes: '*' |
| 15 | + ghae: '*' |
| 16 | + ghec: '*' |
| 17 | +topics: |
| 18 | + - GitHub Apps |
| 19 | +--- |
| 20 | + |
| 21 | +## About {% data variables.product.prodname_github_app %} permissions |
| 22 | + |
| 23 | +{% data variables.product.prodname_github_app %}s don't have any permissions by default. When you create an app, you can select permissions for the app. The permissions that you select determine what the app can do with {% data variables.product.company_short %}'s APIs and what webhooks the app can subscribe to. You should select the minimum permissions required for the app. |
| 24 | + |
| 25 | +App permissions are classified as repository, organization, or account permissions. Repository permissions allow your app to access resources related to repositories that are owned by the account where the app is installed. Organization permissions allow your app to access resources related to the organization where the app is installed, if it is installed on an organization account. Account permissions allow your app to access resources related to a user if the user has also authorized your app. For more information about user authorization of apps, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-a-github-app-on-behalf-of-a-user)." |
| 26 | + |
| 27 | +When a user installs an app on their account or organization, they see and grant the repository and organization permissions that the app requested. They will also see a list of account permissions that the app can request for individual users. When a user authorizes an app to act on their behalf, they will see and grant the account permissions that the app requested. |
| 28 | + |
| 29 | +You can modify the permissions for your app at any time. When you modify the permissions, the owner of each account where the app was installed will be prompted to approve the new permissions. If the account owner does not approve the new permissions, their installation will continue to use the old permissions. |
| 30 | + |
| 31 | +Some webhooks and API access requires "Administration" permissions. If your app requires "Administration" permissions, consider explaining this requirement on your app's homepage. This will help users understand why your app needs a high level permission. |
| 32 | + |
| 33 | +For more information about specifying permissions during app creation, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/creating-a-github-app)." For more information about modifying permissions, see "[AUTOTITLE](/apps/maintaining-github-apps/editing-a-github-apps-permissions)." |
| 34 | + |
| 35 | +## Choosing permissions for webhook access |
| 36 | + |
| 37 | +The webhook documentation indicates whether each webhook is available to {% data variables.product.prodname_github_app %}s. For each webhook that you want to subscribe to, refer to the webhook documentation to see what permissions a {% data variables.product.prodname_github_app %} needs to subscribe to that webhook. For more information, see "[AUTOTITLE](/webhooks-and-events/webhooks/webhook-events-and-payloads)." |
| 38 | + |
| 39 | +For example, if you want your app to subscribe to `team` events, your app must have the "Members" organization permission. |
| 40 | + |
| 41 | +On your app settings page, the available webhook events will change as you change your app's permissions. If you did not select sufficient permissions for your app to subscribe to an event, the event will not appear as an option on your app settings page. |
| 42 | + |
| 43 | +## Choosing permissions for REST API access |
| 44 | + |
| 45 | +For more information about which REST API endpoints you can access with each permission, see "[AUTOTITLE](/rest/overview/permissions-required-for-github-apps)." Some endpoints may require multiple permissions, and some endpoints may require one of multiple permissions. For more information, see the documentation for the endpoint. |
| 46 | + |
| 47 | +For example, to use the `GET /orgs/{org}/dependabot/secrets` endpoint, your app must have at least read-level permission for the "organization dependabot secrets" permission. |
| 48 | + |
| 49 | +The success of an API request with a user access token depends on the user's permissions as well as the app's permissions. For example, if the app was granted permission to write the contents of a repository, but the user can only read the contents, then the user access token can only read the contents. The success of an API request with an installation access token only depends on the app's permissions. |
| 50 | + |
| 51 | +If your app makes a REST API request with insufficient permissions, the API will return a `403` response. |
| 52 | + |
| 53 | +## Choosing permissions for GraphQL API access |
| 54 | + |
| 55 | +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. |
| 56 | + |
| 57 | +The success of an API request with a user access token depends on the user's permissions as well as the app's permissions. For example, if the app was granted permission to write the contents of a repository, but the user can only read the contents, then the user access token can only read the contents. The success of an API request with an installation access token only depends on the app's permissions. |
| 58 | + |
| 59 | +If your app makes a GraphQL API query or mutation with insufficient permissions, the API will return a `401` response. |
| 60 | + |
| 61 | +## Choosing permissions for Git access |
| 62 | + |
| 63 | +If you want your app to use an installation access token to authenticate for HTTP-based Git access, you should request the "Contents" repository permission. |
| 64 | + |
| 65 | +You can then use the installation access token as the HTTP password. Replace `TOKEN` with the installation access token: |
| 66 | + |
| 67 | +``` |
| 68 | +git clone https://x-access-token:[email protected]/owner/repo.git" |
| 69 | +``` |
0 commit comments