Group access tokens API - Gitlabhq

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

Use this API to interact with group access tokens. For more information, see Group access tokens.

List all group access tokens

state attribute introduced in GitLab 17.2.
last_used_ips attribute introduced in GitLab 19.2.

Lists all group access tokens for the specified group.

plaintext

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

Attribute	Type	Required	Description
`id`	integer or string	yes	ID or URL-encoded path of a group.
`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`.

shell

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

json

[
   {
      "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,
      "last_used_at": null,
      "last_used_ips": [],
      "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",
      "last_used_ips": ["192.0.2.10"],
      "access_level": 40
   }
]

[!note] The last_used_ips attribute lists up to five unique IP addresses that have authenticated with this token. When the limit is reached, the oldest IP address is removed. The list updates once per minute per token.

Retrieve details on a group access token

Retrieves details on a specified group access token.

plaintext

GET /groups/:id/access_tokens/:token_id

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

shell

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

json

{
   "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": null,
   "last_used_ips": []
}

Create a group access token

The expires_at attribute default was introduced in GitLab 16.0.

Creates a group access token for a specified group.

Prerequisites:

You must have the Owner role for the group.

plaintext

POST /groups/:id/access_tokens

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

shell

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/groups/<group_id>/access_tokens"

json

{
   "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 group access token

Introduced in GitLab 16.0
expires_at attribute added in GitLab 16.6.

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

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

Prerequisites:

To rotate another group access token, you must have a personal access token with the api scope.
To self-rotate a group access token, the token must have the api or self_rotate scope.

plaintext

POST /groups/:id/access_tokens/:token_id/rotate

Attribute	Type	required	Description
`id`	integer or string	yes	ID or URL-encoded path of a group.
`token_id`	integer or string	yes	ID of a group 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 the maximum allowable lifetime limit.

shell

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/<group_id>/access_tokens/<token_id>/rotate"

Example response:

json

{
    "id": 42,
    "name": "Rotated Token",
    "revoked": false,
    "created_at": "2023-08-01T15:00:00.000Z",
    "description": "Test group access token",
    "scopes": ["api"],
    "user_id": 1337,
    "last_used_at": null,
    "last_used_ips": [],
    "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 group access token to rotate another group 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 an access token.

Self-rotate

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

Rotate a group access token with the api or self_rotate scope.
Use the self keyword in the request URL.

Example request:

shell

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

Revoke a group access token

Revokes a specified group access token.

plaintext

DELETE /groups/:id/access_tokens/:token_id

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

shell

curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/<group_id>/access_tokens/<token_id>"

If successful, returns 204 No content.

Other possible responses:

400: Bad Request if not revoked successfully.
404: Not Found if the access token does not exist.