{"meta":{"title":"Choosing permissions for a GitHub App","intro":"The permissions of a GitHub App determine what the app can do with GitHub's APIs and what webhooks the app can receive.","product":"Apps","breadcrumbs":[{"href":"/en/apps","title":"Apps"},{"href":"/en/apps/creating-github-apps","title":"Creating GitHub Apps"},{"href":"/en/apps/creating-github-apps/registering-a-github-app","title":"Registering a GitHub App"},{"href":"/en/apps/creating-github-apps/registering-a-github-app/choosing-permissions-for-a-github-app","title":"Permissions"}],"documentType":"article"},"body":"# Choosing permissions for a GitHub App\n\nThe permissions of a GitHub App determine what the app can do with GitHub's APIs and what webhooks the app can receive.\n\n## About GitHub App permissions\n\nGitHub Apps don't have any permissions by default. When you register a GitHub App, you can select permissions for the app. The permissions that you select determine what the app can do with GitHub's APIs and what webhooks the app can subscribe to. You should select the minimum permissions required for the app.\n\nAlthough GitHub Apps don't have any permissions by default, they do have implicit permissions to read public resources when acting on behalf of a user. When a user authorizes the app to act on their behalf, the GitHub App can use the resulting user access token to make requests to the REST API and the GraphQL API to read public resources. To learn more about acting on behalf of a user, see [Authenticating with a GitHub App on behalf of a user](/en/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-a-github-app-on-behalf-of-a-user).\n\nApp permissions are classified as repository, organization, enterprise, or account permissions.\n\n* Repository permissions allow your app to access resources related to repositories that are owned by the account where the app is installed.\n* 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.\n* Enterprise permissions allow the app to manage an enterprise, if it is installed on an enterprise account.\n* 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 [Authenticating with a GitHub App on behalf of a user](/en/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-a-github-app-on-behalf-of-a-user).\n\nAny user, organization, or enterprise can create an app using any of the permission types. An app with enterprise permissions must be `public` or `internal` to be installed on an enterprise account. A `public` app can be installed by any enterprise, while an `internal` app can only be installed by the enterprise that owns the app or the enterprise of the organization that owns the app. There are no additional restrictions on which organizations or personal accounts an app can be installed on.\n\nThere is one exception to installing an app across enterprises. If an app requests the \"Enterprise organization installations\" or \"Enterprise organization installation repositories\" permissions, the only enterprise that can install it is the one that owns the app. You cannot install the app on another enterprise, and you cannot add either permission to an app that is already installed on an enterprise other than the one that owns it.\n\nWhen a user installs an app on their user account or organization, they see and grant the repository and organization permissions that the app requested. When they install it on their enterprise, they see and grant only the enterprise 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.\n\nThe 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.\n\nFor more information about specifying permissions during GitHub App registration, see [Registering a GitHub App](/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app).\n\nSome 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.\n\n## About changes to permissions\n\nYou can modify the permissions for apps you own or manage at any time. When you do so, 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.\n\nFor more information about modifying permissions, see [Modifying a GitHub App registration](/en/apps/maintaining-github-apps/modifying-a-github-app-registration).\n\n## Choosing permissions for webhook access\n\nThe webhook documentation indicates whether each webhook is available to GitHub Apps. For each webhook that you want to subscribe to, refer to the webhook documentation to see what permissions a GitHub App needs to subscribe to that webhook. For more information, see [Webhook events and payloads](/en/webhooks/webhook-events-and-payloads).\n\nFor example, if you want your app to subscribe to `team` events, your app must have the \"Members\" organization permission.\n\nOn your GitHub App registration page, the available webhook events will change as you change your app's permissions. If you did not select sufficient permissions for your GitHub App to subscribe to an event, the event will not appear as an option on your app registration page.\n\n## Choosing permissions for REST API access\n\nThe REST API reference documentation for each endpoint states whether the endpoint works with GitHub Apps and states what permissions are required in order for the app to use the endpoint. Some endpoints may require multiple permissions, and some endpoints may require one of multiple permissions. For an overview of which REST API endpoints a GitHub App can access with each permission, see [Permissions required for GitHub Apps](/en/rest/authentication/permissions-required-for-github-apps).\n\nFor 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.\n\nIf your app makes a REST API request with insufficient permissions, the API will return a `403` response.\n\nTo 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 [Troubleshooting the REST API](/en/rest/using-the-rest-api/troubleshooting-the-rest-api#resource-not-accessible).\n\n## Choosing permissions for GraphQL API access\n\nFor 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.\n\nIf your app makes a GraphQL API query or mutation with insufficient permissions, the API will return a `401` response.\n\n## Choosing permissions for Git access\n\nIf you want your app to use an installation or user access token to authenticate for HTTP-based Git access, you should request the \"Contents\" repository permission. If your app specifically needs to access or edit Actions files in the `.github/workflows` directory, request the \"Workflows\" repository permission.\n\nYou can then use the access token as the HTTP password. Replace `TOKEN` with the access token:\n\n```shell\ngit clone https://x-access-token:TOKEN@github.com/owner/repo.git\n```"}