对 REST API 进行身份验证

本文内容

你可以对 REST API 进行身份验证，以访问更多终结点并获得更高的速率限制。

关于身份验证

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

你可以通过在请求的 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 响应。

使用 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 终结点。 有关每个终结点所需权限的详细信息，请参阅 细粒度个人访问令牌所需的权限。 如果使用的是 personal access token (classic)，则 personal access token (classic) 需要特定权限才能访问每个 REST API 终结点。 有关要选择的范围的通用指南，请参阅 OAuth 应用的范围。

如果使用 personal access token (classic) 访问强制执行 SAML 单一登录 (SSO) 进行身份验证的组织，则需在创建令牌后对其进行授权。} Fine-grained personal access token 在令牌创建期间获得授权，然后获得对组织的访问权限。 有关详细信息，请参阅“授权用于 SAML 单点登录的个人访问令牌”。

如果尝试使用 SAML SSO 的 personal access token (classic) 访问强制执行 SAML SSO 的组织之前没有向其授权，你可能会收到 404 Not Found 或 403 Forbidden 错误。 如果收到 403 Forbidden 错误，可以参考 X-GitHub-SSO 标头中的 URL 来对令牌进行授权。 URL 将在一小时后过期。 如果请求的数据可能来自多个组织，API 将不会返回需要 SAML SSO 的组织的结果。 X-GitHub-SSO 标头将指示需对 personal access token (classic) 进行 SAML SSO 授权的组织的 ID。 例如：X-GitHub-SSO: partial-results; organizations=21955855,20582480。

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

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

GitHub App 需要特定权限才能访问每个 REST API 终结点。 有关每个终结点所需权限的详细信息，请参阅 GitHub 应用程序所需的权限。

你还可以使用 OAuth app 创建 OAuth 标记以访问 REST API。 但 GitHub 建议改用 GitHub App。 使用 GitHub Apps 可以更好地控制应用拥有的访问权限和权限。

对于 SAML SSO，应用创建的访问令牌会自动获得授权。

使用基本身份验证

GitHub Apps 和 OAuth apps 的一些 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 的设置页，请参阅“修改 GitHub 应用注册”。

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

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

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

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

延伸阅读