Skip to main content
我们经常发布文档更新,此页面的翻译可能仍在进行中。 有关最新信息,请访问英语文档

对 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: BearerAuthorization: token 传递令牌。 但是,如果要传递 JSON Web 令牌 (JWT),则必须使用 Authorization: Bearer

如果尝试在没有令牌或令牌权限不足的情况下使用 REST API 终结点,你将收到 404 Not Found403 Forbidden 响应。

使用 personal access token 进行身份验证

如果要将 GitHub REST API 用于个人用途,可以创建 personal access token。 如果可能,GitHub 建议使用 fine-grained personal access token 而不是 personal access token (classic)。 有关创建 personal access token 的详细信息,请参阅“Managing your personal access tokens”。

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

如果尝试使用 SAML SSO 的 personal access token (classic) 访问强制执行 SAML SSO 的组织之前没有向其授权,你可能会收到 404 Not Found403 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 应用进行身份验证”。

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

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

使用基本身份验证

GitHub App 和 OAuth App 的一些 REST API 终结点要求使用基本身份验证来访问终结点。 你将使用应用的客户端 ID 作为用户名,使用应用的客户端密码作为密码。

例如:

curl --request POST \
--url "https://api.github.com/authorizations" \
--user ":" \
--header "X-GitHub-Api-Version: 2022-11-28"

你可以在应用的设置页面上找到客户端 ID 和生成客户端密码。 对于用户拥有的 GitHub App,设置页面是 https://github.com/settings/apps/APP-SLUG。 对于组织拥有的 GitHub App,设置页面是 https://github.com/organizations/ORGANIZATION/settings/apps/APP-SLUG。 将 APP-SLUG 替换为应用的慢段化名称,将 ORGANIZATION 替换为组织的慢段化名称。 例如 https://github.com/organizations/octo-org/settings/apps/octo-app

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

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

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

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

延伸阅读