개인 접근 토큰 API

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

개인 접근 토큰에 대해 자세히 알아보세요.

개인 접근 토큰 목록

  • created_after, created_before, last_used_after, last_used_before, revoked, search 및 state 필터는 GitLab 15.5에서 도입되었습니다.

인증된 사용자가 액세스할 수있는 모든 개인 액세스 토큰을 가져옵니다. 기본적으로 다음을 반환합니다:

  • 현재 사용자가 생성 한 개인 액세스 토큰 (관리자가 아님).
  • 관리자에게는 모든 개인 액세스 토큰이 반환됩니다.

관리자는 다음을 수행 할 수 있습니다.

  • user_id 매개 변수를 사용하여 사용자로 필터링 할 수 있습니다.
  • 다른 필터를 사용하여 모든 개인 액세스 토큰을 사용할 수 있습니다 (GitLab 15.5 이상).

관리자가 아닌 사람들은 다음을 수행 할 수 없습니다.

  • 자신 이외의 사용자를 필터링하기 위해 user_id 매개 변수를 사용할 수 없습니다. 그렇지 않으면 401 Unauthorized 응답을 수신합니다.
  • 자신의 개인 액세스 토큰에 대해서만 필터링 할 수 있습니다 (GitLab 15.5 이상). 
GET /personal_access_tokens
GET /personal_access_tokens?created_after=2022-01-01T00:00:00
GET /personal_access_tokens?created_before=2022-01-01T00:00:00
GET /personal_access_tokens?last_used_after=2022-01-01T00:00:00
GET /personal_access_tokens?last_used_before=2022-01-01T00:00:00
GET /personal_access_tokens?revoked=true
GET /personal_access_tokens?search=name
GET /personal_access_tokens?state=inactive
GET /personal_access_tokens?user_id=1

지원되는 속성:

속성 유형 필수여부 설명
created_after datetime (ISO 8601) 아니요 지정된 시간 이후에 생성된 PAT에 대한 결과를 제한합니다.
created_before datetime (ISO 8601) 아니요 지정된 시간 이전에 생성된 PAT에 대한 결과를 제한합니다.
last_used_after datetime (ISO 8601) 아니요 지정된 시간 이후에 마지막으로 사용된 PAT에 대한 결과를 제한합니다.
last_used_before datetime (ISO 8601) 아니요 지정된 시간 이전에 마지막으로 사용된 PAT에 대한 결과를 제한합니다.
revoked 부울 아니요 지정된 취소 상태의 PAT에 대한 결과를 제한합니다. 유효한 값은 true 및 false입니다.
search 문자열 아니요 이름에 검색 문자열을 포함하는 PAT에 대한 결과를 제한합니다.
state 문자열 아니요 지정된 상태의 PAT에 대한 결과를 제한합니다. 유효한 값은 active 및 inactive입니다.
user_id 정수 또는 문자열 아니요 지정된 사용자가 소유 한 PAT에 대한 결과를 제한합니다.

예시 요청: 

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

예시 응답: 

[
  {
    "id": 4,
    "name": "Test Token",
    "revoked": false,
    "created_at": "2020-07-23T14:31:47.729Z",
    "scopes": ["api"],
    "user_id": 24,
    "last_used_at": "2021-10-06T17:58:37.550Z",
    "active": true,
    "expires_at": null
  }
]

예시 요청: 

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/personal_access_tokens?user_id=3"

예시 응답: 

[
  {
    "id": 4,
    "name": "Test Token",
    "revoked": false,
    "created_at": "2020-07-23T14:31:47.729Z",
    "scopes": ["api"],
    "user_id": 3,
    "last_used_at": "2021-10-06T17:58:37.550Z",
    "active": true,
    "expires_at": null
  }
]

예시 요청: 

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/personal_access_tokens?revoked=true"

예시 응답: 

[
  {
    "id": 41,
    "name": "Revoked Test Token",
    "revoked": true,
    "created_at": "2022-01-01T14:31:47.729Z",
    "scopes": ["api"],
    "user_id": 8,
    "last_used_at": "2022-05-18T17:58:37.550Z",
    "active": false,
    "expires_at": null
  }
]

취소된 속성으로 병합된 속성으로 필터링할 수 있습니다: 

GET /personal_access_tokens?revoked=true&created_before=2022-01-01

단일 개인 접근 토큰 가져오기

개인 접근 토큰의 ID 또는 API에 헤더로 전달하여 개인 접근 토큰을 가져옵니다.

개인 접근 토큰 ID 사용

ID로 개인 접근 토큰을 가져옵니다. 사용자는 자신의 토큰을 가져올 수 있습니다. 관리자는 모든 토큰을 가져올 수 있습니다. 

GET /personal_access_tokens/:id
속성 유형 필수여부 설명
id 정수/문자열 예 개인 접근 토큰의 ID 
curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/personal_access_tokens/<id>"

응답

  • 404 HTTP 상태 코드가 GitLab 15.3에서 도입.
  • 사용자가 지정된 ID의 토큰에 액세스 할 수 없는 경우 401: Unauthorized.
  • 지정된 ID의 토큰이 존재하지 않는 경우 404: Not Found (관리자의 경우).
어떠한 경우에도 번역된 문서는 원본 GitLab 페이지보다 정확하지 않을 수 있습니다.

요청 헤더 사용하기

개인 액세스 토큰을 하나 받고 해당 토큰에 대한 정보를 해당 헤더에서 전달하여 가져옵니다. 

GET /personal_access_tokens/self

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

예시 응답: 

{
  "id": 4,
  "name": "Test Token",
  "revoked": false,
  "created_at": "2020-07-23T14:31:47.729Z",
  "scopes": ["api"],
  "user_id": 3,
  "last_used_at": "2021-10-06T17:58:37.550Z",
  "active": true,
  "expires_at": null
}

개인 액세스 토큰 회전

개인 액세스 토큰을 회전합니다. 이전 토큰을 폐기하고 일주일 후에 만료되는 새로운 토큰을 생성합니다.

다음 중 하나를 선택할 수 있습니다:

  • 개인 액세스 토큰 ID를 사용합니다.
  • GitLab 16.10 이상에서 API에 개인 액세스 토큰을 요청 헤더로 전달합니다.

개인 액세스 토큰 ID 사용하기

GitLab 16.6 이상에서 expires_at Parameter를 사용하여 다른 만료 날짜를 설정할 수 있습니다. 이 비표준 만료 날짜는 회전 날짜부터 1년까지입니다. 

POST /personal_access_tokens/:id/rotate
속성 유형 필수 설명
id integer/string yes 개인 액세스 토큰의 ID
expires_at date no ISO 형식(YYYY-MM-DD)으로 된 액세스 토큰의 만료 날짜. GitLab 16.6에서 도입되었습니다.

참고: 관리자가 아닌 사용자는 자신의 토큰을 회전할 수 있습니다. 관리자는 모든 사용자의 토큰을 회전할 수 있습니다. 

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/personal_access_tokens/<personal_access_token_id>/rotate"

예시 응답: 

{
  "id": 42,
  "name": "Rotated Token",
  "revoked": false,
  "created_at": "2023-08-01T15:00:00.000Z",
  "scopes": ["api"],
  "user_id": 1337,
  "last_used_at": null,
  "active": true,
  "expires_at": "2023-08-15",
  "token": "s3cr3t"
}

응답

  • 200: OK 기존 토큰이 성공적으로 폐기되고 새 토큰이 성공적으로 생성된 경우.
  • 400: Bad Request 회전에 실패한 경우.
  • 401: Unauthorized 다음 중 하나:
    • 사용자가 지정된 ID의 토큰에 액세스할 수 없는 경우.
    • 지정된 ID의 토큰이 존재하지 않는 경우.
  • 404: Not Found 사용자가 관리자이지만 지정된 ID의 토큰이 존재하지 않는 경우.

요청 헤더 사용하기

요구 사항:

  • api 스코프.

expires_at Parameter를 사용하여 다른 만료 날짜를 설정할 수 있습니다. 이 비표준 만료 날짜는 회전 날짜부터 1년까지입니다. 

POST /personal_access_tokens/self/rotate

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/personal_access_tokens/self/rotate"

예시 응답: 

{
  "id": 42,
  "name": "Rotated Token",
  "revoked": false,
  "created_at": "2023-08-01T15:00:00.000Z",
  "scopes": ["api"],
  "user_id": 1337,
  "last_used_at": null,
  "active": true,
  "expires_at": "2023-08-15",
  "token": "s3cr3t"
}

응답

  • 200: OK 기존 토큰이 성공적으로 폐기되고 새 토큰이 성공적으로 생성된 경우.
  • 400: Bad Request 회전에 실패한 경우.
  • 401: Unauthorized 다음 중 하나:
    • 토큰이 존재하지 않는 경우.
    • 토큰이 만료되었거나 폐기된 경우.
  • 403: Forbidden 토큰이 자신을 회전할 수 없는 경우.
  • 405: Method Not Allowed 토큰이 개인 액세스 토큰이 아닌 경우.

자동 재사용 감지

각 회전된 토큰마다 이전에 폐기된 토큰이 참조됩니다. 이 참조 연결은 토큰 패밀리를 정의합니다. 토큰 패밀리에서 가장 최근의 토큰만 활성화되며 해당 패밀리의 모든 다른 토큰은 폐기됩니다.

토큰 패밀리에서 폐기된 토큰이 토큰 회전 엔드포인트에 대한 인증 시도에 사용되면 해당 시도가 실패하고 해당 패밀리의 활성 토큰이 폐기됩니다. 이 메커니즘은 개인 액세스 토큰이 유출되었을 때 침해를 방지하는 데 도움이 됩니다.

자동 재사용 감지는 토큰 회전 API 요청에 대해 활성화되어 있습니다.

개인 액세스 토큰 폐기

개인 액세스 토큰을 다음 중 하나로 폐기합니다:

  • 개인 액세스 토큰의 ID 사용.
  • API에 헤더로 전달.

개인 액세스 토큰 ID 사용하기

개인 액세스 토큰을 해당 ID로 폐기합니다. 

DELETE /personal_access_tokens/:id
속성 유형 필수 설명
id integer/string yes 개인 액세스 토큰의 ID

참고: 관리자가 아닌 사용자는 자신의 토큰을 폐기할 수 있습니다. 관리자는 모든 사용자의 토큰을 폐기할 수 있습니다. 

curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/personal_access_tokens/<personal_access_token_id>"

응답

  • 요청이 성공적으로 취소된 경우 204: No Content.
  • 취소가 성공하지 않은 경우 400: Bad Request.
  • 액세스 토큰이 유효하지 않은 경우 401: Unauthorized.
  • 액세스 토큰이 필요한 권한을 갖고 있지 않은 경우 403: Forbidden.

요청 헤더 사용

  • GitLab 15.0에서 도입됨. api 스코프를 가진 토큰에 제한됨.
  • GitLab 15.4에서 도입됨. 이제 모든 토큰이 이 엔드포인트를 사용할 수 있음.

헤더를 통해 전달된 개인 액세스 토큰을 취소합니다. 요구 사항:

  • GitLab 15.0에서 GitLab 15.3까지 api 스코프.
  • GitLab 15.4 이후의 경우 모든 스코프가 필요합니다. 
DELETE /personal_access_tokens/self

curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/personal_access_tokens/self"

응답

  • 성공적으로 취소된 경우 204: No Content.
  • 취소가 성공하지 않은 경우 400: Bad Request.
  • 액세스 토큰이 유효하지 않은 경우 401: Unauthorized.

토큰 연결 목록

현재 인증된 사용자가 액세스할 수 있는 모든 그룹, 하위 그룹 및 프로젝트의 필터되지 않은 목록을 반환합니다. 

GET /personal_access_tokens/self/associations
GET /personal_access_tokens/self/associations?page=2
GET /personal_access_tokens/self/associations?min_access_level=40

지원되는 속성:

속성 타입 필수 설명
min_access_level 정수 아니요 현재 사용자의 최소 역할 (access_level)로 제한합니다.
page 정수 아니요 검색할 페이지입니다. 기본값은 1입니다.
per_page 정수 아니요 페이지당 반환할 레코드 수입니다. 기본값은 20입니다.

예시 요청: 

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

예시 응답: 

{
  "groups": [
    {
      "id": 1,
      "web_url": "http://gitlab.example.com/groups/test",
      "name": "Test",
      "parent_id": null,
      "organization_id": 1,
      "access_levels": 20,
      "visibility": "public"
    },
    {
      "id": 3,
      "web_url": "http://gitlab.example.com/groups/test/test_private",
      "name": "Test Private",
      "parent_id": 1,
      "organization_id": 1,
      "access_levels": 50,
      "visibility": "test_private"
    }
  ],
  "projects": [
    {
      "id": 1337,
      "description": "Leet.",
      "name": "Test Project",
      "name_with_namespace": "Test / Test Project",
      "path": "test-project",
      "path_with_namespace": "Test/test-project",
      "created_at": "2024-07-02T13:37:00.123Z",
      "access_levels": {
        "project_access_level": null,
        "group_access_level": 20
      },
      "visibility": "private",
      "web_url": "http://gitlab.example.com/test/test_project",
      "namespace": {
        "id": 1,
        "name": "Test",
        "path": "Test",
        "kind": "group",
        "full_path": "Test",
        "parent_id": null,
        "avatar_url": null,
        "web_url": "http://gitlab.example.com/groups/test"
      }
    }
  ]
}

개인 액세스 토큰 생성 (관리자 전용)

개인 액세스 토큰을 생성하는 정보는 사용자 토큰 API에서 확인하세요.

현재 인증된 사용자를 위한 스코프가 제한된 개인 액세스 토큰 생성

Tier: Free, Premium, Ultimate Offering: Self-managed, GitLab Dedicated

현재 인증된 사용자를 위한 스코프가 제한된 개인 액세스 토큰 생성에 대한 정보는 사용자 토큰 API에서 확인하세요.

액세스 토큰 문제 해결

액세스 토큰 문제를 해결하려면 토큰 문제 해결 가이드를 참조하세요.