对 REST API 进行身份验证

关于身份验证

许多 REST API 终结点需要身份验证或是在进行身份验证后返回其他信息。此外，进行身份验证后，每小时可以发出更多请求。

要对请求进行身份验证，需要提供具有所需作用域或权限的身份验证令牌。有几种不同的方法可以获取令牌：你可以创建 personal access token，或者用 GitHub App 生成一个令牌，或在 GITHUB_TOKEN 工作流中使用内置的 GitHub Actions。

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

curl --request GET \
--url "http(s)://HOSTNAME/api/v3/octocat" \
--header "Authorization: Bearer YOUR-TOKEN" \
--header "X-GitHub-Api-Version: 2026-03-10"

注意

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

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

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

使用personal access token进行身份验证

如果要使用 GitHub REST API 进行个人使用，可以创建一个 personal access token。如果可能，GitHub建议您使用fine-grained personal access token而不是personal access token (classic)。有关创建personal access token的详细信息，请参阅管理个人访问令牌。

如果您使用 fine-grained personal access token，您的 fine-grained personal access token 需要特定权限才能访问每个 REST API 端点。每个终结点的 REST API 参考文档都说明终结点是否支持 fine-grained personal access token，并说明令牌需要符合哪些权限才能使用该终结点。某些终结点可能需要多个权限，而某些终结点可能需要多个权限之一。有关 fine-grained personal access token 可以在每个权限下访问哪些 REST API 终结点的概述，请参阅细粒度个人访问令牌所需的权限。

如果您使用的是 personal access token (classic)，则需要特定的作用域才能访问每个 REST API 端点。有关选择什么作用域的通用指南，请参阅 OAuth 应用的范围。

Personal access tokens 在向 REST API 发送请求时，会作为你的身份（受你所选作用域或权限的限制）。因此，确保您的 personal access tokens 安全非常重要。有关保护 personal access tokens 安全的详细信息，请参阅确保 API 凭据安全。

Personal access tokens 和 SAML SSO

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

如果要为组织或代表其他用户使用 API， GitHub 建议使用一个 GitHub App。有关详细信息，请参阅“关于使用 GitHub 应用进行身份验证”。

每个终结点的 REST API 参考文档都说明终结点是否正常工作 GitHub Apps ，并说明应用使用终结点所需的权限。某些终结点可能需要多个权限，而某些终结点可能需要多个权限之一。有关 GitHub App 可以在每个权限下访问哪些 REST API 终结点的概述，请参阅 GitHub应用所需的权限。

还可以创建一个 OAuth 令牌，以便通过 OAuth app 访问 REST API。但是，GitHub建议您使用GitHub App代替。 GitHub Apps 允许对应用的访问和权限进行更多控制。

使用基本身份验证

某些用于 GitHub Apps 和 OAuth apps 的 REST API 端点需要使用基本身份验证才能访问。你将使用应用的客户端 ID 作为用户名，使用应用的客户端密码作为密码。

例如：

curl --request POST \
--url "http(s)://HOSTNAME/api/v3/applications/YOUR_CLIENT_ID/token" \
--user "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
--header "Accept: application/vnd.github+json" \
--header "X-GitHub-Api-Version: 2026-03-10" \
--data '{
  "access_token": "ACCESS_TOKEN_TO_CHECK"
}'

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

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

在任何页面 GitHub的右上角，单击个人资料图片。
导航到你的帐户设置。
- 对于由个人帐户拥有的应用，请单击“设置”****。
- 对于组织拥有的应用：
  1. 单击“你的组织”。****
  2. 在组织右侧，单击“设置”。
在左边栏中，单击 “Developer settings”****。
在左侧栏中，单击 GitHub Apps 或 OAuth apps。
对于 GitHub Apps，在要访问的 GitHub App 右侧，单击“ 编辑”。对于 OAuth apps，请点击您想要访问的应用。
在“客户端 ID”旁边****，你将看到应用的客户端 ID。
在“客户端密码”旁边****，单击“生成新客户端密码”，为应用生成客户端密码****。

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

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

如果无法执行此操作，可以将令牌存储为机密，并在工作流中使用 GitHub Actions 机密的名称。有关机密的详细信息，请参阅在 GitHub Actions 中使用机密。

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

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

在以下示例工作流中，将 PATH 替换为终结点的路径。有关路径的详细信息，请参阅 REST API 入门。用HOSTNAME的名称替换你的 GitHub Enterprise Server 实例。

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

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

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

在以下示例工作流中，将 PATH 替换为终结点的路径。有关路径的详细信息，请参阅 REST API 入门。用HOSTNAME的名称替换你的 GitHub Enterprise Server 实例。

YAML

jobs:
  use_api:
    runs-on: ubuntu-latest
    permissions: {}
    steps:
      - env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          curl --request GET \
          --url "http(s)://HOSTNAME/api/v3/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 "http(s)://HOSTNAME/api/v3/PATH" \
          --header "Authorization: Bearer $GH_TOKEN"

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

有关如何使用 JavaScript 在工作流中 GitHub Actions 进行身份验证的示例，请参阅使用 REST API 和 JavaScript 编写脚本。

使用用户名和密码进行身份验证

GitHub 建议使用令牌对 REST API 进行身份验证，而不是密码。你可以更好地控制令牌的功能，并且可以随时撤销令牌。你也可以使用用于基本身份验证的用户名和密码对 REST API 进行身份验证。为此，你需使用 --user 选项传递用户名和密码：

curl --request GET \
--url "http(s)://HOSTNAME/api/v3/user" \
--user USERNAME:PASSWORD \
--header "X-GitHub-Api-Version: 2026-03-10"

在本文中