我们经常发布文档更新,此页面的翻译可能仍在进行中。有关最新信息,请访问英文文档。如果此页面上的翻译有问题,请告诉我们

此版本的 GitHub Enterprise 已停止服务 2020-11-12. 即使针对重大安全问题,也不会发布补丁。 要获得更好的性能、改进的安全性和新功能,请升级到 GitHub Enterprise 的最新版本。 如需升级方面的帮助,请联系 GitHub Enterprise 支持

Scopes for OAuth Apps

通过作用域,您可以准确指定所需的访问权限类型。 作用域限制 OAuth 令牌的访问权限。 它们不会授予超出用户权限范围的任何额外权限。

本文内容

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

Check headers to see what OAuth scopes you have, and what the API action accepts:

$ curl -H "Authorization: token OAUTH-TOKEN" http(s)://[hostname]/api/v3/users/codertocat -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.

Available scopes

名称描述
(no scope)Grants read-only access to public information (includes public user profile info, public repository info, and gists)
site_adminGrants site administrators access to GitHub Enterprise Server Administration API endpoints.
repoGrants full access to private and public 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 public and private repositories and organizations. Also grants ability to manage user projects.
repo:statusGrants 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_deploymentGrants 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.
public_repoLimits 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.
repo:inviteGrants 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.
admin:repo_hookGrants read, write, ping, and delete access to repository hooks in public and private repositories. The repo and public_repo scopes grants full access to repositories, including repository hooks. Use the admin:repo_hook scope to limit access to only repository hooks.
write:repo_hookGrants read, write, and ping access to hooks in public or private repositories.
read:repo_hookGrants read and ping access to hooks in public or private repositories.
admin:orgFully manage the organization and its teams, projects, and memberships.
write:orgRead and write access to organization membership, organization projects, and team membership.
read:orgRead-only access to organization membership, organization projects, and team membership.
admin:public_keyFully manage public keys.
write:public_keyCreate, list, and view details for public keys.
read:public_keyList and view details for public keys.
admin:org_hookGrants 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.
gistGrants write access to gists.
通知Grants:
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 user:email and user:follow.
read:userGrants access to read a user's profile data.
user:emailGrants read access to a user's email addresses.
user:followGrants access to follow or unfollow other users.
delete_repoGrants access to delete adminable repositories.
write:discussionAllows read and write access for team discussions.
read:discussionAllows read access for team discussions.
admin:gpg_keyFully manage GPG keys.
write:gpg_keyCreate, list, and view details for GPG keys.
read:gpg_keyList and view details for 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.