在 GitHub 上设置 OAuth 应用程序时,请求的作用域会在授权表单上显示给用户。
注 :如果您在构建 GitHub 应用程序,则不需要在授权请求中提供作用域。 更多信息请参阅“识别和授权 GitHub 应用程序用户”。
检查标头以查看您拥有哪些 OAuth 作用域,以及 API 操作接受什么:
$ 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
列出令牌已授权的作用域。X-Accepted-OAuth-Scopes
列出操作检查的作用域。
可用作用域
名称 | 描述 |
---|---|
(无作用域) | 授予对公共信息的只读访问权限(包括公开的用户个人资料、公共仓库信息和 gist) |
site_admin | 授予站点管理员对 GitHub Enterprise Server 管理 API 端点的访问权限。 |
repo | 授予对私有和公共仓库的完全访问权限。 这包括对公共和私有仓库及组织的代码、提交状态、仓库和组织项目、邀请、协作者、添加团队成员身份、部署状态以及仓库 web 挂钩的读取/写入权限。 还授予管理用户项目的权限。 |
repo:status | 授予对公共和私有仓库提交状态的读取/写入权限。 仅在授予其他用户或服务对私有仓库提交状态的访问权限而不授予对代码的访问权限时,才需要此作用域。 |
repo_deployment | 授予对公共和私有仓库部署状态的访问权限。 仅在授予其他用户或服务对部署状态的访问权限而不授予对代码的访问权限时,才需要此作用域。 |
public_repo | 将访问权限限制为公共仓库。 这包括对公共仓库和组织的代码、提交状态、仓库项目、协作者以及部署状态的读取/写入权限。 标星公共仓库也需要此权限。 |
repo:invite | 授予接受/拒绝仓库协作邀请的权限。 仅在授予其他用户或服务对邀请的访问权限而不授予对代码的访问权限时,才需要此作用域。 |
admin:repo_hook | 授予对公共和私有仓库中仓库挂钩的读取、写入、ping 和删除权限。 repo 和 public_repo 作用域授予对仓库(包括仓库挂钩)的完全访问权限。 使用 admin:repo_hook 作用域将访问权限限制为仅仓库挂钩。 |
write:repo_hook | 授予对公共或私有仓库中挂钩的读取、写入和 ping 权限。 |
read:repo_hook | 授予对公共或私有仓库中挂钩的读取和 ping 权限。 |
admin:org | 全面管理组织及其团队、项目和成员。 |
write:org | 对组织成员身份、组织项目和团队成员身份的读取和写入权限。 |
read:org | 对组织成员身份、组织项目和团队成员身份的只读权限。 |
admin:public_key | 全面管理公钥。 |
write:public_key | 创建、列出和查看公钥的详细信息。 |
read:public_key | 列出和查看公钥的详细信息。 |
admin:org_hook | 授予对组织挂钩的读取、写入、ping 和删除权限。 注:OAuth 令牌只能对由 OAuth 应用程序创建的组织挂钩执行这些操作。 个人访问令牌只能对用户创建的组织挂钩执行这些操作。 |
gist | 授予对 gist 的写入权限。 |
通知 | 授予: 对用户通知的读取权限 对线程的标记读取权限 对仓库的关注和取消关注权限,以及 对线程订阅的读取、写入和删除权限。 |
用户 | 仅授予对个人资料的读取/写入权限。 请注意,此作用域包括 user:email 和 user:follow 。 |
read:user | 授予读取用户个人资料数据的权限。 |
user:email | 授予对用户电子邮件地址的读取权限。 |
user:follow | 授予关注或取消关注其他用户的权限。 |
delete_repo | 授予删除可管理仓库的权限。 |
write:discussion | 授予对团队讨论的读取和写入权限。 |
read:discussion | 授予对团队讨论的读取权限。 |
admin:gpg_key | 全面管理 GPG 密钥。 |
write:gpg_key | 创建、列出和查看 GPG 密钥的详细信息。 |
read:gpg_key | 列出和查看 GPG 密钥的详细信息。 |
注:您的 OAuth 应用程序可以在初始重定向中请求作用域。 您可以使用空格分隔多个作用域来指定它们:
https://github.com/login/oauth/authorize?
client_id=...&
scope=user%20public_repo
请求的作用域和授予的作用域
scope
属性列出了用户授予的附加到令牌的作用域。 通常,这些作用域与您请求的作用域相同。 但是,用户可以编辑其作用域,实际上授予应用程序更少的权限(相比您最初请求的权限)。 此外,用户还可以在 OAuth 流程完成后编辑令牌作用域。 您应该意识到这种可能性,并相应地调整应用程序的行为。
如果用户选择授予更少的权限(相比您最初请求的权限),妥善处理这种错误情况非常重要。 例如,应用程序可以警告或以其他方式告诉用户,他们可用的功能会减少或者无法执行某些操作。
此外,应用程序总是可以将用户送回流程以获取更多权限,但不要忘记,用户总是可以说不。
请查看身份验证基础知识指南,其中提供了有关处理可修改令牌作用域的提示。
标准化作用域
请求多个作用域时,将用标准化的作用域列表保存令牌,而放弃其他请求的作用域隐式包含的那些作用域。 例如,请求 user,gist,user:email
将生成仅具有 user
和 gist
作用域的令牌,因为使用 user:email
作用域授予的权限包含在 user
作用域中。