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 授权您的令牌。该 URL 在一小时后过期。

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

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

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

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

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

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

使用基本身份验证

某些用于 GitHub Apps 和 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 App 或 OAuth 应用程序的所有者，或者您是 GitHub App 的应用程序管理员，您可以在应用程序的设置页面上找到客户端 ID 并生成客户端密钥。要导航到应用程序的设置页面

在 GitHub 上任何页面的右上角，单击您的个人资料照片。
导航到您的帐户设置。
- 对于个人帐户拥有的应用程序，单击“设置”。
- 对于组织拥有的应用程序
  1. 单击“您的组织”。
  2. 在组织的右侧，单击“设置”。
在左侧边栏中，点击 ** 开发者设置**。
在左侧边栏中，点击 **GitHub Apps** 或 **OAuth apps**。
对于 GitHub Apps，在您要访问的 GitHub App 右侧点击 **编辑**。对于 OAuth apps，点击您要访问的应用。
在 **客户端 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

在本文中