When setting up an OAuth App on GitHub, requested scopes are displayed to the user on the authorization form.
Note: If you're building a GitHub App, you don’t need to provide scopes in your authorization request. For more on this, see "Identifying and authorizing users for GitHub Apps."
If your OAuth App doesn't have access to a browser, such as a CLI tool, then you don't need to specify a scope for users to authenticate to your app. For more information, see "Authorizing OAuth apps."
Check headers to see what OAuth scopes you have, and what the API action accepts:
$ curl -H "Authorization: token OAUTH-TOKEN" https://api.github.com/users/codertocat -I HTTP/1.1 200 OK X-OAuth-Scopes: repo, user X-Accepted-OAuth-Scopes: user
X-OAuth-Scopeslists the scopes your token has authorized.
X-Accepted-OAuth-Scopeslists the scopes that the action checks for.
|Grants read-only access to public information (including user profile info, repository info, and gists)|
|Grants full access to repositories, including private repositories. That includes read/write access to code, commit statuses, repository and organization projects, invitations, collaborators, adding team memberships, deployment statuses, and repository webhooks for repositories and organizations. Also grants ability to manage user projects.|
| ||Grants read/write access to public and private repository commit statuses. This scope is only necessary to grant other users or services access to private repository commit statuses without granting access to the code.|
| ||Grants access to deployment statuses for public and private repositories. This scope is only necessary to grant other users or services access to deployment statuses, without granting access to the code.|
| ||Limits access to public repositories. That includes read/write access to code, commit statuses, repository projects, collaborators, and deployment statuses for public repositories and organizations. Also required for starring public repositories.|
| ||Grants accept/decline abilities for invitations to collaborate on a repository. This scope is only necessary to grant other users or services access to invites without granting access to the code.|
| ||Grants: |
read and write access to security events in the code scanning API
read and write access to security events in the secret scanning API
This scope is only necessary to grant other users or services access to security events without granting access to the code.
|Grants read, write, ping, and delete access to repository hooks in public and private repositories. The |
| ||Grants read, write, and ping access to hooks in public or private repositories.|
| ||Grants read and ping access to hooks in public or private repositories.|
|Fully manage the organization and its teams, projects, and memberships.|
| ||Read and write access to organization membership, organization projects, and team membership.|
| ||Read-only access to organization membership, organization projects, and team membership.|
|Fully manage public keys.|
| ||Create, list, and view details for public keys.|
| ||List and view details for public keys.|
|Grants read, write, ping, and delete access to organization hooks. Note: OAuth tokens will only be able to perform these actions on organization hooks which were created by the OAuth App. Personal access tokens will only be able to perform these actions on organization hooks created by a user.|
|Grants write access to gists.|
read access to a user's notifications
mark as read access to threads
watch and unwatch access to a repository, and
read, write, and delete access to thread subscriptions.
|Grants read/write access to profile info only. Note that this scope includes |
| ||Grants access to read a user's profile data.|
| ||Grants read access to a user's email addresses.|
| ||Grants access to follow or unfollow other users.|
|Grants access to delete adminable repositories.|
|Allows read and write access for team discussions.|
| ||Allows read access for team discussions.|
|Grants access to upload or publish a package in GitHub Packages. For more information, see "Publishing a package".|
|Grants access to download or install packages from GitHub Packages. For more information, see "Installing a package".|
|Grants access to delete packages from GitHub Packages. For more information, see "Deleting and restoring a package."|
|Fully manage GPG keys.|
| ||Create, list, and view details for GPG keys.|
| ||List and view details for GPG keys.|
|Grants the ability to add and update GitHub Actions workflow files. Workflow files can be committed without this scope if the same file (with both the same path and contents) exists on another branch in the same repository. Workflow files can expose |
Note: Your OAuth App can request the scopes in the initial redirection. You can specify multiple scopes by separating them with a space using
https://github.com/login/oauth/authorize? client_id=...& scope=user%20repo_deployment
scope attribute lists scopes attached to the token that were granted by the user. Normally, these scopes will be identical to what you requested. However, users can edit their scopes, effectively granting your application less access than you originally requested. Also, users can edit token scopes after the OAuth flow is completed. You should be aware of this possibility and adjust your application's behavior accordingly.
It's important to handle error cases where a user chooses to grant you less access than you originally requested. For example, applications can warn or otherwise communicate with their users that they will see reduced functionality or be unable to perform some actions.
Also, applications can always send users back through the flow again to get additional permission, but don’t forget that users can always say no.
Check out the Basics of Authentication guide, which provides tips on handling modifiable token scopes.
When requesting multiple scopes, the token is saved with a normalized list of scopes, discarding those that are implicitly included by another requested scope. For example, requesting
user,gist,user:email will result in a token with
gist scopes only since the access granted with
user:email scope is included in the