대부분의 API 요청에는 인증이 필요하거나, 인증이 제공되지 않으면 공개 데이터만 반환됩니다. 인증이 필요하지 않은 경우 각 엔드포인트의 문서에 명시되어 있습니다. 예를 들어 /projects/:id 엔드포인트는 인증이 필요하지 않습니다.

GitLab REST API에서 여러 방법으로 인증할 수 있습니다:

• OAuth 2.0 토큰
• 개인 접근 토큰
• 프로젝트 접근 토큰
• 그룹 접근 토큰
• 세션 쿠키
• CI/CD job 토큰 (특정 엔드포인트만)

프로젝트 접근 토큰은 다음에서 지원됩니다:

• GitLab Self-Managed: Free, Premium, Ultimate.
• GitLab.com: Premium, Ultimate.

관리자인 경우 귀하 또는 귀하의 애플리케이션은 다음 중 하나를 사용하여 특정 사용자로 인증할 수 있습니다:

• 가장 토큰(Impersonation tokens)
• Sudo

인증 정보가 유효하지 않거나 누락된 경우 GitLab은 상태 코드 401과 함께 오류 메시지를 반환합니다:

{
  "message": "401 Unauthorized"
}

OAuth 2.0 토큰#

access_token 매개변수 또는 Authorization 헤더에 전달하여 API로 OAuth 2.0 토큰을 사용하여 인증할 수 있습니다.

매개변수에서 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"

OAuth 2.0 제공자로서의 GitLab에 대해 자세히 읽어보세요.

개인, 프로젝트 및 그룹 접근 토큰#

접근 토큰을 사용하여 API로 인증할 수 있습니다. PRIVATE-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 토큰#

특정 API 엔드포인트로 인증하기 위해 job 토큰을 사용할 수 있습니다. GitLab CI/CD job에서 토큰은 CI_JOB_TOKEN 변수로 사용 가능합니다.

JOB-TOKEN 헤더(권장) 또는 다른 방법으로 토큰을 전달합니다. 모든 인증 방법은 CI/CD job 토큰 인증을 참조하세요.

예를 들어 헤더 방법을 사용하는 경우:

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

세션 쿠키#

메인 GitLab 애플리케이션에 로그인하면 _gitlab_session 쿠키가 설정됩니다. API는 세션 쿠키가 있을 경우 인증에 이 쿠키를 사용합니다. API를 사용하여 새 세션 쿠키를 생성하는 것은 지원되지 않습니다.

이 인증 방법의 주요 사용자는 GitLab 자체의 웹 프론트엔드입니다. 웹 프론트엔드는 명시적으로 접근 토큰을 전달하지 않고도 인증된 사용자로서 API를 사용하여 프로젝트 목록을 가져올 수 있습니다.

가장 토큰#

가장 토큰은 일종의 개인 접근 토큰입니다. 관리자만 생성할 수 있으며, 특정 사용자로서 API로 인증하는 데 사용됩니다.

다음에 대한 대안으로 가장 토큰을 사용합니다:

• 사용자의 암호 또는 개인 접근 토큰 중 하나.
• Sudo 기능. 사용자 또는 관리자의 암호 또는 토큰을 알 수 없거나 시간이 지남에 따라 변경될 수 있습니다.

자세한 내용은 사용자 토큰 API 문서를 참조하세요.

가장 토큰은 일반 개인 접근 토큰과 똑같이 사용되며, private_token 매개변수 또는 PRIVATE-TOKEN 헤더에 전달할 수 있습니다.

가장 비활성화#

기본적으로 가장은 활성화되어 있습니다. 가장을 비활성화하려면:

가장을 다시 활성화하려면 이 구성을 제거하고 GitLab을 재구성(Linux 패키지 설치)하거나 재시작(소스 컴파일 설치)합니다.

Sudo#

모든 API 요청은 sudo 범위가 있는 OAuth 또는 개인 접근 토큰으로 관리자로 인증된 경우 다른 사용자인 것처럼 API 요청을 수행하는 것을 지원합니다. 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 요청 및 sudo 요청과 함께 cURL을 사용하는 요청 예시:

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"

ID를 제공하는 유효한 API 요청 및 sudo 요청과 함께 cURL을 사용하는 요청 예시:

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"