2020-10-28 15:08:49 +00:00
---
2020-11-17 15:09:28 +00:00
stage: Manage
group: Compliance
2020-11-26 06:09:20 +00:00
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
2020-10-28 15:08:49 +00:00
---
2021-09-10 09:11:07 +00:00
# Personal access tokens API **(FREE)**
2020-08-06 21:10:15 +00: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 09:11:07 +00: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.
2020-08-06 21:10:15 +00:00
Get a list of personal access tokens.
```plaintext
GET /personal_access_tokens
```
| Attribute | Type | required | Description |
|-----------|---------|----------|---------------------|
| `user_id` | integer/string | no | The ID of the user to filter by |
2020-12-04 21:09:29 +00:00
NOTE:
2020-08-06 21:10:15 +00:00
Administrators can use the `user_id` parameter to filter by a user. Non-administrators cannot filter by any user except themselves. Attempting to do so will result in a `401 Unauthorized` response.
```shell
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/personal_access_tokens"
```
```json
2020-10-08 12:08:31 +00:00
[
2020-08-06 21:10:15 +00:00
{
"id": 4,
"name": "Test Token",
"revoked": false,
"created_at": "2020-07-23T14:31:47.729Z",
"scopes": [
"api"
],
"active": true,
"user_id": 24,
"expires_at": null
}
]
```
```shell
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/personal_access_tokens?user_id=3"
```
```json
2020-10-08 12:08:31 +00:00
[
2020-08-06 21:10:15 +00:00
{
"id": 4,
"name": "Test Token",
"revoked": false,
"created_at": "2020-07-23T14:31:47.729Z",
"scopes": [
"api"
],
"active": true,
"user_id": 3,
"expires_at": null
}
]
```
2020-08-13 18:10:36 +00:00
## Revoke a personal access token
2021-09-10 09:11:07 +00: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 18:10:36 +00:00
Revoke a personal access token.
```plaintext
DELETE /personal_access_tokens/:id
```
| Attribute | Type | required | Description |
|-----------|---------|----------|---------------------|
| `id` | integer/string | yes | ID of personal access token |
2020-12-04 21:09:29 +00:00
NOTE:
2020-08-13 18:10:36 +00: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 > "
```
### Responses
- `204: No Content` if successfully revoked.
- `400 Bad Request` if not revoked successfully.
2020-11-16 12:09:05 +00:00
2021-09-23 06:12:14 +00:00
## Create a personal access token (administrator only)
2020-11-16 12:09:05 +00:00
2020-12-24 12:10:03 +00:00
See the [Users API documentation ](users.md#create-a-personal-access-token ) for information on creating a personal access token.