• List personal access tokens
• Get single personal access token
  • Using a personal access token ID
    • Responses
  • Using a request header
• Rotate a personal access token
  • Responses
  • Automatic reuse detection
• Revoke a personal access token
  • Using a personal access token ID
    • Responses
  • Using a request header
    • Responses
• Create a personal access token (administrator only)

Personal access tokens API

You can read more about personal access tokens.

List personal access tokens

Get all personal access tokens the authenticated user has access to. By default, returns an unfiltered list of:

• Only personal access tokens created by the current user to a non-administrator.
• All personal access tokens to an administrator.

Administrators:

• Can use the user_id parameter to filter by a user.
• Can use other filters on all personal access tokens (GitLab 15.5 and later).

Non-administrators:

• Cannot use the user_id parameter to filter on any user except themselves, otherwise they receive a 401 Unauthorized response.
• Can only filter on their own personal access tokens (GitLab 15.5 and later).

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 --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/personal_access_tokens"

Example response:

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

Example request:

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/personal_access_tokens?user_id=3"

Example response:

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

Example request:

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/personal_access_tokens?revoked=true"

Example response:

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

You can filter by merged attributes with:

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

Get single personal access token

Get a personal access token by either:

• Using the ID of the personal access token.
• Passing it to the API in a header.

Using a personal access token ID

Get a single personal access token by its ID. Users can get their own tokens. Administrators can get any token.

GET /personal_access_tokens/:id

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

Responses

• 401: Unauthorized if either:
  • The user doesn’t have access to the token with the specified ID.
  • The token with the specified ID doesn’t exist.
• 404: Not Found if the user is an administrator but the token with the specified ID doesn’t exist.

Using a request header

Get a single personal access token and information about that token by passing the token in a header.

GET /personal_access_tokens/self

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

Example response:

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

Rotate a personal access token

Rotate a personal access token. Revokes the previous token and creates a new token that expires in one week.

POST /personal_access_tokens/:id/rotate

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

Responses

• 200: OK if the existing token is successfully revoked and the new token successfully created.
• 400: Bad Request if not rotated successfully.
• 401: Unauthorized if either the:
  • User does not have access to the token with the specified ID.
  • Token with the specified ID does not exist.
• 404: Not Found if the user is an administrator but the token with the specified ID does not exist.

Automatic reuse detection

For each rotated token, the previous and now revoked token is referenced. This chain of references defines a token family. In a token family, only the latest token is active, and all other tokens in that family are revoked.

When a revoked token from a token family is used in an authentication attempt for the token rotation endpoint, that attempt fails and the active token from the token family gets revoked. This mechanism helps to prevent compromise when a personal access token is leaked.

Automatic reuse detection is enabled for token rotation API requests.

Revoke a personal access token

Revoke a personal access token by either:

• Using the ID of the personal access token.
• Passing it to the API in a header.

Using a personal access token ID

Revoke a personal access token using its ID.

DELETE /personal_access_tokens/:id

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

Responses

• 204: No Content if successfully revoked.
• 400: Bad Request if not revoked successfully.

Using a request header

Revokes a personal access token that is passed in using a request header. Requires:

• api scope in GitLab 15.0 to GitLab 15.3.
• Any scope in GitLab 15.4 and later.

DELETE /personal_access_tokens/self

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

Responses

• 204: No Content if successfully revoked.
• 400: Bad Request if not revoked successfully.

Create a personal access token (administrator only)

See the Users API documentation for information on creating a personal access token.