Group access tokens API

  • 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

History

Lists all group access tokens for a group.

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.
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/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 details on a group access token

Gets details on a group access token. You can reference a specific group access token, or use the keyword self to return details on the authenticating group access token.

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 of a group access token or the keyword self. 
curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "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

History

Creates a group access token for a specified group.

Prerequisites:

  • You must have the Owner role for the group.
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.
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 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 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/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

History

Rotates a 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 the revoked token later, GitLab immediately revokes the new token. For more information, see Automatic reuse detection.

Prerequisites:

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). 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/groups/<group_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 group 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 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:

Example request:

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.

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. 
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: Token was not revoked.
  • 404 Not Found: Token can not be found.