개인 액세스 토큰 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": "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
    }
]

아래와 같이 Merge된 속성으로 필터링할 수 있습니다: 

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

단일 개인 액세스 토큰 가져오기

개인 액세스 토큰을 얻으려면 다음 중 하나를 사용하십시오:

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

개인 액세스 토큰 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에서 도입되었습니다.

  • 401: Unauthorized는 다음 중 하나인 경우 발생합니다:
    • 사용자가 지정된 ID의 토큰에 액세스 할 수 없는 경우.
    • 지정된 ID의 토큰이 존재하지 않는 경우.
  • 사용자가 관리자이지만 지정된 ID의 토큰이 존재하지 않는 경우 404: Not Found가 발생합니다.

요청 헤더 사용

GitLab 15.5에서 도입되었습니다.

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

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.0에서 도입되었습니다.

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

POST /personal_access_tokens/:id/rotate
속성 유형 필수여부 설명
id 정수/문자열 예 개인 액세스 토큰의 ID
expires_at 날짜 아니요 액세스 토큰의 만료 날짜(ISO 형식: YYYY-MM-DD). 도입됨 in GitLab 16.6.
note
관리자가 아닌 사용자는 자체 토큰을 회전할 수 있습니다. 관리자는 모든 사용자의 토큰을 회전할 수 있습니다.
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입니다.
  • 사용자가 지정된 ID의 토큰에 액세스 할 수 없는 경우 또는 지정된 ID의 토큰이 존재하지 않는 경우 401: Unauthorized입니다.
  • 사용자가 관리자인데 지정된 ID의 토큰이 존재하지 않는 경우 404: Not Found입니다.

요청 헤더 사용

GitLab 16.10에서 도입되었습니다.

필요 사항:

  • api 범위.

expires_at 매개변수를 사용하여 다른 만료 날짜를 설정할 수 있습니다. 이 비표준 만료 날짜는 회전 날짜로부터 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입니다.

자동 재사용 감지

GitLab 16.3에서 도입되었습니다.

각 회전된 토큰마다 이전에 취소된 토큰을 참조합니다. 이러한 참조 연쇄는 토큰 패밀리를 정의합니다. 토큰 패밀리에서 최신 토큰만 활성화되며 해당 패밀리의 다른 모든 토큰은 취소됩니다.

토큰 패밀리에서 취소된 토큰을 인증 시도에 사용하면 그 시도는 실패하고 해당 패밀리의 활성 토큰이 취소됩니다. 이 기구는 개인 액세스 토큰이 유출됐을 때의 침해를 방지하는 데 도움이 됩니다.

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

개인 액세스 토큰 취소

다음 중 하나를 사용하여 개인 액세스 토큰을 취소합니다:

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

개인 액세스 토큰 ID 사용

개인 액세스 토큰의 ID를 사용하여 개인 액세스 토큰을 취소합니다. 

DELETE /personal_access_tokens/:id
속성 유형 필수 여부 설명
id 정수/문자열 예 개인 액세스 토큰의 ID
note
관리자가 아닌 사용자는 자신의 토큰을 취소할 수 있습니다. 관리자는 모든 사용자의 토큰을 취소할 수 있습니다.
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 설명서를 참조하세요.