关于身份验证
许多 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 的详细信息,请参阅“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 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 应用进行身份验证”。
你还可以使用 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 错误。