Personal access tokens API

{{< details >}}

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

{{< /details >}}

Use this API to interact with personal access tokens.

List all personal access tokens

{{< history >}}

• created_after, created_before, last_used_after, last_used_before, revoked, search and state filters were introduced in GitLab 15.5.

{{< /history >}}

Lists all personal access tokens accessible by the authenticated user. For administrators, returns all personal access tokens in the instance. For non-administrators, returns all of their personal access tokens.

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

Supported attributes:

Example request:

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"

Example response:

[
    {
        "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
    }
]

If successful, returns a list of tokens.

Other possible response:

• 401: Unauthorized if a non-administrator uses the user_id attribute to filter for other users.

Retrieve a personal access token

{{< history >}}

• Introduced in GitLab 15.1.
• 404 HTTP status code introduced in GitLab 15.3.

{{< /history >}}

Retrieves details for a specified personal access token. Administrators can retrieve details on any token. Non-administrators can only retrieve details on their own tokens.

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>"

If successful, returns details on the token.

Other possible responses:

• 401: Unauthorized if either:
  • The token does not exist.
  • You do not have access to the specified token.
• 404: Not Found if the user is an administrator but the token does not exist.

Self-inform

{{< history >}}

• Introduced in GitLab 15.5

{{< /history >}}

Instead of getting details on a specific personal access token, you can also return details on the personal access token you used to authenticate the request. To return these details, you must use the self keyword in the request URL.

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

Create a personal access token

{{< details >}}

• Offering: GitLab Self-Managed, GitLab Dedicated

{{< /details >}}

You can create personal access tokens with the user tokens API. For more information, see the following endpoints:

• Create a personal access token
• Create a personal access token for a user

Rotate a personal access token

{{< history >}}

• Introduced in GitLab 16.0
• expires_at attribute added in GitLab 16.6.

{{< /history >}}

Rotates a specified personal access token. This revokes the previous token and creates a new token that expires after one week. Administrators can revoke tokens for any user. Non-administrators can only revoke their own tokens.

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"

Example response:

{
    "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"
}

If successful, returns 200: OK.

Other possible responses:

• 400: Bad Request if not rotated successfully.
• 401: Unauthorized if any of the following conditions are true:
  • The token does not exist.
  • The token has expired.
  • The token was revoked.
  • You do not have access to the specified token.
• 403: Forbidden if the token is not allowed to rotate itself.
• 404: Not Found if the user is an administrator but the token does not exist.
• 405: Method Not Allowed if the token is not a personal access token.

Self-rotate

{{< history >}}

• Introduced in GitLab 16.10

{{< /history >}}

Instead of rotating a specific personal access token, you can also rotate the same personal access token you used to authenticate the request. To self-rotate a personal access token, you must:

• Rotate a personal access token with the api or self_rotate scope.
• Use the self keyword in the request URL.

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

Automatic reuse detection

{{< history >}}

• Introduced in GitLab 16.3

{{< /history >}}

When you rotate or revoke a token, GitLab automatically tracks the relationship between the old and new tokens. Each time a new token is generated, a connection is made to the previous token. These connected tokens form a token family.

If you attempt to use the API to rotate an access token that was already revoked, any active tokens from the same token family are revoked.

This feature helps secure GitLab if an old token is ever leaked or stolen. By tracking token relationships and automatically revoking access when old tokens are used, attackers cannot exploit compromised tokens.

Revoke a personal access token

Revokes a specified personal access token. Administrators can revoke tokens for any user. Non-administrators can only revoke their own tokens.

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>"

If successful, returns 204: No Content.

Other possible responses:

• 400: Bad Request if not revoked successfully.
• 401: Unauthorized if the request is not authorized.
• 403: Forbidden if the request is not allowed.

Self-revoke

{{< history >}}

• Introduced in GitLab 15.0. Limited to tokens with api scope.
• Introduced in GitLab 15.4, any token can use this endpoint.

{{< /history >}}

Instead of revoking a specific personal access token, you can also revoke the same personal access token you used to authenticate the request. To self-revoke a personal access token, you must use the self keyword in the request URL.

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

List all token associations

{{< history >}}

• Introduced in GitLab 17.4.

{{< /history >}}

Lists all groups and projects accessible by the personal access token used to authenticate the request. Generally, this includes any groups or projects that the user is a member of.

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

Supported attributes:

Example request:

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

Example response:

{
    "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"
            }
        }
    ]
}

Related topics

• Token troubleshooting