# 对 REST API 进行身份验证 你可以对 REST API 进行身份验证，以访问更多终结点并获得更高的速率限制。 ## 关于身份验证 许多 REST API 终结点需要身份验证或是在进行身份验证后返回其他信息。 此外，进行身份验证后，每小时可以发出更多请求。 要对请求进行身份验证，需要提供具有所需作用域或权限的身份验证令牌。 有几种不同的方法可以获取令牌：你可以创建 personal access token，或者用 GitHub App 生成一个令牌，或在 `GITHUB_TOKEN` 工作流中使用内置的 GitHub Actions。 创建令牌后，可以通过在请求的 `Authorization` 标头中发送令牌来对请求进行身份验证。 例如，在以下请求中，请将 `YOUR-TOKEN` 替换为对你的令牌的引用： ```shell curl --request GET \ --url "http(s)://HOSTNAME/api/v3/octocat" \ --header "Authorization: Bearer YOUR-TOKEN" \ --header "X-GitHub-Api-Version: 2026-03-10" ``` > \[!NOTE] > 在大多数情况下，可以使用 `Authorization: Bearer` 或 `Authorization: token` 传递令牌。 但是，如果要传递 JSON Web 令牌 (JWT)，则必须使用 `Authorization: Bearer`。 ### 失败登录限制 如果尝试在没有令牌或令牌权限不足的情况下使用 REST API 终结点，你将收到 `404 Not Found` 或 `403 Forbidden` 响应。 使用无效凭据进行身份验证最初将返回 `401 Unauthorized` 响应。 在短时间内检测到多个使用无效凭据的请求后，API 将暂时拒绝该用户的所有身份验证尝试（包括使用有效凭据的尝试），并返回 `403 Forbidden` 响应： 有关详细信息，请参阅“[REST API 的速率限制](/zh/enterprise-server@3.22/rest/using-the-rest-api/rate-limits-for-the-rest-api)”。 ## 使用personal access token进行身份验证 如果要使用 GitHub REST API 进行个人使用，可以创建一个 personal access token。 如果可能，GitHub建议您使用fine-grained personal access token而不是personal access token (classic)。 有关创建personal access token的详细信息，请参阅[管理个人访问令牌](/zh/enterprise-server@3.22/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)。 如果您使用 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 终结点的概述，请参阅 [细粒度个人访问令牌所需的权限](/zh/enterprise-server@3.22/rest/authentication/permissions-required-for-fine-grained-personal-access-tokens)。 如果您使用的是 personal access token (classic)，则需要特定的作用域才能访问每个 REST API 端点。 有关选择什么作用域的通用指南，请参阅 [OAuth 应用的范围](/zh/enterprise-server@3.22/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps#available-scopes)。 Personal access tokens 在向 REST API 发送请求时，会作为你的身份（受你所选作用域或权限的限制）。 因此，确保您的 personal access tokens 安全非常重要。 有关保护 personal access tokens 安全的详细信息，请参阅 [确保 API 凭据安全](/zh/enterprise-server@3.22/rest/authentication/keeping-your-api-credentials-secure?apiVersion=2022-11-28)。 ### Personal access tokens 和 SAML SSO ## 使用应用生成的令牌进行身份验证 如果要为组织或代表其他用户使用 API， GitHub 建议使用一个 GitHub App。 有关详细信息，请参阅“[关于使用 GitHub 应用进行身份验证](/zh/enterprise-server@3.22/apps/creating-github-apps/authenticating-with-a-github-app/about-authentication-with-a-github-app)”。 每个终结点的 REST API 参考文档都说明终结点是否正常工作 GitHub Apps ，并说明应用使用终结点所需的权限。 某些终结点可能需要多个权限，而某些终结点可能需要多个权限之一。 有关 GitHub App 可以在每个权限下访问哪些 REST API 终结点的概述，请参阅 [GitHub应用所需的权限](/zh/enterprise-server@3.22/rest/authentication/permissions-required-for-github-apps)。 还可以创建一个 OAuth 令牌，以便通过 OAuth app 访问 REST API。 但是，GitHub建议您使用GitHub App代替。 GitHub Apps 允许对应用的访问和权限进行更多控制。 ### 使用基本身份验证 某些用于 GitHub Apps 和 OAuth apps 的 REST API 端点需要使用基本身份验证才能访问。 你将使用应用的客户端 ID 作为用户名，使用应用的客户端密码作为密码。 例如： ```shell 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 并生成客户端密钥。 导航到应用的设置页： 1. 在任何页面 GitHub的右上角，单击个人资料图片。 2. 导航到你的帐户设置。 * 对于由个人帐户拥有的应用，请单击“设置”\*\*\*\*。 * 对于组织拥有的应用： 1. 单击“你的组织”。\*\*\*\* 2. 在组织右侧，单击“设置”。 3. 在左边栏中，单击 “Developer settings”\*\*\*\*。 4. 在左侧栏中，单击 **GitHub Apps** 或 **OAuth apps**。 5. 对于 GitHub Apps，在要访问的 GitHub App 右侧，单击“ **编辑**”。 对于 OAuth apps，请点击您想要访问的应用。 6. 在“客户端 ID”旁边\*\*\*\*，你将看到应用的客户端 ID。 7. 在“客户端密码”旁边\*\*\*\*，单击“生成新客户端密码”，为应用生成客户端密码\*\*\*\*。 ## 在 GitHub Actions 工作流中进行身份验证 如果要在工作流中使用 GitHub Actions API， GitHub 建议使用内置 `GITHUB_TOKEN` 身份验证，而不是创建令牌。 可以使用 `GITHUB_TOKEN` 密钥向 `permissions` 授予权限。 有关详细信息，请参阅“[在工作流中使用 GITHUB\_TOKEN 进行身份验证](/zh/enterprise-server@3.22/actions/tutorials/authenticate-with-github_token#modifying-the-permissions-for-the-github_token)”。 如果无法执行此操作，可以将令牌存储为机密，并在工作流中使用 GitHub Actions 机密的名称。 有关机密的详细信息，请参阅 [在 GitHub Actions 中使用机密](/zh/enterprise-server@3.22/actions/how-tos/write-workflows/choose-what-workflows-do/use-secrets)。 ### 在 GitHub Actions 工作流中使用 GitHub CLI 进行身份验证 若要在使用 GitHub Actions 的 GitHub CLI 工作流中向该 API 发出经过身份验证的请求，可以将 `GITHUB_TOKEN` 的值存储为环境变量，并使用 `run` 关键字执行 GitHub CLI`api` 子命令。 有关 `run` 关键字的详细信息，请参阅 [GitHub Actions 的工作流语法](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idstepsrun)。 在以下示例工作流中，将 `PATH` 替换为终结点的路径。 有关路径的详细信息，请参阅 [REST API 入门](/zh/enterprise-server@3.22/rest/using-the-rest-api/getting-started-with-the-rest-api?tool=cli#path)。 用`HOSTNAME`的名称替换你的 GitHub Enterprise Server 实例。 ```yaml 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 的工作流语法](/zh/enterprise-server@3.22/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idstepsrun)。 在以下示例工作流中，将 `PATH` 替换为终结点的路径。 有关路径的详细信息，请参阅 [REST API 入门](/zh/enterprise-server@3.22/rest/using-the-rest-api/getting-started-with-the-rest-api?tool=cli#path)。 用`HOSTNAME`的名称替换你的 GitHub Enterprise Server 实例。 ```yaml copy 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 编写脚本](/zh/enterprise-server@3.22/rest/guides/scripting-with-the-rest-api-and-javascript#authenticating-in-github-actions)。 ## 使用用户名和密码进行身份验证 GitHub 建议使用令牌对 REST API 进行身份验证，而不是密码。 你可以更好地控制令牌的功能，并且可以随时撤销令牌。 你也可以使用用于基本身份验证的用户名和密码对 REST API 进行身份验证。 为此，你需使用 `--user` 选项传递用户名和密码： ```shell curl --request GET \ --url "http(s)://HOSTNAME/api/v3/user" \ --user USERNAME:PASSWORD \ --header "X-GitHub-Api-Version: 2026-03-10" ``` ## 延伸阅读 * [确保 API 凭据安全](/zh/enterprise-server@3.22/rest/authentication/keeping-your-api-credentials-secure) * [REST API 入门](/zh/enterprise-server@3.22/rest/using-the-rest-api/getting-started-with-the-rest-api#authentication)