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

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

히스토리

• created_after, created_before, last_used_after, last_used_before, revoked, search 및 state 필터가 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

지원되는 속성:

요청 예시:

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",
        "active": true,
        "expires_at": null
    }
]

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

다른 가능한 응답:

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

개인 액세스 토큰 조회#

히스토리

• GitLab 15.1에서 도입됨.
• GitLab 15.3에서 404 HTTP 상태 코드가 도입됨.

지정된 개인 액세스 토큰의 세부 정보를 조회합니다. 관리자는 모든 토큰의 세부 정보를 조회할 수 있습니다. 비관리자는 자신의 토큰에 대한 세부 정보만 조회할 수 있습니다.

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 속성이 추가됨.

지정된 개인 액세스 토큰을 교체합니다. 이전 토큰을 취소하고 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"
}

성공하면 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"
            }
        }
    ]
}

관련 항목#

• 토큰 문제 해결