{"meta":{"title":"对 REST API 进行身份验证","intro":"你可以对 REST API 进行身份验证，以访问更多终结点并获得更高的速率限制。","product":"REST API","breadcrumbs":[{"href":"/zh/rest","title":"REST API"},{"href":"/zh/rest/authentication","title":"身份验证"},{"href":"/zh/rest/authentication/authenticating-to-the-rest-api","title":"身份验证"}],"documentType":"article"},"body":"# 对 REST API 进行身份验证\n\n你可以对 REST API 进行身份验证，以访问更多终结点并获得更高的速率限制。\n\n## 关于身份验证\n\n许多 REST API 终结点需要身份验证或是在进行身份验证后返回其他信息。 此外，进行身份验证后，每小时可以发出更多请求。\n\n要对请求进行身份验证，需要提供具有所需作用域或权限的身份验证令牌。 有几种不同的方法可以获取令牌：你可以创建 personal access token，或者用 GitHub App 生成一个令牌，或在 `GITHUB_TOKEN` 工作流中使用内置的 GitHub Actions。\n\n创建令牌后，可以通过在请求的 `Authorization` 标头中发送令牌来对请求进行身份验证。 例如，在以下请求中，请将 `YOUR-TOKEN` 替换为对你的令牌的引用：\n\n```shell\ncurl --request GET \\\n--url \"https://api.github.com/octocat\" \\\n--header \"Authorization: Bearer YOUR-TOKEN\" \\\n--header \"X-GitHub-Api-Version: 2026-03-10\"\n```\n\n> \\[!NOTE]\n> 在大多数情况下，可以使用 `Authorization: Bearer` 或 `Authorization: token` 传递令牌。 但是，如果要传递 JSON Web 令牌 (JWT)，则必须使用 `Authorization: Bearer`。\n\n### 失败登录限制\n\n如果尝试在没有令牌或令牌权限不足的情况下使用 REST API 终结点，你将收到 `404 Not Found` 或 `403 Forbidden` 响应。 使用无效凭据进行身份验证最初将返回 `401 Unauthorized` 响应。\n\n在短时间内检测到多个使用无效凭据的请求后，API 将暂时拒绝该用户的所有身份验证尝试（包括使用有效凭据的尝试），并返回 `403 Forbidden` 响应： 有关详细信息，请参阅“[REST API 的速率限制](/zh/rest/using-the-rest-api/rate-limits-for-the-rest-api)”。\n\n## 使用personal access token进行身份验证\n\n如果要使用 GitHub REST API 进行个人使用，可以创建一个 personal access token。 如果可能，GitHub建议您使用fine-grained personal access token而不是personal access token (classic)。 有关创建personal access token的详细信息，请参阅[管理个人访问令牌](/zh/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)。\n\n如果您使用 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/rest/authentication/permissions-required-for-fine-grained-personal-access-tokens)。\n\n如果您使用的是 personal access token (classic)，则需要特定的作用域才能访问每个 REST API 端点。 有关选择什么作用域的通用指南，请参阅 [OAuth 应用的范围](/zh/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps#available-scopes)。\n\nPersonal access tokens 在向 REST API 发送请求时，会作为你的身份（受你所选作用域或权限的限制）。 因此，确保您的 personal access tokens 安全非常重要。 有关保护 personal access tokens 安全的详细信息，请参阅 [确保 API 凭据安全](/zh/rest/authentication/keeping-your-api-credentials-secure?apiVersion=2022-11-28)。\n\n### Personal access tokens 和 SAML SSO\n\n如果您使用 personal access token (classic) 访问要求通过 SAML 单点登录（SSO）进行身份验证的组织，则需要在创建令牌后对其进行授权。\nFine-grained personal access token 会在创建令牌期间获得授权，此时尚未授予对组织的访问权限。 有关详细信息，请参阅“[授权个人访问令牌以与单点登录一起使用](/zh/authentication/authenticating-with-single-sign-on/authorizing-a-personal-access-token-for-use-with-single-sign-on)”。\n\n如果您在尝试使用 personal access token (classic) 访问强制实施 SAML SSO 的某个组织之前，未授权您的 personal access token (classic) 使用 SAML SSO，则您可能会收到 `403 Forbidden` 或 错误。 如果收到 `403 Forbidden` 错误，`X-GitHub-SSO` 标头将包含一个 URL，您可以访问该 URL 以授权您的令牌。 URL 将在一小时后过期。\n\n如果您在尝试使用您的 personal access token (classic) 访问多个组织之前，未先为其完成 SAML SSO 授权，则 API 将不会返回来自那些要求 SAML SSO 的组织的结果，而 `X-GitHub-SSO` 标头会指明要求对您的 personal access token (classic) 进行 SAML SSO 授权的组织 ID。 例如：`X-GitHub-SSO: partial-results; organizations=21955855,20582480`。\n\n## 使用应用生成的令牌进行身份验证\n\n如果要为组织或代表其他用户使用 API， GitHub 建议使用一个 GitHub App。 有关详细信息，请参阅“[关于使用 GitHub 应用进行身份验证](/zh/apps/creating-github-apps/authenticating-with-a-github-app/about-authentication-with-a-github-app)”。\n\n每个终结点的 REST API 参考文档都说明终结点是否正常工作 GitHub Apps ，并说明应用使用终结点所需的权限。 某些终结点可能需要多个权限，而某些终结点可能需要多个权限之一。 有关 GitHub App 可以在每个权限下访问哪些 REST API 终结点的概述，请参阅 [GitHub应用所需的权限](/zh/rest/authentication/permissions-required-for-github-apps)。\n\n还可以创建一个 OAuth 令牌，以便通过 OAuth app 访问 REST API。 但是，GitHub建议您使用GitHub App代替。\nGitHub Apps 允许对应用的访问和权限进行更多控制。\n\n应用创建的访问令牌会自动获得 SAML SSO 的授权。\n\n### 使用基本身份验证\n\n某些用于 GitHub Apps 和 OAuth apps 的 REST API 端点需要使用基本身份验证才能访问。 你将使用应用的客户端 ID 作为用户名，使用应用的客户端密码作为密码。\n\n例如：\n\n```shell\ncurl --request POST \\\n--url \"https://api.github.com/applications/YOUR_CLIENT_ID/token\" \\\n--user \"YOUR_CLIENT_ID:YOUR_CLIENT_SECRET\" \\\n--header \"Accept: application/vnd.github+json\" \\\n--header \"X-GitHub-Api-Version: 2026-03-10\" \\\n--data '{\n \"access_token\": \"ACCESS_TOKEN_TO_CHECK\"\n}'\n```\n\n客户端 ID 和客户端密码与应用相关联，而不是与应用所有者或授权应用的用户相关联。 它们用于代表应用执行操作，例如创建访问令牌。\n\n如果你是 GitHub App 或 OAuth app 的所有者，或者你是 GitHub App 的应用管理员，则可以在你的应用的设置页面中找到客户端 ID 并生成客户端密钥。 导航到应用的设置页：\n\n1. 在任何页面 GitHub的右上角，单击个人资料图片。\n2. 导航到你的帐户设置。\n * 对于由个人帐户拥有的应用，请单击“设置”\\*\\*\\*\\*。\n * 对于组织拥有的应用：\n 1. 单击“你的组织”。\\*\\*\\*\\*\n 2. 在组织右侧，单击“设置”。\n3. 在左边栏中，单击 “Developer settings”\\*\\*\\*\\*。\n4. 在左侧栏中，单击 **GitHub Apps** 或 **OAuth apps**。\n5. 对于 GitHub Apps，在要访问的 GitHub App 右侧，单击“ **编辑**”。 对于 OAuth apps，请点击您想要访问的应用。\n6. 在“客户端 ID”旁边\\*\\*\\*\\*，你将看到应用的客户端 ID。\n7. 在“客户端密码”旁边\\*\\*\\*\\*，单击“生成新客户端密码”，为应用生成客户端密码\\*\\*\\*\\*。\n\n## 在 GitHub Actions 工作流中进行身份验证\n\n如果要在工作流中使用 GitHub Actions API， GitHub 建议使用内置 `GITHUB_TOKEN` 身份验证，而不是创建令牌。 可以使用 `GITHUB_TOKEN` 密钥向 `permissions` 授予权限。 有关详细信息，请参阅“[在工作流中使用 GITHUB\\_TOKEN 进行身份验证](/zh/actions/tutorials/authenticate-with-github_token#modifying-the-permissions-for-the-github_token)”。\n\n如果无法执行此操作，可以将令牌存储为机密，并在工作流中使用 GitHub Actions 机密的名称。 有关机密的详细信息，请参阅 [在 GitHub Actions 中使用机密](/zh/actions/how-tos/write-workflows/choose-what-workflows-do/use-secrets)。\n\n### 在 GitHub Actions 工作流中使用 GitHub CLI 进行身份验证\n\n若要在使用 GitHub Actions 的 GitHub CLI\n工作流中向该 API 发出经过身份验证的请求，可以将 `GITHUB_TOKEN` 的值存储为环境变量，并使用 `run` 关键字执行 GitHub CLI`api` 子命令。 有关 `run` 关键字的详细信息，请参阅 [GitHub Actions 的工作流语法](/zh/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idstepsrun)。\n\n在以下示例工作流中，将 `PATH` 替换为终结点的路径。 有关路径的详细信息，请参阅 [REST API 入门](/zh/rest/using-the-rest-api/getting-started-with-the-rest-api?tool=cli#path)。\n\n```yaml\njobs:\n use_api:\n runs-on: ubuntu-latest\n permissions: {}\n steps:\n - env:\n GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n run: |\n gh api /PATH\n```\n\n### 在 GitHub Actions 工作流中使用 `curl` 进行身份验证\n\n若要在使用 GitHub Actions 的 `curl` 工作流中向 API 发出经过身份验证的请求，可以将 `GITHUB_TOKEN` 的值存储为环境变量，并使用 `run` 关键字向 API 执行 `curl` 请求。 有关 `run` 关键字的详细信息，请参阅 [GitHub Actions 的工作流语法](/zh/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idstepsrun)。\n\n在以下示例工作流中，将 `PATH` 替换为终结点的路径。 有关路径的详细信息，请参阅 [REST API 入门](/zh/rest/using-the-rest-api/getting-started-with-the-rest-api?tool=cli#path)。\n\n```yaml copy\njobs:\n use_api:\n runs-on: ubuntu-latest\n permissions: {}\n steps:\n - env:\n GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n run: |\n curl --request GET \\\n --url \"https://api.github.com/PATH\" \\\n --header \"Authorization: Bearer $GH_TOKEN\"\n```\n\n### 在 GitHub Actions 工作流中使用 JavaScript 进行身份验证\n\n有关如何使用 JavaScript 在工作流中 GitHub Actions 进行身份验证的示例，请参阅 [使用 REST API 和 JavaScript 编写脚本](/zh/rest/guides/scripting-with-the-rest-api-and-javascript#authenticating-in-github-actions)。\n\n## 使用用户名和密码进行身份验证\n\n不支持使用用户名和密码进行身份验证。 如果尝试使用用户名和密码进行身份验证，你将收到 4xx 错误。\n\n## 延伸阅读\n\n* [确保 API 凭据安全](/zh/rest/authentication/keeping-your-api-credentials-secure)\n* [REST API 入门](/zh/rest/using-the-rest-api/getting-started-with-the-rest-api#authentication)"}