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, seeProject access tokens.

List all project access tokens

History

Lists all project access tokens for a specified project.

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

Attribute	Type	Required	Description
`id`	integer or string	yes	ID orURL-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.
`expires_after`	date (ISO 8601)	No	If defined, returns tokens that expire after the specified time.
`expires_before`	date (ISO 8601)	No	If defined, returns tokens that expire 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.
`sort`	string	No	If defined, sorts the results by the specified value. Possible values:`created_asc`,`created_desc`,`expires_asc`,`expires_desc`,`last_used_asc`,`last_used_desc`,`name_asc`,`name_desc`.
`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","description":"Test Token description","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","description":"Test Token description","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.

GET projects/:id/access_tokens/:token_id

Attribute	Type	required	Description
`id`	integer or string	yes	ID orURL-encoded path of a project.
`token_id`	integer or string	yes	ID

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","description":"Test Token description","revoked" :false,"access_level":40,"last_used_at":"2022-03-15T11:05:42.437Z"}

Create a project access token

History

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.

You must use a personal access token with this endpoint. You cannot authenticate with a project access token. There is anopen feature request to add this functionality.

POST projects/:id/access_tokens

Attribute	Type	required	Description
`id`	integer or string	yes	ID orURL-encoded path of a project.
`name`	string	yes	Name of the token.
`description`	string	no	Description of the project access token.
`scopes`	`Array[String]`	yes	List ofscopes available to the token.
`access_level`	integer	no	Role 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 themaximum allowable lifetime limit.

curl --request POST\  --header"PRIVATE-TOKEN: <your_personal_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","description":"Test Token description","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, seeSelf-rotate.

If you attempt to use this endpoint to rotate a token that was previously revoked, any active tokens from the sametoken family are revoked. For more information, seeAutomatic reuse detection.

Prerequisites:

A personal access token with theapi scope or a project access token with theapi orself_rotate scope. SeeSelf-rotate.

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

Attribute	Type	required	Description
`id`	integer or string	yes	ID orURL-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`). If the token requires an expiration date, defaults to 1 week. If not required, defaults to themaximum allowable lifetime limit.

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, returns200: 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. SeeSelf-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 theapi orself_rotate scope.
Use theself 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 orURL-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, returns204 No content.

Other possible responses: