API des jetons d'accès de groupe

{{< details >}}

• Édition : Gratuite, GitLab Premium, GitLab Ultimate
• Offre : GitLab.com, GitLab Self-Managed, GitLab Dedicated

{{< /details >}}

Utilisez cette API pour interagir avec les jetons d'accès de groupe. Pour plus d'informations, voir Jetons d'accès de groupe.

Lister tous les jetons d'accès de groupe {#list-all-group-access-tokens}

{{< history >}}

• L'attribut state a été introduit dans GitLab 17.2.

{{< /history >}}

Liste tous les jetons d'accès de groupe pour le groupe spécifié.

GET /groups/:id/access_tokens
GET /groups/:id/access_tokens?state=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",
      "description": "Test Token description",
      "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",
      "description": "Test Token description",
      "revoked" : true,
      "last_used_at": "2021-02-13T10:34:57.178Z",
      "access_level": 40
   }
]

Récupérer les détails d'un jeton d'accès de groupe {#retrieve-details-on-a-group-access-token}

Récupère les détails d'un jeton d'accès de groupe spécifié.

GET /groups/:id/access_tokens/:token_id

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",
   "description": "Test Token description",
   "revoked" : false,
   "access_level": 40
}

Créer un jeton d'accès de groupe {#create-a-group-access-token}

{{< history >}}

• La valeur par défaut de l'attribut expires_at a été introduite dans GitLab 16.0.

{{< /history >}}

Crée un jeton d'accès de groupe pour un groupe spécifié.

Prérequis :

• Vous devez avoir le rôle Owner pour le groupe.

POST /groups/:id/access_tokens

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",
   "description": "Test Token description",
   "user_id" : 166,
   "id" : 58,
   "expires_at" : "2021-01-31",
   "token" : "D4y...Wzr",
   "access_level": 30
}

Faire pivoter un jeton d'accès de groupe {#rotate-a-group-access-token}

{{< history >}}

• Introduit dans GitLab 16.0
• L'attribut expires_at a été ajouté dans GitLab 16.6.

{{< /history >}}

Fait pivoter un jeton d'accès de groupe spécifié. Cela révoque immédiatement le jeton précédent et crée un nouveau jeton. En général, ce point de terminaison fait pivoter un jeton d'accès de groupe spécifique en s'authentifiant avec un jeton d'accès personnel. Vous pouvez également utiliser un jeton d'accès de groupe pour le faire pivoter lui-même. Pour plus d'informations, voir Self-rotate.

Si vous tentez d'utiliser ce point de terminaison pour faire pivoter un jeton précédemment révoqué, tous les jetons actifs de la même famille de jetons sont révoqués. Pour plus d'informations, voir la détection automatique de réutilisation.

Prérequis :

• Pour faire pivoter un autre jeton d'accès de groupe, vous devez disposer d'un jeton d'accès personnel avec la api.
• Pour faire pivoter soi-même un jeton d'accès de groupe, le jeton doit avoir la portée api ou self_rotate.

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

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

Exemple de réponse :

{
    "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"
}

En cas de succès, retourne 200: OK.

Autres réponses possibles :

• 400: Bad Request si la rotation n'a pas réussi.
• 401: Unauthorized si l'une des conditions suivantes est vraie :
  • Le jeton n'existe pas.
  • Le jeton a expiré.
  • Le jeton a été révoqué.
  • Vous n'avez pas accès au jeton spécifié.
  • Vous utilisez un jeton d'accès de groupe pour faire pivoter un autre jeton d'accès de groupe. Voir Auto-rotation à la place.
• 403: Forbidden si le jeton n'est pas autorisé à pivoter lui-même.
• 404: Not Found si l'utilisateur est un administrateur mais que le jeton n'existe pas.
• 405: Method Not Allowed si le jeton n'est pas un jeton d'accès.

Auto-rotation {#self-rotate}

Au lieu de faire pivoter un jeton d'accès de groupe spécifique, vous pouvez faire pivoter le même jeton d'accès de groupe que celui utilisé pour authentifier la requête. Pour faire pivoter soi-même un jeton d'accès de groupe, vous devez :

• Faire pivoter un jeton d'accès de groupe avec la portée api ou self_rotate.
• Utiliser le mot-clé self dans l'URL de la requête.

Exemple de requête :

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

Révoquer un jeton d'accès de groupe {#revoke-a-group-access-token}

Révoque un jeton d'accès de groupe spécifié.

DELETE /groups/:id/access_tokens/:token_id

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

En cas de succès, retourne 204 No content.

Autres réponses possibles :

• 400: Bad Request si la révocation n'a pas réussi.
• 404: Not Found si le jeton d'accès n'existe pas.