이 API를 사용하여 개인 액세스 토큰을 관리합니다.

모든 개인 액세스 토큰 목록#

히스토리

• created_after, created_before, last_used_after, last_used_before, revoked, search 및 state 필터가 GitLab 15.5에서 도입됨.
• 응답의 granular_scopes가 GitLab 19.2에서 도입됨.

인증된 사용자가 접근 가능한 모든 개인 액세스 토큰을 나열합니다. 관리자의 경우 인스턴스의 모든 개인 액세스 토큰을 반환합니다. 비관리자의 경우 자신의 개인 액세스 토큰을 모두 반환합니다.

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

지원되는 속성:

요청 예시:

curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/personal_access_tokens?user_id=3&created_before=2022-01-01"

응답 예시:

[
    {
        "id": 4,
        "name": "Test Token",
        "revoked": false,
        "created_at": "2020-07-23T14:31:47.729Z",
        "description": "Test Token description",
        "scopes": [
            "api"
        ],
        "user_id": 3,
        "last_used_at": "2021-10-06T17:58:37.550Z",
        "last_used_ips": ["192.0.2.10"],
        "active": true,
        "expires_at": null,
        "granular_scopes": [
            {
                "access": "selected_memberships",
                "permissions": ["read_job"],
                "project_id": 6,
                "group_id": null
            }
        ]
    }
]

last_used_ips 속성은 이 토큰으로 인증한 최대 5개의 고유 IP 주소를 나열합니다. 한도에 도달하면 가장 오래된 IP 주소가 제거됩니다. 목록은 토큰당 1분에 한 번 업데이트됩니다. granular_scopes 속성은 표준 scopes 속성 대신 세분화된 스코프로 생성된 토큰에만 존재합니다. 각 스코프는 access가 selected_memberships이고 스코프가 프로젝트를 대상으로 하는 경우 project_id를, 그룹을 대상으로 하는 경우 group_id를 가집니다. access가 user, instance, all_memberships 또는 personal_projects인 스코프의 경우 둘 다 null입니다.

성공하면 토큰 목록을 반환합니다.

다른 가능한 응답:

• 비관리자가 다른 사용자를 필터링하기 위해 user_id 속성을 사용하는 경우 401: Unauthorized.

개인 액세스 토큰 조회#

히스토리

• GitLab 15.1에서 도입됨.
• GitLab 15.3에서 404 HTTP 상태 코드가 도입됨.
• 응답의 granular_scopes가 GitLab 19.2에서 도입됨.

지정된 개인 액세스 토큰의 세부 정보를 조회합니다. 관리자는 모든 토큰의 세부 정보를 조회할 수 있습니다. 비관리자는 자신의 토큰에 대한 세부 정보만 조회할 수 있습니다. 응답은 granular_scopes를 포함하여 모든 개인 액세스 토큰 목록과 동일한 속성을 가집니다.

GET /personal_access_tokens/:id

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

성공하면 토큰의 세부 정보를 반환합니다.

다른 가능한 응답:

• 다음 중 하나인 경우 401: Unauthorized:
  • 토큰이 존재하지 않는 경우.
  • 지정된 토큰에 대한 접근 권한이 없는 경우.
• 사용자가 관리자이지만 토큰이 존재하지 않는 경우 404: Not Found.

자기 조회#

히스토리

• GitLab 15.5에서 도입됨

특정 개인 액세스 토큰의 세부 정보를 가져오는 대신 요청을 인증하는 데 사용한 개인 액세스 토큰의 세부 정보를 반환할 수도 있습니다. 이러한 세부 정보를 반환하려면 요청 URL에 self 키워드를 사용해야 합니다.

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

개인 액세스 토큰 생성#

사용자 토큰 API를 사용하여 개인 액세스 토큰을 생성할 수 있습니다. 자세한 내용은 다음 엔드포인트를 참조하세요:

• 개인 액세스 토큰 생성
• 사용자를 위한 개인 액세스 토큰 생성

개인 액세스 토큰 교체#

히스토리

• GitLab 16.0에서 도입됨
• GitLab 16.6에서 expires_at 속성이 추가됨.
• 응답의 granular_scopes가 GitLab 19.2에서 도입됨.

지정된 개인 액세스 토큰을 교체합니다. 이전 토큰을 취소하고 1주일 후 만료되는 새 토큰을 생성합니다. 관리자는 모든 사용자의 토큰을 취소할 수 있습니다. 비관리자는 자신의 토큰만 취소할 수 있습니다.

POST /personal_access_tokens/:id/rotate

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "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",
    "description": "Test Token description",
    "scopes": ["api"],
    "user_id": 1337,
    "last_used_at": null,
    "active": true,
    "expires_at": "2023-08-15",
    "token": "s3cr3t"
}

세분화된 스코프가 있는 토큰을 교체하면 모든 개인 액세스 토큰 목록에 설명된 대로 해당 스코프가 새 토큰의 granular_scopes 속성으로 반환됩니다.

성공하면 200: OK를 반환합니다.

다른 가능한 응답:

• 성공적으로 교체되지 않은 경우 400: Bad Request.
• 다음 조건 중 하나가 true인 경우 401: Unauthorized:
  • 토큰이 존재하지 않는 경우.
  • 토큰이 만료된 경우.
  • 토큰이 취소된 경우.
  • 지정된 토큰에 대한 접근 권한이 없는 경우.
• 토큰이 자체 교체를 허용하지 않는 경우 403: Forbidden.
• 사용자가 관리자이지만 토큰이 존재하지 않는 경우 404: Not Found.
• 토큰이 개인 액세스 토큰이 아닌 경우 405: Method Not Allowed.

자기 교체#

히스토리

• GitLab 16.10에서 도입됨

특정 개인 액세스 토큰을 교체하는 대신 요청을 인증하는 데 사용한 동일한 개인 액세스 토큰을 교체할 수도 있습니다. 개인 액세스 토큰을 자기 교체하려면 다음이 필요합니다:

• api 또는 self_rotate 스코프가 있는 개인 액세스 토큰으로 교체합니다.
• 요청 URL에 self 키워드를 사용합니다.

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

자동 재사용 감지#

히스토리

• GitLab 16.3에서 도입됨

토큰을 교체하거나 취소할 때 GitLab은 이전 토큰과 새 토큰 간의 관계를 자동으로 추적합니다. 새 토큰이 생성될 때마다 이전 토큰과의 연결이 만들어집니다. 이러한 연결된 토큰은 토큰 패밀리를 형성합니다.

API를 사용하여 이미 취소된 액세스 토큰을 교체하려고 하면 동일한 토큰 패밀리의 모든 활성 토큰이 취소됩니다.

이 기능은 이전 토큰이 유출되거나 도난된 경우 GitLab을 보호하는 데 도움이 됩니다. 토큰 관계를 추적하고 이전 토큰이 사용될 때 자동으로 접근을 취소함으로써 공격자가 손상된 토큰을 악용할 수 없습니다.

개인 액세스 토큰 취소#

지정된 개인 액세스 토큰을 취소합니다. 관리자는 모든 사용자의 토큰을 취소할 수 있습니다. 비관리자는 자신의 토큰만 취소할 수 있습니다.

DELETE /personal_access_tokens/:id

curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "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에서 도입됨, 모든 토큰이 이 엔드포인트를 사용할 수 있음.

특정 개인 액세스 토큰을 취소하는 대신 요청을 인증하는 데 사용한 동일한 개인 액세스 토큰을 취소할 수도 있습니다. 개인 액세스 토큰을 자기 취소하려면 요청 URL에 self 키워드를 사용해야 합니다.

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

모든 토큰 연결 목록#

히스토리

• GitLab 17.4에서 도입됨.

요청을 인증하는 데 사용된 개인 액세스 토큰이 접근 가능한 모든 그룹 및 프로젝트를 나열합니다. 일반적으로 사용자가 멤버인 그룹 또는 프로젝트가 포함됩니다.

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

지원되는 속성:

요청 예시:

curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "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"
            }
        }
    ]
}

관련 항목#

• 토큰 문제 해결