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

History

Lists all project access tokens for a specified project.

In GitLab 17.2 and later, you can use the state attribute to limit the response to project access tokens with a specified state.

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.
state string No If defined, only 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

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

History

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-rotation.

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

Prerequisites:

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 POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/<project_id>/access_tokens/<token_id>/rotate"

Example response:

{
    "id": 42,
    "name": "Rotated Token",
    "revoked": false,
    "created_at": "2023-08-01T15:00:00.000Z",
    "description": "Test project access token",
    "scopes": ["api"],
    "user_id": 1337,
    "last_used_at": null,
    "active": true,
    "expires_at": "2023-08-15",
    "access_level": 30,
    "token": "s3cr3t"
}

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 a project access token instead.
  • 403: Forbidden if the token is not allowed to rotate itself.
  • 404: Not Found if the user is an administrator but the token with the specified ID does not exist.
  • 405: Method Not Allowed if the token is not a project access token.

Self-rotation

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

Example request:

curl --request POST \
  --header "PRIVATE-TOKEN: <your_project_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/<project_id>/access_tokens/self/rotate"

Revoke a project access token

Revokes a specified project access token.

DELETE 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 yes ID of a project access token.
curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/<project_id>/access_tokens/<token_id>"

If successful, returns 204 No content.

Other possible responses:

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