Project access tokens API

Tier: Free, Premium, Ultimate
Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

Use this API to interact with project access tokens. For more information, see Project access tokens.

List all project access tokens

Version history

state attribute introduced in GitLab 17.2.

Lists all project access tokens for a specified project.

GET projects/:id/access_tokens
GET projects/:id/access_tokens?state=inactive

Attribute	Type	required	Description
`id`	integer or string	yes	ID or URL-encoded path of a project.
`created_after`	datetime (ISO 8601)	No	If defined, returns tokens created after the specified time.
`created_before`	datetime (ISO 8601)	No	If defined, returns tokens created before the specified time.
`last_used_after`	datetime (ISO 8601)	No	If defined, returns tokens last used after the specified time.
`last_used_before`	datetime (ISO 8601)	No	If defined, returns tokens last used before the specified time.
`revoked`	boolean	No	If `true`, only returns revoked tokens.
`search`	string	No	If defined, returns tokens that include the specified value in the name.
`state`	string	No	If defined, returns tokens with the specified state. Possible values: `active` and `inactive`.

curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/<project_id>/access_tokens"

[
   {
      "user_id" : 141,
      "scopes" : [
         "api"
      ],
      "name" : "token",
      "expires_at" : "2021-01-31",
      "id" : 42,
      "active" : true,
      "created_at" : "2021-01-20T22:11:48.151Z",
      "last_used_at" : null,
      "revoked" : false,
      "access_level" : 40
   },
   {
      "user_id" : 141,
      "scopes" : [
         "read_api"
      ],
      "name" : "token-2",
      "expires_at" : "2021-01-31",
      "id" : 43,
      "active" : false,
      "created_at" : "2021-01-21T12:12:38.123Z",
      "revoked" : true,
      "last_used_at" : "2021-02-13T10:34:57.178Z",
      "access_level" : 40
   }
]

Get details on a project access token

Gets details on a project access token. You can either reference a specific project access token, or use the keyword self to return details on the authenticating project access token.

GET projects/:id/access_tokens/:token_id

Attribute	Type	required	Description
`id`	integer or string	yes	ID or URL-encoded path of a project.
`token_id`	integer or string	yes	ID of a project access token or the keyword `self`.

curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/<project_id>/access_tokens/<token_id>"

{
   "user_id" : 141,
   "scopes" : [
      "api"
   ],
   "name" : "token",
   "expires_at" : "2021-01-31",
   "id" : 42,
   "active" : true,
   "created_at" : "2021-01-20T22:11:48.151Z",
   "revoked" : false,
   "access_level": 40,
   "last_used_at": "2022-03-15T11:05:42.437Z"
}

Create a project access token

Version history

The expires_at attribute default was introduced in GitLab 16.0.

Creates a project access token for a specified project. You cannot create a token with an access level greater than your account. For example, a user with the Maintainer role cannot create a project access token with the Owner role.

POST projects/:id/access_tokens

Attribute	Type	required	Description
`id`	integer or string	yes	ID or URL-encoded path of a project.
`name`	string	yes	Name of the token.
`scopes`	`Array[String]`	yes	List of scopes available to the token.
`access_level`	integer	no	Access level for the token. Possible values: `10` (Guest), `15` (Planner), `20` (Reporter), `30` (Developer), `40` (Maintainer), and `50` (Owner). Default value: `40`.
`expires_at`	date	yes	Expiration date of the token in ISO format (`YYYY-MM-DD`). If undefined, the date is set to the maximum allowable lifetime limit.

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header "Content-Type:application/json" \
  --data '{ "name":"test_token", "scopes":["api", "read_repository"], "expires_at":"2021-01-31", "access_level":30 }' \
  --url "https://gitlab.example.com/api/v4/projects/<project_id>/access_tokens"

{
   "scopes" : [
      "api",
      "read_repository"
   ],
   "active" : true,
   "name" : "test",
   "revoked" : false,
   "created_at" : "2021-01-21T19:35:37.921Z",
   "user_id" : 166,
   "id" : 58,
   "expires_at" : "2021-01-31",
   "token" : "D4y...Wzr",
   "access_level": 30
}

Rotate a project access token

Version history

Introduced in GitLab 16.0
expires_at attribute added in GitLab 16.6.

Rotates a project access token. This immediately revokes the previous token and creates a new token. Generally, this endpoint rotates a specific project access token by authenticating with a personal access token. You can also use a project access token to rotate itself. For more information, see Self-rotate.

If you attempt to use the revoked token later, GitLab immediately revokes the new token. For more information, see Automatic reuse detection.

Prerequisites:

A personal access token with the api scope or a project access token with the api or self_rotate scope. See Self-rotate.

POST /projects/:id/access_tokens/:token_id/rotate

Attribute	Type	required	Description
`id`	integer or string	yes	ID or URL-encoded path of a project.
`token_id`	integer or string	yes	ID of a project access token or the keyword `self`.
`expires_at`	date	no	Expiration date of the access token in ISO format (`YYYY-MM-DD`). The date must be one year or less from the rotation date. If undefined, the token expires after one week.

curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/<project_id>/access_tokens"
```0

Example response:

```shell
curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/<project_id>/access_tokens"
```1

If successful, returns `200: OK`.

Other possible responses:

- `400: Bad Request` if not rotated successfully.
- `401: Unauthorized` if any of the following conditions are true:
  - The token does not exist.
  - The token has expired.
  - The token was revoked.
  - You do not have access to the specified token.
  - You're using a project access token to rotate another project access token. See [Self-rotate](#self-rotate) instead.
- `403: Forbidden` if the token is not allowed to rotate itself.
- `404: Not Found` if the user is an administrator but the token does not exist.
- `405: Method Not Allowed` if the token is not a project access token.

### Self-rotate

Instead of rotating a specific project access token, you can rotate the same project access token you used to authenticate the request. To self-rotate a project access token, you must:

- Rotate a project access token with the [`api` or `self_rotate` scope](../user/profile/personal_access_tokens.md#personal-access-token-scopes).
- Use the `self` keyword in the request URL.

Example request:

```shell
curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/<project_id>/access_tokens"
```2

## Revoke a project access token

Revokes a specified project access token.

```shell
curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/<project_id>/access_tokens"
```3

| Attribute  | Type              | required | Description |
| ---------- | ----------------- | -------- | ----------- |
| `id`       | integer or string | yes      | ID or [URL-encoded path](rest/_index.md#namespaced-paths) of a project. |
| `token_id` | integer           | yes      | ID of a project access token. |

```shell
curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/<project_id>/access_tokens"
```4

If successful, returns `204 No content`.

Other possible responses:

- `400 Bad Request`: Token was not revoked.
- `404 Not Found`: Token can not be found.