Personal access tokens API

You can read more about personal access tokens.

List personal access tokens

Version history
  • Introduced in GitLab 13.3.
  • Moved from GitLab Ultimate to GitLab Free in 13.6.
  • created_after, created_before, last_used_after, last_used_before, revoked, search and state filters were introduced in GitLab 15.5.

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:

AttributeTypeRequiredDescription
created_afterdatetime (ISO 8601) NoLimit results to PATs created after specified time.
created_beforedatetime (ISO 8601) NoLimit results to PATs created before specified time.
last_used_afterdatetime (ISO 8601) NoLimit results to PATs last used after specified time.
last_used_beforedatetime (ISO 8601) NoLimit results to PATs last used before specified time.
revokedboolean NoLimit results to PATs with specified revoked state. Valid values are true and false.
searchstring NoLimit results to PATs with name containing search string.
statestring NoLimit results to PATs with specified state. Valid values are active and inactive.
user_idinteger or string NoLimit results to PATs owned by specified user.

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

Introduced in GitLab 15.1.

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
AttributeTypeRequiredDescription
idinteger/stringyesID of personal access token
curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/personal_access_tokens/<id>"

Responses

404 HTTP status code introduced in GitLab 15.3.

  • 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

Introduced in GitLab 15.5

Get a single personal access token by using 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
}

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

Version history
  • Introduced in GitLab 13.3.
  • Moved from GitLab Ultimate to GitLab Free in 13.6.

Revoke a personal access token using its ID.

DELETE /personal_access_tokens/:id
AttributeTypeRequiredDescription
idinteger/stringyesID of personal access token
note
Non-administrators can revoke their own tokens. Administrators can revoke tokens of any user.
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

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

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.