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
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
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
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 theapi
orself_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 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 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
orself_rotate
scope. - Use the
self
keyword in the request URL.
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.
Docs
Edit this page to fix an error or add an improvement in a merge request.
Create an issue to suggest an improvement to this page.
Product
Create an issue if there's something you don't like about this feature.
Propose functionality by submitting a feature request.
Feature availability and product trials
View pricing to see all GitLab tiers and features, or to upgrade.
Try GitLab for free with access to all features for 30 days.
Get help
If you didn't find what you were looking for, search the docs.
If you want help with something specific and could use community support, post on the GitLab forum.
For problems setting up or using this feature (depending on your GitLab subscription).
Request support