Skip to content

Group access tokens API

DETAILS: 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 group access tokens

Get a list of group access tokens.

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

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 the group
state string No Limit results to tokens with specified state. Valid values are active and inactive. By default both states are returned. 
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/<group_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",
      "revoked" : false,
      "last_used_at": null,
      "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 a group access token

Get a group access token by ID.

GET /groups/:id/access_tokens/:token_id
Attribute Type required Description
id integer or string yes ID or URL-encoded path of the group
token_id integer yes ID of the group access token 
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/<group_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
}

Create a group access token

  • The expires_at attribute default was introduced in GitLab 16.0.

Create a group access token. You must have the Owner role for the group to create group access tokens.

POST /groups/:id/access_tokens
Attribute Type required Description
id integer or string yes ID or URL-encoded path of the group
name String yes Name of the group access token
scopes Array[String] yes List of scopes
access_level Integer no Access level. Valid values are 10 (Guest), 15 (Planner), 20 (Reporter), 30 (Developer), 40 (Maintainer), and 50 (Owner).
expires_at Date yes Expiration date of the access 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 }' \
"https://gitlab.example.com/api/v4/groups/<group_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 group access token

Prerequisites:

Rotate a group access token. Revokes the previous token and creates a new token that expires in one week.

In GitLab 16.6 and later, you can use the expires_at parameter to set a different expiry date. This non-default expiry date can be up to a maximum of one year from the rotation date.

POST /groups/:id/access_tokens/:token_id/rotate
Attribute Type required Description
id integer or string yes ID or URL-encoded path of the group
token_id integer yes ID of the access token
expires_at date no Expiration date of the access token in ISO format (YYYY-MM-DD). Introduced in GitLab 16.6. If undefined, the token expires after one week. 
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/<group_id>/access_tokens"
```0

Example response:

```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/<group_id>/access_tokens"
```1

### Responses

- `200: OK` if existing token is successfully revoked and the new token is created.
- `400: Bad Request` if not rotated successfully.
- `401: Unauthorized` if either the:
  - User does not have access to the token with the specified ID.
  - Token with the specified ID does not exist.
- `404: Not Found` if the user is an administrator but the token with the specified ID does not exist.

### Automatic reuse detection

Refer to [automatic reuse detection for personal access tokens](personal_access_tokens.md#automatic-reuse-detection)
for more information.

## Revoke a group access token

Revoke a [group access token](../user/group/settings/group_access_tokens.md).

```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/<group_id>/access_tokens"
```2

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

```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/<group_id>/access_tokens"
```3

### Responses

- `204: No Content` if successfully revoked.
- `400 Bad Request` or `404 Not Found` if not revoked successfully.