REST API 认证 - GitHub 文档

关于身份验证

许多 REST API 端点需要身份验证，或者如果您已进行身份验证，则会返回其他信息。此外，当您进行身份验证时，您每小时可以发出更多请求。

要对您的请求进行身份验证，您需要使用所需的范围或权限提供身份验证令牌。有几种不同的方法可以获取令牌：您可以创建个人访问令牌，使用 GitHub 应用生成令牌，或在 GitHub Actions 工作流中使用内置的 GITHUB_TOKEN。

创建令牌后，您可以通过在请求的 Authorization 标头中发送令牌来对请求进行身份验证。例如，在以下请求中，将 YOUR-TOKEN 替换为您令牌的引用

curl --request GET \
--url "https://api.github.com/octocat" \
--header "Authorization: Bearer YOUR-TOKEN" \
--header "X-GitHub-Api-Version: 2022-11-28"

注意

在大多数情况下，您可以使用 Authorization: Bearer 或 Authorization: token 传递令牌。但是，如果您传递 JSON Web 令牌 (JWT)，则必须使用 Authorization: Bearer。

如果您尝试在没有令牌或使用权限不足的令牌的情况下使用 REST API 端点，您将收到 404 Not Found 或 403 Forbidden 响应。使用无效凭据进行身份验证最初将返回 401 Unauthorized 响应。

在检测到短时间内使用无效凭据的多个请求后，API 将暂时拒绝该用户的全部身份验证尝试（包括使用有效凭据的尝试），并返回 403 Forbidden 响应。有关更多信息，请参阅“REST API 的速率限制”。

使用个人访问令牌进行身份验证

如果您想将 GitHub REST API 用于个人用途，您可以创建一个个人访问令牌。如果可能，GitHub 建议您使用细粒度个人访问令牌而不是个人访问令牌（经典版）。有关创建个人访问令牌的更多信息，请参阅“管理您的个人访问令牌”。

如果您使用的是细粒度个人访问令牌，则您的细粒度个人访问令牌需要特定权限才能访问每个 REST API 端点。每个端点的 REST API 参考文档说明该端点是否适用于细粒度个人访问令牌，并说明令牌使用该端点所需的权限。某些端点可能需要多个权限，而某些端点可能需要多个权限之一。有关每个权限下细粒度个人访问令牌可以访问哪些 REST API 端点的概述，请参阅“细粒度个人访问令牌所需的权限”。

如果您使用的是个人访问令牌（经典版），则它需要特定范围才能访问每个 REST API 端点。有关要选择哪些范围的一般指南，请参阅“OAuth 应用的范围”。

个人访问令牌和 SAML SSO

如果您使用个人访问令牌（经典版）访问强制执行 SAML 单点登录 (SSO) 进行身份验证的组织，则需要在创建后授权您的令牌。细粒度个人访问令牌在令牌创建期间授权，然后授予对组织的访问权限。有关更多信息，请参阅“授权个人访问令牌以与 SAML 单点登录一起使用”。

如果您在尝试使用个人访问令牌（经典版）访问强制执行 SAML SSO 的单个组织之前没有为 SAML SSO 授权您的个人访问令牌（经典版），您可能会收到 404 Not Found 或 403 Forbidden 错误。如果您收到 403 Forbidden 错误，则 X-GitHub-SSO 标头将包含您可以遵循以授权令牌的 URL。该 URL 在一小时后过期。

如果您在尝试使用个人访问令牌（经典版）访问多个组织之前没有为 SAML SSO 授权您的个人访问令牌（经典版），则 API 将不会返回需要 SAML SSO 授权您的个人访问令牌（经典版）的组织的结果，并且 X-GitHub-SSO 标头将指示需要 SAML SSO 授权的组织的 ID。例如：X-GitHub-SSO: partial-results; organizations=21955855,20582480。

使用应用生成的令牌进行身份验证

如果您想将 API 用于组织或代表其他用户使用，GitHub 建议您使用 GitHub 应用。有关更多信息，请参阅“关于使用 GitHub 应用进行身份验证”。

每个端点的 REST API 参考文档说明该端点是否适用于 GitHub 应用，并说明应用使用该端点所需的权限。某些端点可能需要多个权限，而某些端点可能需要多个权限之一。有关 GitHub 应用可以使用每个权限访问哪些 REST API 端点的概述，请参阅“GitHub 应用所需的权限”。

您还可以使用 OAuth 应用创建 OAuth 令牌以访问 REST API。但是，GitHub 建议您改用 GitHub 应用。GitHub 应用允许更好地控制应用具有的访问权限和权限。

应用创建的访问令牌会自动获得 SAML SSO 授权。

使用基本身份验证

某些 GitHub 应用和 OAuth 应用的 REST API 端点要求您使用基本身份验证才能访问该端点。您将使用应用的客户端 ID 作为用户名，使用应用的客户端密钥作为密码。

例如

curl --request POST \
--url "https://api.github.com/applications/YOUR_CLIENT_ID/token" \
--user "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
--header "Accept: application/vnd.github+json" \
--header "X-GitHub-Api-Version: 2022-11-28" \
--data '{
  "access_token": "ACCESS_TOKEN_TO_CHECK"
}'

客户端 ID 和客户端密钥与应用相关联，而不是与应用的所有者或授权应用的用户相关联。它们用于代表应用执行操作，例如创建访问令牌。

如果您是 GitHub 应用或 OAuth 应用的所有者，或者如果您是 GitHub 应用的应用管理员，您可以在应用的设置页面上找到客户端 ID 并生成客户端密钥。要导航到应用的设置页面

在 GitHub 上任何页面的右上角，点击您的个人资料照片。
导航到您的帐户设置。
- 对于个人帐户拥有的应用，点击设置。
- 对于组织拥有的应用
  1. 点击您的组织。
  2. 在组织的右侧，点击设置。
在左侧边栏中，点击 开发者设置。
在左侧边栏中，点击GitHub 应用或OAuth 应用。
对于 GitHub 应用，在要访问的 GitHub 应用的右侧，点击编辑。对于 OAuth 应用，点击要访问的应用。
在客户端 ID旁边，您将看到应用的客户端 ID。
在客户端密钥旁边，点击生成新的客户端密钥以生成应用的客户端密钥。

在 GitHub Actions 工作流中进行身份验证

如果您想在 GitHub Actions 工作流中使用 API，GitHub 建议您使用内置的 GITHUB_TOKEN 进行身份验证，而不是创建令牌。您可以使用 permissions 密钥授予 GITHUB_TOKEN 权限。有关更多信息，请参阅“自动令牌身份验证”。

如果这不可行，您可以将令牌存储为机密并在 GitHub Actions 工作流中使用机密名称。有关机密的更多信息，请参阅“在 GitHub Actions 中使用机密”。

使用 GitHub CLI 在 GitHub Actions 工作流中进行身份验证

要在使用 GitHub CLI 的 GitHub Actions 工作流中发出经过身份验证的 API 请求，您可以将GITHUB_TOKEN的值存储为环境变量，并使用run关键字执行 GitHub CLI 的api子命令。有关run关键字的更多信息，请参阅“GitHub Actions 的工作流语法”。

在以下示例工作流中，请将PATH替换为端点的路径。有关路径的更多信息，请参阅“REST API 入门”。

jobs:
  use_api:
    runs-on: ubuntu-latest
    permissions: {}
    steps:
      - env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          gh api /PATH

使用`curl`在 GitHub Actions 工作流中进行身份验证

要在使用curl的 GitHub Actions 工作流中发出经过身份验证的 API 请求，您可以将GITHUB_TOKEN的值存储为环境变量，并使用run关键字执行对 API 的curl请求。有关run关键字的更多信息，请参阅“GitHub Actions 的工作流语法”。

在以下示例工作流中，请将PATH替换为端点的路径。有关路径的更多信息，请参阅“REST API 入门”。

YAML

jobs:
  use_api:
    runs-on: ubuntu-latest
    permissions: {}
    steps:
      - env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          curl --request GET \
          --url "https://api.github.com/PATH" \
          --header "Authorization: Bearer $GH_TOKEN"

jobs:
  use_api:
    runs-on: ubuntu-latest
    permissions: {}
    steps:
      - env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          curl --request GET \
          --url "https://api.github.com/PATH" \
          --header "Authorization: Bearer $GH_TOKEN"

向 REST API 进行身份验证

在本文中