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: 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 速率限制。

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

如果您想个人使用 GitHub REST API，您可以创建个人访问令牌。如果可能，GitHub 建议使用细粒度个人访问令牌，而不是传统的个人访问令牌（classic）。有关创建个人访问令牌的更多信息，请参见管理您的个人访问令牌。

如果您使用细粒度个人访问令牌，则该令牌需要特定权限才能访问每个 REST API 端点。每个端点的 REST API 参考文档会说明该端点是否支持细粒度个人访问令牌以及使用该端点需要哪些权限。有些端点可能需要多个权限，有些端点则需要多种权限中的任意一个。有关细粒度个人访问令牌在不同权限下可访问的 REST API 端点概览，请参见细粒度个人访问令牌所需的权限。

如果您使用传统个人访问令牌（classic），则需要特定的作用域（scopes）才能访问每个 REST API 端点。有关选择哪些作用域的一般指南，请参见 OAuth 应用的作用域。

个人访问令牌在您向 REST API 发出请求时充当您的身份（受所选作用域或权限限制），因此请务必妥善保管个人访问令牌。有关保持个人访问令牌安全的更多信息，请参见保护 API 凭证安全。

个人访问令牌与 SAML 单点登录

如果您使用传统个人访问令牌访问实施 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 端点需要使用基本认证才能访问。您需要将应用的 client ID 作为用户名，client secret 作为密码。

例如

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: 2026-03-10" \
--data '{
  "access_token": "ACCESS_TOKEN_TO_CHECK"
}'

client ID 和 client secret 与应用关联，而非与应用所有者或授权该应用的用户关联。它们用于代表应用执行操作，例如创建访问令牌。

如果您是 GitHub 应用或 OAuth 应用的所有者，或是 GitHub 应用的管理员，您可以在应用的设置页面查找 client ID 并生成 client secret。要前往应用的设置页面

在 GitHub 任意页面的右上角，点击您的个人资料图片。
前往您的账户设置。
- 对于由个人账户拥有的 App，点击设置。
- 对于由组织拥有的 App
  1. 点击 您的组织。
  2. 在组织右侧，点击设置。
在左侧边栏，点击 开发者设置。
在左侧栏中，点击 GitHub Apps 或 OAuth apps。
对于 GitHub Apps，在想要访问的 GitHub App 右侧点击 Edit。对于 OAuth apps，点击您想要访问的应用。
在 Client ID 旁边，您可以看到应用的 client ID。
在 Client secrets 旁边，点击 Generate a new client secret 为您的应用生成新的 client secret。

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

如果您想在 GitHub Actions 工作流中使用 API，GitHub 建议使用内置的 GITHUB_TOKEN 进行认证，而不是自行创建令牌。您可以通过 permissions 键为 GITHUB_TOKEN 授予权限。更多信息请参见在工作流中使用 GITHUB_TOKEN 进行认证。

如果无法实现此方式，您可以将令牌存储为机密，并在 GitHub Actions 工作流中使用该机密的名称。有关机密的更多信息，请参见在 GitHub Actions 中使用机密。

在 GitHub Actions 工作流中使用 GitHub CLI 进行认证

要在 GitHub Actions 工作流中使用 GitHub CLI 对 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

在 GitHub Actions 工作流中使用 `curl` 进行认证

要在 GitHub Actions 工作流中使用 curl 对 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"

在 GitHub Actions 工作流中使用 JavaScript 进行认证

有关在 GitHub Actions 工作流中使用 JavaScript 进行认证的示例，请参见使用 REST API 与 JavaScript 编写脚本。

使用用户名和密码进行认证

不支持使用用户名和密码进行认证。如果尝试使用用户名和密码进行认证，将收到 4xx 错误。

对 REST API 进行身份验证

本文内容