개인 액세스 토큰 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 필터는 도입되었습니다 in 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 boolean 아니오 특정 해지 상태를 가진 PAT로 결과 제한. 유효한 값은 true 및 false입니다.
search string 아니오 검색 문자열을 포함하는 이름의 PAT로 결과 제한.
state string 아니오 특정 상태를 가진 PAT로 결과 제한. 유효한 값은 active 및 inactive입니다.
user_id integer 또는 string 아니오 특정 사용자가 소유한 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 integer/string 예 개인 액세스 토큰의 ID 
curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/personal_access_tokens/<id>"

응답

  • 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": "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
}

개인 액세스 토큰 회전

개인 액세스 토큰을 회전합니다. 이전 토큰을 취소하고 1주일 후 만료되는 새 토큰을 생성합니다.

다음 방법 중 하나를 사용할 수 있습니다:

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

개인 액세스 토큰 ID 사용

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

POST /personal_access_tokens/:id/rotate
속성 유형 필수 설명
id integer/string 예 개인 액세스 토큰의 ID
expires_at date 아니오 액세스 토큰의 만료 날짜, 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 매개변수를 사용하여 다른 만료 날짜를 설정할 수 있습니다. 이 비기본 만료 날짜는 회전일로부터 최대 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 정수/문자열 예 개인 접근 토큰의 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": "테스트",
        "parent_id": null,
        "organization_id": 1,
        "access_levels": 20,
        "visibility": "public"
        },
        {
        "id": 3,
        "web_url": "http://gitlab.example.com/groups/test/test_private",
        "name": "테스트 개인",
        "parent_id": 1,
        "organization_id": 1,
        "access_levels": 50,
        "visibility": "test_private"
        }
    ],
    "projects": [
        {
            "id": 1337,
            "description": "리트.",
            "name": "테스트 프로젝트",
            "name_with_namespace": "테스트 / 테스트 프로젝트",
            "path": "test-project",
            "path_with_namespace": "테스트/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": "테스트",
                "path": "테스트",
                "kind": "group",
                "full_path": "테스트",
                "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를 참조하세요.

액세스 토큰 문제 해결

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