# OAuth 应用的范围
通过作用域，您可以准确指定所需的访问权限类型。 作用域限制 OAuth 标记的访问权限。 它们不会授予超出用户权限范围的任何额外权限。
> \[!NOTE]
> 请考虑构建GitHub App，而不是OAuth app。
> GitHub Apps 使用细粒度的权限，而不是范围，这样可以更好地控制应用可以执行的操作。 有关详细信息，请参阅 [GitHub 应用和 OAuth 应用之间的差异](/zh/enterprise-server@3.22/apps/oauth-apps/building-oauth-apps/differences-between-github-apps-and-oauth-apps) 和 [关于创建GitHub应用](/zh/enterprise-server@3.22/apps/creating-github-apps/about-creating-github-apps/about-creating-github-apps)。
在 GitHub 上设置OAuth app时，所请求的权限范围会显示在授权表单中，供用户查看。
> \[!NOTE]
> 如果要构建GitHub应用，则无需在授权请求中提供范围。 有关详细信息，请参阅“[代表用户使用 GitHub 应用进行身份验证](/zh/enterprise-server@3.22/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-a-github-app-on-behalf-of-a-user)”。
如果你的 OAuth app 无法访问浏览器（例如命令行界面 (CLI) 工具），则无需指定供用户向你的应用进行身份验证时使用的作用域。 有关详细信息，请参阅“[授权 OAuth 应用](/zh/enterprise-server@3.22/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps#device-flow)”。
检查标头以查看您拥有哪些 OAuth 作用域，以及 API 操作接受什么：
```shell
$ curl -H "Authorization: Bearer OAUTH-TOKEN" http(s)://HOSTNAME/api/v3/users/codertocat -I
HTTP/2 200
X-OAuth-Scopes: repo, user
X-Accepted-OAuth-Scopes: user
```
* `X-OAuth-Scopes` 列出令牌已授权的范围。
* `X-Accepted-OAuth-Scopes` 列出操作检查的范围。
## 可用的范围
| 名称 | 描述 |
| -------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`(no scope)`** | 授予对公共信息的只读访问权限（包括用户个人资料信息、存储库信息和代码片段） |
| **`site_admin`** | 授予站点管理员对 [GitHub Enterprise Server 管理 API 终结点](/zh/enterprise-server@3.22/rest/enterprise-admin)的访问权限。 |
| **`repo`** | 授予对公共、内部 和专用存储库的完全访问权限，包括对代码的读取和写入访问权限、提交状态、存储库邀请、协作者、部署状态和存储库 Webhook。 |
| **注意：** 除了存储库相关资源外，`repo` 范围还授予对组织拥有的资源（包括项目、邀请、团队成员身份和 Webhook）的管理权限。 此范围还授予对用户所拥有的项目的管理权限。 | |
| `repo:status` | 授予对 公开、私有和内部仓库中的提交状态的读/写访问权限。 仅在向其他用户或服务授予对专用存储库提交状态的访问权限而不授予对代码的访问权限时，才需要此范围。 |
| `repo_deployment` | 授予对公共和专用仓库的[部署状态](/zh/enterprise-server@3.22/rest/repos#deployments)的访问权限。 仅在向其他用户或服务授予对部署状态的访问权限而“不”\_\_ 授予对代码的访问权限时，才需要此范围。 |
| `public_repo` | 限制对公共存储库的访问权限。 这包括对公共仓库和组织的代码、提交状态、仓库项目、协作者以及部署状态的读取/写入权限。 带有星标的公共存储库也需要此权限。 |
| `repo:invite` | 授予接受/拒绝仓库协作邀请的权限。 仅在向其他用户或服务授予对邀请的访问权限而“不”\_\_ 授予对代码的访问权限时，才需要此作用域。 |
| `security_events` | 授予下列权限：
对[code scanning API](/zh/enterprise-server@3.22/rest/code-scanning)中安全事件的读写访问权限
仅当您希望向其他用户或服务授予访问安全事件的权限，而不授予对代码的访问权限时，才需要此作用域。 |
| **`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 app 创建的组织钩子执行这些操作。 | |
| Personal access tokens 只能对由用户创建的组织钩子执行这些操作。 | |
| **`gist`** | 授予对 Gist 的写权限。 |
| **`notifications`** | 授予下列权限：
对用户的通知的读取访问权限
对会话的“标记为读取”访问权限
对存储库的监视和取消监视访问权限，以及
对会话订阅的读取、写入和删除访问权限。 |
| **`user`** | 仅授予对个人资料的读写权限。 请注意，此范围包括 `user:email` 和 `user:follow`。 |
| `read:user` | 授予对用户个人资料数据的读取权限。 |
| `user:email` | 授予对用户电子邮件地址的读取权限。 |
| `user:follow` | 授予对关注或取消关注其他用户的访问权限。 |
| **`delete_repo`** | 授予删除可管理的仓库的权限。 |
| **`write:packages`** | 授予在 GitHub Packages 中上传或发布包的权限。 有关详细信息，请参阅“[发布包](/zh/enterprise-server@3.22/packages/learn-github-packages/publishing-a-package)”。 |
| **`read:packages`** | 授予从 GitHub Packages 下载或安装软件包的权限。 有关详细信息，请参阅“[安装一个包](/zh/enterprise-server@3.22/packages/learn-github-packages/installing-a-package)”。 |
| **`delete:packages`** | 授予从 GitHub Packages 删除软件包的权限。 有关详细信息，请参阅“[删除和恢复包](/zh/enterprise-server@3.22/packages/learn-github-packages/deleting-and-restoring-a-package)”。 |
| **`admin:gpg_key`** | 全面管理 GPG 密钥。 |
| `write:gpg_key` | 创建、列出和查看 GPG 密钥的详细信息。 |
| `read:gpg_key` | 列出和查看 GPG 密钥的详细信息。 |
| **`workflow`** | 授予添加和更新 GitHub Actions 工作流文件的能力。 如果在同一仓库中的另一个分支上存在相同的文件(具有相同的路径和内容)，则工作流程文件可以在没有此作用域的情况下提交。 工作流文件可以公开`GITHUB_TOKEN`，而`GITHUB_TOKEN`可能拥有不同的范围集。 有关详细信息，请参阅 [在工作流中使用 GITHUB\_TOKEN 进行身份验证](/zh/enterprise-server@3.22/actions/tutorials/authenticate-with-github_token#modifying-the-permissions-for-the-github_token)。 |
| **`admin:enterprise`** | 授予对企业功能的完全控制权限。 有关详细信息，请参阅 GraphQL API 文档中的“[管理企业帐户](/zh/enterprise-server@3.22/graphql/guides/managing-enterprise-accounts)”。
包括 `manage_runners:enterprise`、`manage_billing:enterprise` 和 `read:enterprise`。 |
| `manage_runners:enterprise` | 授予对企业内部自托管运行器的完全控制权限。 有关详细信息，请参阅“[自托管运行程序](/zh/enterprise-server@3.22/actions/concepts/runners/self-hosted-runners)”。 |
| `manage_billing:enterprise` | 读取和写入企业账单数据。 有关详细信息，请参阅“[计费 REST API 端点](/zh/enterprise-server@3.22/rest/billing)”。 |
| `read:enterprise` | 读取企业资料中的所有数据。 不包括企业成员或组织的个人资料数据。 |
| **`read:audit_log`** | 读取审核日志数据。 |
> \[!NOTE]
> 您的 OAuth app 可以在初始重定向时请求作用域。 可使用 `%20` 以空格分隔多个范围来指定它们：
>
> ```text
> https://github.com/login/oauth/authorize?
> client_id=...&
> scope=user%20repo_deployment
> ```
## 请求的作用域和授予的作用域
`scope` 属性列出了附加到用户授予的令牌的范围。 通常，这些作用域与您请求的作用域相同。
但是，用户可以编辑其范围，实际授予应用程序更少的权限（相比你最初请求的权限）。 此外，用户还可以在 OAuth 流程完成后编辑令牌范围。
你应该意识到这种可能性，并相应地调整应用程序的行为。
如果用户选择授予更少的权限（相比你最初请求的权限），妥善处理这种错误情况非常重要。 例如，应用程序可以警告或以其他方式告诉用户，他们可用的功能会减少或者无法执行某些操作。
此外，应用程序可以随时引导用户回到流程，以获取更多权限，但不要忘记，用户总是可以拒绝。
请查看[身份验证基础知识指南](/zh/enterprise-server@3.22/apps/oauth-apps/building-oauth-apps/authenticating-to-the-rest-api-with-an-oauth-app)，其中提供了有关处理可修改令牌范围的提示。
## 标准化范围
请求多个范围时，将用标准化的范围列表保存令牌，而放弃其他请求的范围隐式包含的那些范围。 例如，请求 `user,gist,user:email` 将生成仅具有 `user` 和 `gist` 范围的令牌，因为使用 `user:email` 范围授予的权限包含在 `user` 范围中。