debian-mirror-gitlab/doc/api/personal_access_tokens.md

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

152 lines
4.4 KiB
Markdown
Raw Normal View History

2021-01-29 00:20:46 +05:30
---
stage: Manage
group: Compliance
2021-02-22 17:27:13 +05:30
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
2021-01-29 00:20:46 +05:30
---
2021-11-11 11:23:49 +05:30
# Personal access tokens API **(FREE)**
2020-10-24 23:57:45 +05:30
You can read more about [personal access tokens](../user/profile/personal_access_tokens.md#personal-access-tokens).
## List personal access tokens
2021-11-11 11:23:49 +05:30
> - [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-10-24 23:57:45 +05:30
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 |
2021-02-22 17:27:13 +05:30
NOTE:
2020-10-24 23:57:45 +05:30
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
2021-01-03 14:25:43 +05:30
[
2020-10-24 23:57:45 +05:30
{
"id": 4,
"name": "Test Token",
"revoked": false,
"created_at": "2020-07-23T14:31:47.729Z",
"scopes": [
"api"
],
"user_id": 24,
2022-01-26 12:08:38 +05:30
"last_used_at": "2021-10-06T17:58:37.550Z",
"active": true,
2020-10-24 23:57:45 +05:30
"expires_at": null
}
]
```
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/personal_access_tokens?user_id=3"
```
```json
2021-01-03 14:25:43 +05:30
[
2020-10-24 23:57:45 +05:30
{
"id": 4,
"name": "Test Token",
"revoked": false,
"created_at": "2020-07-23T14:31:47.729Z",
"scopes": [
"api"
],
"user_id": 3,
2022-01-26 12:08:38 +05:30
"last_used_at": "2021-10-06T17:58:37.550Z",
"active": true,
2020-10-24 23:57:45 +05:30
"expires_at": null
}
]
```
2022-07-23 23:45:48 +05:30
## Get single personal access token by ID
> [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
```
| Attribute | Type | required | Description |
|-----------|---------|----------|---------------------|
| `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>"
```
### Responses
- `401: Unauthorized` if the user doesn't have access to the token they're requesting the ID or if the token with matching ID doesn't exist.
2020-10-24 23:57:45 +05:30
## Revoke a personal access token
2022-07-16 23:28:13 +05:30
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
2021-11-11 11:23:49 +05:30
> - [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-10-24 23:57:45 +05:30
2022-07-16 23:28:13 +05:30
Revoke a personal access token using its ID.
2020-10-24 23:57:45 +05:30
```plaintext
DELETE /personal_access_tokens/:id
```
| Attribute | Type | required | Description |
|-----------|---------|----------|---------------------|
| `id` | integer/string | yes | ID of personal access token |
2021-02-22 17:27:13 +05:30
NOTE:
2020-10-24 23:57:45 +05:30
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-07-16 23:28:13 +05:30
#### Responses
- `204: No Content` if successfully revoked.
- `400: Bad Request` if not revoked successfully.
### Using a request header
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/350240) in GitLab 15.0.
Revokes a personal access token that is passed in using a request header.
```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-10-24 23:57:45 +05:30
- `204: No Content` if successfully revoked.
2022-07-16 23:28:13 +05:30
- `400: Bad Request` if not revoked successfully.
2021-01-29 00:20:46 +05:30
2021-11-18 22:05:49 +05:30
## Create a personal access token (administrator only)
2021-01-29 00:20:46 +05:30
2021-03-08 18:12:59 +05:30
See the [Users API documentation](users.md#create-a-personal-access-token) for information on creating a personal access token.