About scopes for OAuth Apps

Scopes let you specify exactly what type of access you need. Scopes limit access for OAuth tokens. They do not grant any additional permission beyond that which the user already has.

When setting up an OAuth App on GitHub, requested scopes are displayed to the user on the authorize form.

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/technoweenie -I
HTTP/1.1 200 OK
X-OAuth-Scopes: repo, user
X-Accepted-OAuth-Scopes: user

X-OAuth-Scopes lists the scopes your token has authorized. X-Accepted-OAuth-Scopes lists the scopes that the action checks for.

Name Description
(no scope) Grants read-only access to public information (includes public user profile info, public repository info, and gists)
user Grants read/write access to profile info only. Note that this scope includes user:email and user:follow.
user:email Grants read access to a user's email addresses.
user:follow Grants access to follow or unfollow other users.
public_repo Grants read/write access to code, commit statuses, collaborators, and deployment statuses for public repositories and organizations. Also required for starring public repositories.
repo Grants read/write access to code, commit statuses, invitations, collaborators, adding team memberships, and deployment statuses for public and private repositories and organizations.
repo_deployment 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.
repo:status 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.
repo:invite 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.
delete_repo Grants access to delete adminable repositories.
notifications Grants read access to a user's notifications. repo also provides this access.
gist Grants write access to gists.
read:repo_hook Grants read and ping access to hooks in public or private repositories.
write:repo_hook Grants read, write, and ping access to hooks in public or private repositories.
admin:repo_hook Grants read, write, ping, and delete access to hooks in public or private repositories.
admin:org_hook 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.
read:org Read-only access to organization, teams, and membership.
write:org Publicize and unpublicize organization membership.
admin:org Fully manage organization, teams, and memberships.
read:public_key List and view details for public keys.
write:public_key Create, list, and view details for public keys.
admin:public_key Fully manage public keys.
read:gpg_key List and view details for GPG keys.
write:gpg_key Create, list, and view details for GPG keys.
admin:gpg_key Fully manage GPG keys.

Note: Your OAuth App can request the scopes in the initial redirection. You can specify multiple scopes by separating them with a space:

https://github.com/login/oauth/authorize?
  client_id=...&
  scope=user%20public_repo

Requested scopes and granted scopes

The 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.

Normalized 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 user and gist scopes only since the access granted with user:email scope is included in the user scope.