关于用户访问令牌
注意:过期的用户访问令牌目前是一项可选功能,可能会有变动。 若要选择加入或退出令牌过期功能,请参阅“激活 GitHub 应用的可选功能”。 有关详细信息,请参阅“GitHub 应用的用户到服务器访问令牌过期”。
用户访问令牌是一种 OAuth 标记。 不同于传统 OAuth 标记,用户访问令牌不使用范围。 而是使用细粒度的权限。 用户访问令牌仅具有用户和应用都拥有的权限。 例如,如果向应用授予了写入存储库内容的权限,但用户只能读取内容,则用户访问令牌也只能读取内容。
同样,用户访问令牌只能访问用户和应用都可访问的资源。 例如,如果向应用授予了对存储库 A
和 B
的访问权限,并且用户可以访问存储库 B
和 C
,那么用户访问令牌可以访问存储库 B
,但不能访问 A
或 C
。 可以使用 REST API 检查用户访问令牌可以访问哪些安装以及安装中的哪些存储库。 有关详细信息,请参阅“GitHub 应用安装”中的 GET /user/installations
和 GET /user/installations/{installation_id}/repositories
。
使用用户访问令牌发出 API 请求时,用户访问令牌的速率限制适用。 有关详细信息,请参阅“GitHub 应用的速率限制”。
默认情况下,用户访问令牌在 8 小时后过期。 可以使用刷新令牌重新生成用户访问令牌。 有关详细信息,请参阅“刷新用户访问令牌”。
用户可以撤销其对 GitHub App 的授权。 有关详细信息,请参阅“令牌过期和吊销”。 如果用户撤销其对 GitHub App 的授权,应用会收到 github_app_authorization
Webhook。 GitHub Apps 无法取消订阅此事件。 如果应用收到此 Webhook,应停止代表已撤销令牌的用户调用 API。 如果应用继续使用已撤销的访问令牌,它将收到 401 Bad Credentials
错误。 有关此 Webhook 的详细信息,请参阅“Webhook 事件和有效负载”。
应确保用户访问令牌和刷新令牌的安全。 有关详细信息,请参阅“Best practices for creating a GitHub App”。
使用 Web 应用程序流生成用户访问令牌
如果应用在浏览器中运行,应使用 Web 应用程序流来生成用户访问令牌。 有关使用 Web 应用流的教程,请参阅“Building a "Login with GitHub" button with a GitHub App”。
-
将用户定向到此 URL,并从以下参数列表添加任何必需的查询参数:
http(s)://HOSTNAME/login/oauth/authorize
。 例如,此 URL 指定client_id
和state
参数:http(s)://HOSTNAME/login/oauth/authorize?client_id=12345&state=abcdefg
。查询参数 类型 说明 client_id
string
必填。 GitHub App 的客户端 ID。 客户端 ID 不同于应用 ID。 可以在应用的设置页上找到客户端 ID。
对于用户拥有的应用,设置页为https://github.com/settings/apps/APP-SLUG
。
对于组织拥有的应用,设置页为https://github.com/organizations/ORGANIZATION/settings/apps/APP-SLUG
。
将APP-SLUG
替换为应用的转换名称,将ORGANIZATION
替换为组织的转换名称。 例如,https://github.com/organizations/octo-org/settings/apps/octo-app
。redirect_uri
string
用户获得授权后被发送到的应用程序中的 URL。 此 URL 必须与在应用设置中作为“回叫 URL”提供的 URL 之一完全匹配,并且不能包含任何附加参数。 state
string
指定后,该值应该包含一个随机字符串,以防止伪造攻击,并且可以包含任何其他任意数据。 login
string
指定后,Web 应用程序流会显示特定帐户,提示用户可使用该帐户登录和授权应用。 allow_signup
boolean
在 OAuth 流程中,是否向未经身份验证的用户提供注册 GitHub 的选项。 默认为 true
。 在策略禁止注册时使用false
。 -
如果用户接受授权请求,GitHub 会将用户重定向到应用设置中的回叫 URL 之一,并提供可用于在下一步中创建用户访问令牌的
code
查询参数。 如果在上一步中指定了redirect_uri
,则会使用该回叫 URL。 否则,将使用应用设置页上的第一个回叫 URL。如果在上一步中指定了
state
参数,GitHub 还将包含state
参数。 如果state
参数与在上一步中发送的state
参数不匹配,则无法信任请求,应中止 Web 应用程序流。 -
通过向此 URL 发出
POST
请求以及以下查询参数,将上一步中的code
换为用户访问令牌:http(s)://HOSTNAME/login/oauth/access_token
查询参数 类型 说明 client_id
string
必填。 GitHub App 的客户端 ID。 客户端 ID 不同于应用 ID。 可以在应用的设置页上找到客户端 ID。
对于用户拥有的应用,设置页为https://github.com/settings/apps/APP-SLUG
。
对于组织拥有的应用,设置页为https://github.com/organizations/ORGANIZATION/settings/apps/APP-SLUG
。
将APP-SLUG
替换为应用的转换名称,将ORGANIZATION
替换为组织的转换名称。 例如,https://github.com/organizations/octo-org/settings/apps/octo-app
。client_secret
string
必填。 GitHub App的客户端密码。 可以在应用的设置页上生成客户端密码。 code
string
必填。 在上一步中收到的代码。 redirect_uri
string
用户获得授权后被发送到的应用程序中的 URL。 此 URL 必须与在设置 GitHub App 时作为“回叫 URL”提供的 URL 之一完全匹配,并且不能包含任何附加参数。 repository_id
string
用户访问令牌可以访问的单个存储库的 ID。 如果 GitHub App 或用户无法访问存储库,将忽略此项。 使用此参数可进一步限制用户访问令牌的访问权限。 -
GitHub will give a response that includes the following parameters:
响应参数 类型 说明 access_token
string
用户访问令牌。 令牌以 ghu_
开头。expires_in
integer
access_token
过期前需经历的秒数。 如果禁用了用户访问令牌的有效期限,将省略此参数。 值将始终为28800
(8 小时)。refresh_token
string
刷新令牌。 如果禁用了用户访问令牌的有效期限,将省略此参数。 令牌以 ghr_
开头。refresh_token_expires_in
integer
refresh_token
过期前需经历的秒数。 如果禁用了用户访问令牌的有效期限,将省略此参数。 值将始终为15811200
(6 个月)。scope
string
令牌具有的范围。 此值将始终为空字符串。 不同于传统的 OAuth 标记,用户访问令牌仅限于应用和用户拥有的权限。 token_type
string
令牌类型。 值将始终为 bearer
。 -
使用上一步中的用户访问令牌代表用户发出 API 请求。 在 API 请求的
Authorization
标头中包含用户访问令牌。 例如:curl --request GET \ --url "https://HOSTNAME/api/v3/user" \ --header "Accept: application/vnd.github+json" \ --header "Authorization: Bearer USER_ACCESS_TOKEN"
使用设备流生成用户访问令牌
注意:设备流处于公开测试阶段,可能会发生更改。
如果应用无外设应用或无权访问浏览器,应使用设备流来生成用户访问令牌。 例如,CLI 工具、简单的 Raspberry Pi 和桌面应用程序应使用设备流。 有关使用设备流的教程,请参阅“Building a CLI with a GitHub App”。
必须先在应用的设置中启用设备流,才能使用设备流。 有关启用设备流的详细信息,请参阅“Modifying a GitHub App registration”。
设备流使用 OAuth 2.0 设备授权模式。
-
向
http(s)://HOSTNAME/login/device/code
发送POST
请求和client_id
查询参数。 客户端 ID 不同于应用 ID。 可以在应用的设置页上找到客户端 ID。- 对于用户拥有的应用,设置页为
https://github.com/settings/apps/APP-SLUG
。 - 对于组织拥有的应用,设置页为
https://github.com/organizations/ORGANIZATION/settings/apps/APP-SLUG
。
将
APP-SLUG
替换为应用的转换名称,将ORGANIZATION
替换为组织的转换名称。 例如https://github.com/organizations/octo-org/settings/apps/octo-app
。 - 对于用户拥有的应用,设置页为
-
GitHub 将做出包含以下查询参数的响应:
响应参数 类型 说明 device_code
string
用于验证设备的验证码。 该验证码长度为 40 个字符。 user_code
string
应用程序应该显示的验证码,以便用户可以在浏览器中输入该验证码。 此代码为 8 个字符,中间有连字符。 例如, WDJB-MJHT
。verification_uri
string
用户需要在其中输入其 user_code
的 URL。 该 URL 为:https://HOSTNAME/login/device
。expires_in
integer
device_code
和user_code
过期之前的秒数。 默认值为 900 秒(15 分钟)。interval
integer
在能够发出新的访问令牌请求 ( POST http(s)://HOSTNAME/login/oauth/access_token
) 以完成设备授权之前必须经过的最短秒数。 如果在经过此时间间隔前发出请求,则会达到速率限制并出现slow_down
错误。 默认值为 5 秒。 -
提示用户在
https://HOSTNAME/login/device
输入上一步中的user_code
。如果用户未在
expires_in
时间内输入该代码,该代码会失效。 在这种情况下,应重启设备流。 -
轮询
POST http(s)://HOSTNAME/login/oauth/access_token
以及client_id
、device_code
和grant_type
查询参数(如下所述),直到设备和用户代码过期或用户通过输入user_code
成功授权应用。查询参数 类型 说明 client_id
string
必填。 GitHub App 的客户端 ID。 device_code
string
必填。 在上一步中收到的设备验证码。 grant_type
string
必填。 授权类型必须是 urn:ietf:params:oauth:grant-type:device_code
。repository_id
string
用户访问令牌可以访问的单个存储库的 ID。 如果 GitHub App 或用户无法访问存储库,将忽略此项。 使用此参数可进一步限制用户访问令牌的访问权限。 轮询此终结点的频率不要高于
interval
指示的频率。 如果这样做,会达到速率限制并出现slow_down
错误。slow_down
错误响应向上一个interval
添加 5 秒钟的时间。在用户输入代码之前,GitHub 将做出响应,其中包含一个 200 状态和一个
error
响应查询参数。错误名称 说明 authorization_pending
授权请求待处理并且用户尚未输入用户代码时,将发生此错误。 应用应持续轮询 POST http(s)://HOSTNAME/login/oauth/access_token
,且轮询频率低于interval
指定的频率。slow_down
收到 slow_down
错误时,会使用POST http(s)://HOSTNAME/login/oauth/access_token
向请求之间所需的最短interval
或时间范围添加 5 秒钟的额外时间。 例如,如果请求之间的启动间隔至少需要 5 秒,并且你收到了slow_down
错误响应,那么现在必须等待至少 10 秒,然后才能发出新的令牌请求。 错误响应包括必须使用的新interval
。expired_token
如果设备代码已过期,则将看到 token_expired
错误。 您必须发出新的设备代码请求。unsupported_grant_type
轮询 OAuth 令牌请求 POST http(s)://HOSTNAME/login/oauth/access_token
时,授权类型必须为urn:ietf:params:oauth:grant-type:device_code
并且必须作为输入参数包含在内。incorrect_client_credentials
对于设备流程,您必须传递应用程序的客户端 ID,您可以在应用程序设置页面上找到该 ID。 客户端 ID 不同于应用程序 ID 和客户端密码。 incorrect_device_code
提供的 device_code
无效。access_denied
当用户在授权过程中单击取消时,你将收到 access_denied
错误,该用户将无法再次使用验证码。device_flow_disabled
尚未在应用的设置中启用设备流。 有关启用设备流的详细信息,请参阅“Modifying a GitHub App registration”。 -
用户输入
user_code
后,GitHub 将做出包含以下查询参数的响应:响应参数 类型 说明 access_token
string
用户访问令牌。 令牌以 ghu_
开头。expires_in
integer
access_token
过期前需经历的秒数。 如果禁用了用户访问令牌的有效期限,将省略此参数。 值将始终为28800
(8 小时)。refresh_token
string
刷新令牌。 如果禁用了用户访问令牌的有效期限,将省略此参数。 令牌以 ghr_
开头。refresh_token_expires_in
integer
refresh_token
过期前需经历的秒数。 如果禁用了用户访问令牌的有效期限,将省略此参数。 值将始终为15811200
(6 个月)。scope
string
令牌具有的范围。 此值将始终为空字符串。 不同于传统的 OAuth 标记,用户访问令牌仅限于应用和用户拥有的权限。 token_type
string
令牌类型。 值将始终为 bearer
。 -
使用上一步中的用户访问令牌代表用户发出 API 请求。 在 API 请求的
Authorization
标头中包含用户访问令牌。 例如:curl --request GET \ --url "https://HOSTNAME/api/v3/user" \ --header "Accept: application/vnd.github+json" \ --header "Authorization: Bearer USER_ACCESS_TOKEN"
在用户安装应用时生成用户访问令牌
如果在应用设置中选择“在安装过程中请求用户授权(OAuth)”,GitHub 会在用户安装应用后立即启动 Web 应用程序流。
无论应用是安装在用户帐户上还是组织帐户上,都可以使用此方法生成用户访问令牌。 但是,如果应用安装在组织帐户上,则需要使用 Web 应用程序流或设备流来为组织中的其他用户生成用户访问令牌。
-
当用户安装应用时,GitHub 会将用户重定向到
http(s)://HOSTNAME/login/oauth/authorize?client_id=CLIENT_ID
,其中CLIENT_ID
是应用的客户端 ID。 -
如果用户接受你的授权请求,GitHub 会将用户重定向到应用设置中的第一个回叫 URL,并提供
code
查询参数。如果要控制使用的回叫 URL,请不要选择“在安装过程中请求用户授权(OAuth)”。 而是要引导用户完成整个 Web 应用程序流,并指定
redirect_uri
参数。 -
通过向此 URL 发出
POST
请求以及以下查询参数,将上一步中的code
换为用户访问令牌:http(s)://HOSTNAME/login/oauth/access_token
查询参数 类型 说明 client_id
string
必填。 GitHub App 的客户端 ID。 客户端 ID 不同于应用 ID。 可以在应用的设置页上找到客户端 ID。
对于用户拥有的应用,设置页为https://github.com/settings/apps/APP-SLUG
。
对于组织拥有的应用,设置页为https://github.com/organizations/ORGANIZATION/settings/apps/APP-SLUG
。
将APP-SLUG
替换为应用的转换名称,将ORGANIZATION
替换为组织的转换名称。 例如,https://github.com/organizations/octo-org/settings/apps/octo-app
。client_secret
string
必填。 GitHub App的客户端密码。 可以在应用的设置页上生成客户端密码。 code
string
必填。 在上一步中收到的代码。 redirect_uri
string
用户获得授权后被发送到的应用程序中的 URL。 此 URL 必须与在设置 GitHub App 时作为“回叫 URL”提供的 URL 之一完全匹配,并且不能包含任何附加参数。 repository_id
string
用户访问令牌可以访问的单个存储库的 ID。 如果 GitHub App 或用户无法访问存储库,将忽略此项。 使用此参数可进一步限制用户访问令牌的访问权限。 -
GitHub will give a response that includes the following parameters:
响应参数 类型 说明 access_token
string
用户访问令牌。 令牌以 ghu_
开头。expires_in
integer
access_token
过期前需经历的秒数。 如果禁用了用户访问令牌的有效期限,将省略此参数。 值将始终为28800
(8 小时)。refresh_token
string
刷新令牌。 如果禁用了用户访问令牌的有效期限,将省略此参数。 令牌以 ghr_
开头。refresh_token_expires_in
integer
refresh_token
过期前需经历的秒数。 如果禁用了用户访问令牌的有效期限,将省略此参数。 值将始终为15811200
(6 个月)。scope
string
令牌具有的范围。 此值将始终为空字符串。 不同于传统的 OAuth 标记,用户访问令牌仅限于应用和用户拥有的权限。 token_type
string
令牌类型。 值将始终为 bearer
。 -
使用上一步中的用户访问令牌代表用户发出 API 请求。 在 API 请求的
Authorization
标头中包含用户访问令牌。 例如:curl --request GET \ --url "https://HOSTNAME/api/v3/user" \ --header "Accept: application/vnd.github+json" \ --header "Authorization: Bearer USER_ACCESS_TOKEN"
使用刷新令牌生成用户访问令牌
默认情况下,用户访问令牌在 8 小时后过期。 如果收到带有过期时间的用户访问令牌,则会同时收到刷新令牌。 刷新令牌在 6 个月后过期。 可以使用此刷新令牌重新生成用户访问令牌。 有关详细信息,请参阅“刷新用户访问令牌”。
GitHub 强烈建议使用会过期的用户访问令牌。 如果之前选择不使用会过期的用户访问令牌,但希望重新启用此功能,请参阅“激活 GitHub 应用的可选功能”。
用户访问令牌支持的终结点
检查运行
检查套件
行为准则
部署状态
部署
事件
源
Git Blob
Git 提交
Git 引用
Git 标记
Git 树
Gitignore 模板
安装
议题受理人
议题评论
议题事件
议题时间表
问题
标签
许可证
Markdown
元数据
里程碑
组织挂钩
组织成员
- 列出组织成员
- 检查用户的组织成员身份
- 删除组织成员
- 获取用户的组织成员身份
- 设置用户的组织成员身份
- 删除用户的组织成员身份
- 列出公共组织成员
- 检查用户的公共组织成员身份
- 为已通过身份验证的用户设置公共组织成员身份
- 为已通过身份验证的用户删除公共组织成员身份
组织外部协作者
组织团队项目
组织团队仓库
组织团队
组织
项目协作者
项目
- 列出组织项目
- 创建组织项目
- 获取项目
- 更新项目
- 删除项目
- 列出项目列
- 创建项目列
- 获取项目列
- 更新项目列
- 删除项目列
- 列出项目卡
- 创建项目卡
- 移动项目列
- 获取项目卡
- 更新项目卡
- 删除项目卡
- 移动项目卡
- 列出存储库项目
- 创建存储库项目
拉取注释
拉取请求审查事件
拉取请求审查请求
拉取请求审查
拉取
反应
- 删除反应
- 列出对提交注释的反应
- 创建对提交注释的反应
- 列出对问题的反应
- 创建对问题的反应
- 列出对问题注释的反应
- 创建对问题注释的反应
- 列出对拉取请求评审注释的反应
- 创建对拉取请求评审注释的反应
- 列出对团队讨论注释的反应
- 创建对团队讨论注释的反应
- 列出对团队讨论的反应
- 创建对团队讨论的反应
- 删除提交注释反应
- 删除问题反应
- 删除对提交注释的反应
- 删除拉取请求注释反应
- 删除团队讨论反应
- 删除团队讨论注释反应
存储库
- 列出组织存储库
- 为已通过身份验证的用户创建存储库
- 获取存储库
- 更新存储库
- 删除存储库
- 比较两个提交
- 列出存储库参与者
- 列出分支
- 创建分支
- 列出存储库语言
- 列出存储库标记
- 列出存储库团队
- 传输存储库
- 列出公共存储库
- 列出已通过身份验证的用户的存储库
- 列出用户的存储库
- 使用存储库模板创建存储库
仓库活动
仓库分支
- 列出分支
- 获取分支
- 获取分支保护
- 更新分支保护
- 删除分支保护
- 获取管理分支保护
- 设置管理分支保护
- 删除管理分支保护
- 获取拉取请求评审保护
- 更新拉取请求评审保护
- 删除拉取请求评审保护
- 获取提交签名保护
- 创建提交签名保护
- 删除提交签名保护
- 获取状态检查保护
- 更新状态检查保护
- 删除状态检查保护
- 获取所有状态检查上下文
- 添加状态检查上下文
- 设置状态检查上下文
- 删除状态检查上下文
- 获取访问限制
- 删除访问限制
- 列出有权访问受保护分支的团队
- 添加团队访问限制
- 设置访问限制
- 删除团队访问限制
- 列出受保护分支的用户限制
- 添加用户访问限制
- 设置用户访问限制
- 删除用户访问限制
- 合并分支
仓库协作者
仓库提交注释
仓库提交
仓库社区
仓库内容
仓库事件调度
仓库挂钩
- 列出存储库 Webhook
- 创建存储库 Webhook
- 获取存储库 Webhook
- 更新存储库 Webhook
- 删除存储库 Webhook
- Ping 存储库 Webhook
- 测试推送存储库 Webhook
仓库邀请
仓库密钥
仓库页面
- 获取 GitHub Pages 站点
- 创建 GitHub Pages 站点
- 更新有关 GitHub Pages 站点的信息
- 删除 GitHub Pages 站点
- 列出 GitHub Pages 生成
- 请求GitHub Pages 生成
- 获取 GitHub Pages 生成
- 获取最新页面生成