2020-10-28 11:08:49 -04:00
---
2022-09-14 05:12:58 -04:00
stage: Govern
2020-11-17 10:09:28 -05:00
group: Compliance
2022-09-21 17:13:33 -04:00
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments
2020-10-28 11:08:49 -04:00
---
2021-09-10 05:11:07 -04:00
# Personal access tokens API **(FREE)**
2020-08-06 17:10:15 -04:00
You can read more about [personal access tokens ](../user/profile/personal_access_tokens.md#personal-access-tokens ).
## List personal access tokens
2021-09-10 05:11:07 -04:00
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/227264) in GitLab 13.3.
> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/270200) from GitLab Ultimate to GitLab Free in 13.6.
2022-09-21 02:13:35 -04:00
> - `created_after`, `created_before`, `last_used_after`, `last_used_before`, `revoked`, `search` and `state` filters were [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/362248) in GitLab 15.5.
2020-08-06 17:10:15 -04:00
2022-09-20 05:10:52 -04:00
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.
2022-09-21 02:13:35 -04:00
- Can use other filters on all personal access tokens (GitLab 15.5 and later).
2022-09-20 05:10:52 -04:00
Non-administrators:
- Cannot use the `user_id` parameter to filter on any user except themselves, otherwise they receive a `401 Unauthorized` response.
2022-09-21 02:13:35 -04:00
- Can only filter on their own personal access tokens (GitLab 15.5 and later).
2020-08-06 17:10:15 -04:00
```plaintext
GET /personal_access_tokens
2022-09-20 05:10:52 -04:00
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
2020-08-06 17:10:15 -04:00
```
2022-09-20 05:10:52 -04:00
Supported attributes:
2020-08-06 17:10:15 -04:00
2022-09-20 05:10:52 -04:00
| Attribute | Type | Required | Description |
|---------------------|----------------|----------|---------------------|
| `created_after` | datetime (ISO 8601) | ** {dotted-circle}** No | Limit results to PATs created after specified time. |
| `created_before` | datetime (ISO 8601) | ** {dotted-circle}** No | Limit results to PATs created before specified time. |
| `last_used_after` | datetime (ISO 8601) | ** {dotted-circle}** No | Limit results to PATs last used after specified time. |
| `last_used_before` | datetime (ISO 8601) | ** {dotted-circle}** No | Limit results to PATs last used before specified time. |
| `revoked` | boolean | ** {dotted-circle}** No | Limit results to PATs with specified revoked state. Valid values are `true` and `false` . |
| `search` | string | ** {dotted-circle}** No | Limit results to PATs with name containing search string. |
| `state` | string | ** {dotted-circle}** No | Limit results to PATs with specified state. Valid values are `active` and `inactive` . |
| `user_id` | integer or string | ** {dotted-circle}** No | Limit results to PATs owned by specified user. |
Example request:
2020-08-06 17:10:15 -04:00
```shell
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/personal_access_tokens"
```
2022-09-20 05:10:52 -04:00
Example response:
2020-08-06 17:10:15 -04:00
```json
2020-10-08 08:08:31 -04:00
[
2020-08-06 17:10:15 -04:00
{
"id": 4,
"name": "Test Token",
"revoked": false,
"created_at": "2020-07-23T14:31:47.729Z",
"scopes": [
"api"
],
"user_id": 24,
2021-12-01 13:15:19 -05:00
"last_used_at": "2021-10-06T17:58:37.550Z",
"active": true,
2020-08-06 17:10:15 -04:00
"expires_at": null
}
]
```
2022-09-20 05:10:52 -04:00
Example request:
2020-08-06 17:10:15 -04:00
```shell
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/personal_access_tokens?user_id=3"
```
2022-09-20 05:10:52 -04:00
Example response:
2020-08-06 17:10:15 -04:00
```json
2020-10-08 08:08:31 -04:00
[
2020-08-06 17:10:15 -04:00
{
"id": 4,
"name": "Test Token",
"revoked": false,
"created_at": "2020-07-23T14:31:47.729Z",
"scopes": [
"api"
],
"user_id": 3,
2021-12-01 13:15:19 -05:00
"last_used_at": "2021-10-06T17:58:37.550Z",
"active": true,
2020-08-06 17:10:15 -04:00
"expires_at": null
}
]
```
2020-08-13 14:10:36 -04:00
2022-09-20 05:10:52 -04:00
Example request:
```shell
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/personal_access_tokens?revoked=true"
```
Example response:
```json
[
{
"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:
```plaintext
GET /personal_access_tokens?revoked=true& created_before=2022-01-01
```
2022-09-20 11:13:52 -04:00
## 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
2022-05-26 11:08:29 -04:00
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/362239) in GitLab 15.1.
Get a single personal access token by its ID. Users can get their own tokens.
Administrators can get any token.
```plaintext
GET /personal_access_tokens/:id
```
2022-09-20 05:10:52 -04:00
| Attribute | Type | Required | Description |
2022-05-26 11:08:29 -04:00
|-----------|---------|----------|---------------------|
| `id` | integer/string | yes | ID of personal access token |
```shell
curl --request GET --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/personal_access_tokens/< id > "
```
2022-09-20 11:13:52 -04:00
#### Responses
2022-05-26 11:08:29 -04:00
2022-08-04 08:11:22 -04:00
> `404` HTTP status code [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/93650) 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.
2022-05-26 11:08:29 -04:00
2022-09-20 11:13:52 -04:00
### Using a request header
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/373999) in GitLab 15.5
Get a single personal access token by using passing the token in a header.
```plaintext
GET /personal_access_tokens/self
```
```shell
curl --request GET --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/personal_access_tokens/self"
```
Example response:
```json
{
"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
}
```
2020-08-13 14:10:36 -04:00
## Revoke a personal access token
2022-05-17 05:08:20 -04:00
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
2022-05-13 08:08:49 -04:00
2021-09-10 05:11:07 -04:00
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216004) in GitLab 13.3.
> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/270200) from GitLab Ultimate to GitLab Free in 13.6.
2020-08-13 14:10:36 -04:00
2022-05-17 05:08:20 -04:00
Revoke a personal access token using its ID.
2020-08-13 14:10:36 -04:00
```plaintext
DELETE /personal_access_tokens/:id
```
2022-09-20 05:10:52 -04:00
| Attribute | Type | Required | Description |
2020-08-13 14:10:36 -04:00
|-----------|---------|----------|---------------------|
| `id` | integer/string | yes | ID of personal access token |
2020-12-04 16:09:29 -05:00
NOTE:
2020-08-13 14:10:36 -04:00
Non-administrators can revoke their own tokens. Administrators can revoke tokens of any user.
```shell
curl --request DELETE --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/personal_access_tokens/< personal_access_token_id > "
```
2022-05-13 08:08:49 -04:00
#### Responses
- `204: No Content` if successfully revoked.
- `400: Bad Request` if not revoked successfully.
2022-05-17 05:08:20 -04:00
### Using a request header
2022-05-13 08:08:49 -04:00
2022-09-05 08:13:20 -04:00
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/350240) in GitLab 15.0. Limited to tokens with `api` scope.
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/369103) in GitLab 15.4, any token can use this endpoint.
2022-05-13 08:08:49 -04:00
2022-09-05 08:13:20 -04:00
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.
2022-05-13 08:08:49 -04:00
```plaintext
DELETE /personal_access_tokens/self
```
```shell
curl --request DELETE --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/personal_access_tokens/self"
```
#### Responses
2020-08-13 14:10:36 -04:00
- `204: No Content` if successfully revoked.
2022-05-13 08:08:49 -04:00
- `400: Bad Request` if not revoked successfully.
2020-11-16 07:09:05 -05:00
2021-09-23 02:12:14 -04:00
## Create a personal access token (administrator only)
2020-11-16 07:09:05 -05:00
2020-12-24 07:10:03 -05:00
See the [Users API documentation ](users.md#create-a-personal-access-token ) for information on creating a personal access token.