极狐GitLab 的大多数 API 请求都需要身份验证，否则只返回公共数据。当不需要身份验证时，每个端点的文档会指定这一点。例如，/projects/:id 端点不需要身份验证。

你可以通过以下几种方式与极狐GitLab REST API 进行身份验证：

项目访问令牌支持以下版本：

  • 极狐GitLab 私有化部署：基础版、专业版和旗舰版。
  • JihuLab.com：专业版和旗舰版。

如果你是管理员，你或你的应用程序可以使用以下方法以特定用户身份进行身份验证：

如果身份验证信息无效或缺失，极狐GitLab 会返回带有状态代码 401 的错误消息：

{
  "message": "401 Unauthorized"
}

{{< alert type=”note” >}}

部署令牌不能用于极狐GitLab 公共 API。有关详细信息，请参阅部署令牌。

{{< /alert >}}

OAuth 2.0 令牌

你可以通过在 access_token 参数或 Authorization 标头中传递 OAuth 2.0 令牌 来与 API 进行身份验证。

在参数中使用 OAuth 2.0 令牌的示例：

curl "https://gitlab.example.com/api/v4/projects?access_token=OAUTH-TOKEN"

在标头中使用 OAuth 2.0 令牌的示例：

curl --header "Authorization: Bearer OAUTH-TOKEN" "https://gitlab.example.com/api/v4/projects"

阅读更多关于极狐GitLab 作为 OAuth 2.0 提供程序的信息。

{{< alert type=”note” >}}

所有 OAuth 访问令牌在创建后两小时内有效。你可以使用 refresh_token 参数刷新令牌。有关如何使用刷新令牌请求新访问令牌的信息，请参阅 OAuth 2.0 令牌 文档。

{{< /alert >}}

Personal/project/group access tokens

你可以通过在 private_token 参数或 PRIVATE-TOKEN 标头中传递访问令牌来与 API 进行身份验证。

在参数中使用个人、项目或群组访问令牌的示例：

curl "https://gitlab.example.com/api/v4/projects?private_token=<your_access_token>"

在标头中使用个人、项目或群组访问令牌的示例：

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects"

你还可以使用符合 OAuth 的标头传递个人、项目或群组访问令牌：

curl --header "Authorization: Bearer <your_access_token>" "https://gitlab.example.com/api/v4/projects"

作业令牌

你可以通过在 job_token 参数或 JOB-TOKEN 标头中传递令牌来与特定 API 端点进行身份验证。在极狐GitLab CI/CD 作业中传递令牌时，使用 CI_JOB_TOKEN 变量。

在参数中使用作业令牌的示例：

curl --location --output artifacts.zip "https://gitlab.example.com/api/v4/projects/1/jobs/42/artifacts?job_token=$CI_JOB_TOKEN"

在标头中使用作业令牌的示例：

curl --header "JOB-TOKEN:$CI_JOB_TOKEN" "https://gitlab.example.com/api/v4/projects/1/releases"

登录主极狐GitLab 应用程序会设置一个 _gitlab_session cookie。如果存在，该 API 会使用此 cookie 进行身份验证。使用 API 生成新的会话 cookie 不受支持。

这种身份验证方法的主要用户是极狐GitLab 本身的 Web 前端。Web 前端可以使用 API 作为经过身份验证的用户获取项目列表，而无需显式传递访问令牌。

模拟令牌

模拟令牌是一种个人访问令牌。它们只能由管理员创建，并用于以特定用户身份通过 API 进行身份验证。

使用模拟令牌作为以下功能的替代方案：

  • 用户的密码或他们的个人访问令牌之一。
  • Sudo 功能。用户或管理员的密码或令牌可能未知，或可能随时间更改。

有关详细信息，请参阅用户令牌 API 文档。

模拟令牌的使用方式与常规个人访问令牌完全相同，可以在 private_token 参数或 PRIVATE-TOKEN 标头中传递。

禁用模拟

默认情况下，模拟是启用的。要禁用模拟：

{{< tabs >}}

{{< tab title=”Linux package (Omnibus)” >}}

  1. 编辑 /etc/gitlab/gitlab.rb 文件：

    gitlab_rails['impersonation_enabled'] = false

  2. 保存文件，然后重新配置 极狐GitLab 以使更改生效。

{{< /tab >}}

{{< tab title=”Self-compiled (source)” >}}

  1. 编辑 config/gitlab.yml 文件：

    gitlab:
  impersonation_enabled: false

  2. 保存文件，然后重新启动 极狐GitLab 以使更改生效。

{{< /tab >}}

{{< /tabs >}}

要重新启用模拟，请删除此配置，并重新配置极狐GitLab（Linux 包安装）或重新启动极狐GitLab（自编译安装）。

Sudo

所有 API 请求都支持以另一个用户身份执行 API 请求，前提是你已使用具有 sudo 范围的 OAuth 或个人访问令牌作为管理员进行身份验证。API 请求将以模拟用户的权限执行。

作为管理员，通过查询字符串或标头传递 sudo 参数，并使用你想要以其身份执行操作的用户的 ID 或用户名（不区分大小写）。如果作为标头传递，标头名称必须是 Sudo。

如果提供了非管理员访问令牌，极狐GitLab 会返回带有状态代码 403 的错误消息：

{
  "message": "403 Forbidden - Must be admin to use sudo"
}

如果提供了不具有 sudo 范围的访问令牌，则返回带有状态代码 403 的错误消息：

{
  "error": "insufficient_scope",
  "error_description": "The request requires higher privileges than provided by the access token.",
  "scope": "sudo"
}

如果找不到 sudo 用户 ID 或用户名，则返回状态代码为 404 的错误消息：

{
  "message": "404 User with ID or username '123' Not Found"
}

提供用户名的有效 API 请求和使用 cURL 的 sudo 请求示例：

GET /projects?private_token=<your_access_token>&sudo=username

curl --header "PRIVATE-TOKEN: <your_access_token>" --header "Sudo: username" "https://gitlab.example.com/api/v4/projects"

提供 ID 的有效 API 请求和使用 cURL 的 sudo 请求示例：

GET /projects?private_token=<your_access_token>&sudo=23

curl --header "PRIVATE-TOKEN: <your_access_token>" --header "Sudo: 23" "https://gitlab.example.com/api/v4/projects"