注：过期用户令牌目前是用户到服务器令牌过期的一部分，可能会更改。 要选择使用用户到服务器令牌过期测试功能，请参阅“激活应用程序的可选功能”。 更多信息请参阅“GitHub 应用程序过期用户到服务器访问令牌”。
当 GitHub 应用程序代表用户时，它执行用户到服务器请求。 这些请求必须使用用户的访问令牌进行授权。 用户到服务器请求包括请求用户的数据，例如确定要向特定用户显示哪些仓库。 这些请求还包括用户触发的操作，例如运行构建。
为使用户到服务器的访问令牌更安全，您可以使用将在 8 小时后过期的访问令牌，以及可交换新访问令牌的刷新令牌。 更多信息请参阅“刷新用户到服务器访问令牌”。
识别站点上的用户
要授权用户使用在浏览器中运行的标准应用程序，请使用 web 应用程序流程。
Web 应用程序流程
使用 web 应用程序流程时，识别您站点上用户的过程如下：
- 用户被重定向，以请求他们的 GitHub 身份
- 用户被 GitHub 重定向回您的站点
- 您的 GitHub 应用程序使用用户的访问令牌访问 API
如果您在创建或修改应用程序时选择在安装过程中请求用户授权 (OAuth)，则步骤 1 将在应用程序安装过程中完成。 更多信息请参阅“在安装过程中授权用户”。
1. 请求用户的 GitHub 身份
Direct the user to the following URL in their browser:
GET http(s)://[hostname]/login/oauth/authorize
当您的 GitHub 应用程序指定 login 参数后，它将提示拥有特定账户的用户可以用来登录和授权您的应用程序。
参数
| 名称 | 类型 | 描述 |
|---|---|---|
client_id | 字符串 | 必填。GitHub 应用程序的客户端 ID。 选择应用程序时，您可以在 GitHub 应用程序设置中找到它。 注意： 应用程序 ID 和客户端 ID 不相同，无法互换。 |
redirect_uri | 字符串 | 用户获得授权后被发送到的应用程序中的 URL。 它必须完全匹配设置 GitHub 应用程序时 在 User authorization callback URL（用户授权回调 URL）字段中提供的 URL，并且不能包含任何其他参数。 |
state | 字符串 | 它应该包含一个随机字符串以防止伪造攻击，并且可以包含任何其他任意数据。 |
login | 字符串 | 提供用于登录和授权应用程序的特定账户。 |
allow_signup | 字符串 | 在 OAuth 流程中，是否向经过验证的用户提供注册 GitHub 的选项。 默认值为 true。 如有政策禁止注册，请使用 false。 |
注 ：不需要在授权请求中提供作用域。 不同于传统的 OAuth，授权令牌仅限于与您的 GitHub 应用程序和用户的应用程序相关联的权限。
2. 用户被 GitHub 重定向回您的站点
如果用户接受您的请求，GitHub 将重定向回您的站点，其中，代码参数为临时 code，state 参数为您在上一步提供的状态。 如果状态不匹配，则请求是由第三方创建的，该过程应中止。
注：如果您在创建或修改应用程序时选择在安装过程中请求用户授权 (OAuth)，则 GitHub 将返回需要交换访问令牌的临时 code。 当 GitHub 在应用程序安装过程中启动 OAuth 流程时，不会返回 state 参数。
将此 code 交换为访问令牌。 When expiring tokens are enabled, the access token expires in 8 hours and the refresh token expires in 6 months. 每次刷新令牌时都会得到一个新的刷新令牌。 更多信息请参阅“刷新用户到服务器访问令牌”。
过期用户令牌目前是一个可选的功能，可能会更改。 要选择使用用户到服务器令牌过期功能，请参阅“激活应用程序的可选功能”。
Make a request to the following endpoint to receive an access token:
POST http(s)://[hostname]/login/oauth/access_token
参数
| 名称 | 类型 | 描述 |
|---|---|---|
client_id | 字符串 | 必填。GitHub 应用程序的客户端 ID。 |
client_secret | 字符串 | 必填。GitHub 应用程序的客户端密钥。 |
代码 | 字符串 | 必填。您收到的响应第 1 步的代码。 |
redirect_uri | 字符串 | 用户获得授权后被发送到的应用程序中的 URL。 它必须完全匹配设置 GitHub 应用程序时 在 User authorization callback URL（用户授权回调 URL）字段中提供的 URL，并且不能包含任何其他参数。 |
state | 字符串 | 您在第 1 步提供的不可猜测的随机字符串。 |
响应
默认情况下，响应采用以下形式。 响应参数 expires_in、refresh_token 和 refresh_token_expires_in 仅当您启用过期用户到服务器访问令牌功能时才会返回。
{
"access_token": "e72e16c7e42f292c6912e7710c838347ae178b4a",
"expires_in": 28800,
"refresh_token": "r1.c1b4a2e77838347a7e420ce178f2e7c6912e1692",
"refresh_token_expires_in": 15811200,
"scope": "",
"token_type": "bearer"
}
3. 您的 GitHub 应用程序使用用户的访问令牌访问 API
用户的访问令牌允许 GitHub 应用程序代表用户向 API 发出请求。
Authorization: token OAUTH-TOKEN
GET http(s)://[hostname]/api/v3/user
例如，您可以像以下这样在 curl 中设置“授权”标头：
curl -H "Authorization: token OAUTH-TOKEN" http(s)://[hostname]/api/v3/user检查用户可以访问哪些安装资源
获得用户的 OAuth 令牌后，您可以检查该用户可以访问哪些安装。
Authorization: token OAUTH-TOKEN
GET /user/installations
您还可以检查用户可以访问哪些仓库进行安装。
Authorization: token OAUTH-TOKEN
GET /user/installations/:installation_id/repositories
更多信息请参阅：列出用户访问令牌可访问的应用程序安装和列出用户访问令牌可访问的仓库。
处理已撤销的 GitHub 应用程序授权
默认情况下，如果用户撤销对 GitHub 应用程序的授权，该应用程序将收到 github_app_authorization web 挂钩。 GitHub 应用程序无法取消订阅此事件。 任何人都可以从 GitHub 帐户设置页面撤销他们对 GitHub 应用程序的授权。 撤销对 GitHub 应用程序的授权不会卸载 GitHub 应用程序。 您应该编程 GitHub 应用程序，使其在收到此 web 挂钩后，不再代表已撤销令牌的人调用 API。 如果 GitHub 应用程序继续使用已撤销的访问令牌，它将收到 401 Bad Credentials 错误。
用户级别的权限
您可以向 GitHub 应用程序添加用户级别的权限，以访问用户电子邮件等用户资源，这些权限是单个用户在用户授权流程中授予的。 用户级别的权限不同于仓库和组织级别的权限，后者是在组织或用户帐户上安装时授予的。
您可以在 Permissions & webhooks（权限和 web 挂钩）页面 User permissions（用户权限）部分的 GitHub 应用程序设置中选择用户级别的权限。 有关选择权限的更多信息，请参阅“编辑 GitHub 应用程序的权限”。
当用户在他们的帐户上安装您的应用程序时，安装提示将列出应用程序请求的用户级别权限，并说明应用程序会向各个用户请求这些权限。
由于用户级别的权限是基于单个用户授予的，因此您可以将它们添加到现有应用中，而无需提示用户升级。 但是，您需要通过用户授权流程发送现有用户，以授权新权限并为这些请求获取新的用户到服务器令牌。
用户到服务器请求
虽然大多数 API 交互应使用服务器到服务器安装访问令牌进行，但某些端点允许您使用用户访问令牌通过 API 执行操作。 您的应用程序可以使用GraphQL v4 或 REST v3 端点发出以下请求。
支持的端点
检查运行
检查套件
行为准则
部署状态
部署
事件
馈送
Git Blob
Git 提交
Git 引用
Git 标记
Git 树
Gitignore 模板
安装设施
议题受理人
议题评论
议题事件
议题时间表
议题
标签
许可
Markdown
元数据
里程碑
组织挂钩
组织成员
- 列出组织成员
- 检查用户的组织成员身份
- 删除组织成员
- 获取用户的组织成员身份
- 设置用户的组织成员身份
- 删除用户的组织成员身份
- 列出公共组织成员
- 检查用户的公共组织成员身份
- 设置经验证用户的公共组织成员身份
- 删除经验证用户的公共组织成员身份
组织外部协作者
组织预接收挂钩
组织团队项目
组织团队仓库
组织团队
组织
项目协作者
项目
- 列出组织项目
- 创建组织项目
- 获取项目
- 更新项目
- 删除项目
- 列出项目列
- 创建项目列
- 获取项目列
- 更新项目列
- 删除项目列
- 列出项目卡
- 创建项目卡
- 移动项目列
- 获取项目卡
- 更新项目卡
- 删除项目卡
- 移动项目卡
- 列出仓库项目
- 创建仓库项目
拉取注释
拉取请求审查事件
拉取请求审查请求
拉取请求审查
拉取
反应
- 删除反应
- 列出提交注释的反应
- 创建提交注释的反应
- 列出议题的反应
- 创建议题的反应
- 列出议题注释的反应
- 创建议题注释的反应
- 列出拉取请求审查注释的反应
- 创建拉取请求审查注释的反应
- 列出团队讨论注释的反应
- 创建团队讨论注释的反应
- 列出团队讨论的反应
- 创建团队讨论的反应
- 删除提交注释反应
- 删除议题反应
- 删除对提交注释的反应
- 删除拉取请求注释反应
- 删除团队讨论反应
- 删除团队讨论注释反应
仓库
- 列出组织仓库
- 为经验证的用户创建仓库。
- 获取仓库
- 更新仓库
- 删除仓库
- 比较两个提交
- 列出仓库贡献者
- 列出复刻
- 创建复刻
- 列出仓库语言
- 列出仓库标记
- 列出仓库团队
- 转让仓库
- 列出公共仓库
- 列出经验证用户的仓库
- 列出用户的仓库
- 使用仓库模板创建仓库
仓库活动
仓库分支
- 列出分支
- 获取分支
- 获取分支保护
- 更新分支保护
- 删除分支保护
- 获取管理员分支保护
- 设置管理员分支保护
- 删除管理员分支保护
- 获取拉取请求审查保护
- 更新拉取请求审查保护
- 删除拉取请求审查保护
- 获取提交签名保护
- 创建提交签名保护
- 删除提交签名保护
- 获取状态检查保护
- 更新状态检查保护
- 删除状态检查保护
- 获取所有状态检查上下文
- 添加状态检查上下文
- 设置状态检查上下文
- 删除状态检查上下文
- 获取访问限制
- 删除访问限制
- 列出有权访问受保护分支的团队
- 添加团队访问限制
- 设置团队访问限制
- 删除团队访问限制
- 列出受保护分支的用户限制
- 添加用户访问限制
- 设置用户访问限制
- 删除用户访问限制
- 合并分支
仓库协作者
仓库提交注释
仓库提交
仓库社区
仓库内容
仓库事件调度
仓库挂钩
仓库邀请
仓库密钥
仓库页面
- 获取 GitHub Pages 站点
- 创建 GitHub Pages 站点
- 更新关于 GitHub Pages 站点的信息
- 删除 GitHub Pages 站点
- 列出 GitHub Pages 构建
- 请求 GitHub Pages 构建
- 获取 GitHub Pages 构建
- 获取最新页面构建