개인 액세스 토큰 API

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

개인 액세스 토큰에 대해 자세히 알아보세요.

개인 액세스 토큰 목록

  • GitLab 13.3에서 도입됨.
  • GitLab Ultimate에서 GitLab Free로 이동됨 (13.6).
  • GitLab 15.5에서 created_after, created_before, last_used_after, last_used_before, revoked, search 및 state 필터가 도입됨.

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

  • 현재 사용자가 생성 한 개인 액세스 토큰에서 관리자가 아닌 사람에게.
  • 관리자에게는 모든 개인 액세스 토큰이 포함됩니다.

관리자: - 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": "테스트 토큰",
        "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": "테스트 토큰",
        "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": 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 상태 코드 소개 in GitLab 15.3.
  • 다음의 경우 401: Unauthorized:
    • 사용자가 지정된 ID의 토큰에 액세스할 수 없는 경우
    • 지정된 ID로 된 토큰이 존재하지 않는 경우
  • 다음의 경우 404: Not Found:
    • 사용자가 관리자이지만 지정된 ID의 토큰이 존재하지 않는 경우

요청 헤더 사용

헤더에 토큰을 전달하여 단일 개인 액세스 토큰 및 해당 토큰에 대한 정보를 받습니다. 

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": "테스트 토큰",
    "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 매개변수를 사용하여 다른 만료 날짜를 설정할 수 있습니다. 기본 이외의 만료 날짜는 회전 날짜로부터 최대 일년까지 될 수 있습니다. 

POST /personal_access_tokens/:id/rotate
속성 유형 필수 설명
id 정수/문자열 예 개인 액세스 토큰의 ID
expires_at 날짜 아니오 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": "회전된 토큰",
    "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": "비밀번호"
}

응답

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

요청 헤더 사용

사용자가 다른 만료 날짜를 설정하기 위해 expires_at 매개변수를 사용할 수 있습니다. 기본 이외의 만료 날짜는 회전 날짜로부터 최대 일년까지 될 수 있습니다. 

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": "회전된 토큰",
    "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": "비밀번호"
}

응답

  • 200: OK - 기존 토큰이 성공적으로 폐기되고 새 토큰이 성공적으로 생성될 경우.
  • 400: Bad Request - 성공적으로 회전되지 않은 경우.
  • 401: Unauthorized - 다음 중 하나인 경우:
    • 토큰이 존재하지 않음.
    • 토큰의 유효 기간이 만료됨.
    • 토큰이 폐기됨.
  • 403: Forbidden - 토큰이 자체 회전을 허용하지 않는 경우.
  • 405: Method Not Allowed - 토큰이 개인 액세스 토큰이 아닌 경우.

자동 재사용 감지

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

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

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

개인 액세스 토큰 폐기

ID를 사용하여 개인 액세스 토큰을 폐기하려면 다음 중 하나를 사용하세요:

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

개인 액세스 토큰 ID 사용

  • GitLab 13.3에서 도입됨.
  • GitLab 13.6에서 GitLab Ultimate에서 GitLab Free로 이동됨.

개인 액세스 토큰의 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 - 성공적으로 폐기되지 않은 경우.

요청 헤더 사용

  • 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 - 성공적으로 폐기되지 않은 경우.

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

현재 사용자에 대해 제한된 범위로 개인 액세스 토큰을 생성하는 방법에 대한 정보는 사용자 API 설명서를 참조하세요.

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

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

현재 인증된 사용자를 위해 제한된 범위로 개인 액세스 토큰을 생성하는 방법에 대한 정보는 사용자 API 설명서를 참조하세요.