REST API 认证

大多数 API 请求需要身份验证，或者在没有提供身份验证时仅返回公开数据。当不需要身份验证时，每个端点的文档会明确说明这一点。例如，/projects/:id 端点不需要身份验证。

您可以通过以下几种方式对 GitLab REST API 进行身份验证：

• OAuth 2.0 令牌
• 个人访问令牌
• 项目访问令牌
• 组访问令牌
• 会话 cookie
• GitLab CI/CD 作业令牌 (仅限特定端点)

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

• GitLab 自托管：Free、Premium 和 Ultimate。
• GitLab.com：Premium 和 Ultimate。

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

• 模拟令牌
• Sudo

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

{
  "message": "401 Unauthorized"
}

OAuth 2.0 tokens

您可以使用 OAuth 2.0 令牌 通过在 access_token 参数或 Authorization 头部中传递它来对 API 进行身份验证。

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

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

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

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

有关 GitLab 作为 OAuth 2.0 提供商 的更多信息。

Personal/project/group access tokens

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

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

curl --request GET \
  --url "https://gitlab.example.com/api/v4/projects?private_token=<your_access_token>"

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

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

您还可以将个人、项目或组访问令牌与 OAuth 兼容的头部一起使用：

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

Job tokens

您可以通过在 job_token 参数或 JOB-TOKEN 头部中传递令牌，使用作业令牌对 特定 API 端点 进行身份验证。要在 GitLab CI/CD 作业中传递令牌，请使用 CI_JOB_TOKEN 变量。

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

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

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

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

Session cookie

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

此身份验证方法的主要用户是 GitLab 本身的 Web 前端。Web 前端可以以已认证用户的身份使用 API 来获取项目列表，而无需显式传递访问令牌。

Impersonation tokens

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

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

• 用户的密码或其个人访问令牌之一。
• Sudo 功能。用户或管理员的密码或令牌可能未知，或者可能随时间变化。

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

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

Disable impersonation

默认情况下，模拟功能已启用。要禁用模拟：

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

Sudo

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

作为 管理员，通过使用查询字符串或带有您要执行操作的用户 ID 或用户名（不区分大小写）的头部传递 sudo 参数。如果作为头部传递，头部名称必须为 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 --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header "Sudo: username" \
  --url "https://gitlab.example.com/api/v4/projects"

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

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

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