GitLab Group credentials inventory API

openapi: 3.2.0
info:
  title: GitLab REST Group credentials inventory API
  description: GitLab REST API used to interact with a GitLab installation.
  termsOfService: https://handbook.gitlab.com/handbook/legal/api-terms/
  version: '19.6'
  license:
    name: CC BY-SA 4.0
    url: https://gitlab.com/gitlab-org/gitlab/-/blob/master/LICENSE
    x-gitlab-description: The license applies to the OpenAPI specification document itself. For terms governing use of the GitLab API, see the termsOfService field.
servers:
- url: https://{hostname}
  description: GitLab REST API
  variables:
    hostname:
      default: gitlab.com
      description: Your GitLab instance hostname
security:
- http: []
- oauth2: []
- apiKey: []
tags:
- name: Group credentials inventory
  description: 'Use this API to manage the credentials that members of a top-level group hold, including their

    personal access tokens, resource access tokens, and SSH keys. You can list these credentials, revoke

    them, and rotate the tokens. For more information, see

    credentials inventory.'
  x-displayName: Group credentials inventory
  externalDocs:
    url: https://docs.gitlab.com/api/groups/
paths:
  /api/v4/groups/{id}/manage/personal_access_tokens:
    get:
      operationId: getApiV4GroupsIdManagePersonalAccessTokens
      summary: List all personal access tokens for a group
      description: Lists all personal access tokens associated with enterprise users in a top-level group. This feature was introduced in GitLab 17.8.
      tags:
      - Group credentials inventory
      responses:
        '200':
          description: OK
        '404':
          description: Not Found
        '400':
          description: Bad Request
      parameters:
      - name: id
        required: true
        description: ID or URL-encoded path of the group.
        schema:
          type: string
        in: path
      - name: revoked
        required: false
        description: If `true`, only returns revoked tokens. If `false`, only returns tokens that are not revoked.
        schema:
          type:
          - boolean
          - 'null'
        in: query
        example: false
      - name: state
        required: false
        description: Return tokens with the specified state.
        schema:
          type:
          - string
          - 'null'
          enum:
          - all
          - active
          - inactive
          - null
        in: query
        example: active
      - name: created_before
        required: false
        description: Return tokens created on or before the specified time.
        schema:
          type:
          - string
          - 'null'
          format: date-time
        in: query
        example: '2022-01-01T00:00:00Z'
      - name: created_after
        required: false
        description: Return tokens created on or after the specified time.
        schema:
          type:
          - string
          - 'null'
          format: date-time
        in: query
        example: '2021-01-01T00:00:00Z'
      - name: last_used_before
        required: false
        description: Return tokens last used on or before the specified time.
        schema:
          type:
          - string
          - 'null'
          format: date-time
        in: query
        example: '2021-01-01T00:00:00Z'
      - name: last_used_after
        required: false
        description: Return tokens last used on or after the specified time.
        schema:
          type:
          - string
          - 'null'
          format: date-time
        in: query
        example: '2022-01-01T00:00:00Z'
      - name: expires_before
        required: false
        description: Return tokens that expire before the specified date.
        schema:
          type:
          - string
          - 'null'
          format: date
        in: query
        example: '2022-01-01'
      - name: expires_after
        required: false
        description: Return tokens that expire on or after the specified date.
        schema:
          type:
          - string
          - 'null'
          format: date
        in: query
        example: '2021-01-01'
      - name: search
        required: false
        description: Return tokens that include the specified value in their name.
        schema:
          type:
          - string
          - 'null'
        in: query
        example: token
      - name: sort
        required: false
        description: Sort results by the specified field and direction. Possible values are `created_asc`, `created_desc`, `expires_asc`, `expires_desc`, `last_used_asc`, `last_used_desc`, `name_asc`, and `name_desc`.
        schema:
          type:
          - string
          - 'null'
        in: query
        example: created_desc
      - name: page
        required: false
        description: Page number of results to retrieve.
        schema:
          type: integer
          default: 1
        in: query
        example: 1
      - name: per_page
        required: false
        description: Number of items to list per page.
        schema:
          type: integer
          default: 20
        in: query
        example: 20
      x-gitlab-tier: ultimate
  /api/v4/groups/{id}/manage/personal_access_tokens/{pat_id}:
    delete:
      operationId: deleteApiV4GroupsIdManagePersonalAccessTokensPatId
      summary: Revoke a personal access token for an enterprise user
      description: Revokes a specified personal access token for an enterprise user.
      tags:
      - Group credentials inventory
      responses:
        '204':
          description: No Content
        '400':
          description: Bad Request
        '404':
          description: Not Found
      parameters:
      - name: id
        required: true
        description: ID or URL-encoded path of the group.
        schema:
          type: string
        in: path
      - name: pat_id
        required: true
        description: ID of the personal access token.
        schema:
          type: integer
        in: path
      x-gitlab-tier: ultimate
  /api/v4/groups/{id}/manage/personal_access_tokens/{pat_id}/rotate:
    post:
      operationId: postApiV4GroupsIdManagePersonalAccessTokensPatIdRotate
      summary: Rotate a personal access token for an enterprise user
      description: Rotates a specified personal access token for an enterprise user associated with the top-level group. This revokes the previous token and creates a token that expires after one week.
      tags:
      - Group credentials inventory
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIEntitiesPersonalAccessTokenWithToken'
        '404':
          description: Not Found
        '400':
          description: Bad Request
      parameters:
      - name: id
        required: true
        description: ID or URL-encoded path of the group.
        schema:
          type: string
        in: path
      - name: pat_id
        required: true
        description: ID of the personal access token.
        schema:
          type: integer
        in: path
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/postApiV4GroupsIdManagePersonalAccessTokensPatIdRotateRequest'
      x-gitlab-tier: ultimate
  /api/v4/groups/{id}/manage/resource_access_tokens:
    get:
      operationId: getApiV4GroupsIdManageResourceAccessTokens
      summary: List all group and project access tokens for a group
      description: Lists all group and project access tokens associated with a top-level-group. This feature was introduced in GitLab 17.10.
      tags:
      - Group credentials inventory
      responses:
        '200':
          description: OK
        '404':
          description: Not Found
        '400':
          description: Bad Request
      parameters:
      - name: id
        required: true
        description: ID or URL-encoded path of the group.
        schema:
          oneOf:
          - type: string
          - type: integer
        in: path
      - name: revoked
        required: false
        description: If `true`, only returns revoked tokens. If `false`, only returns tokens that are not revoked.
        schema:
          type:
          - boolean
          - 'null'
        in: query
        example: false
      - name: state
        required: false
        description: Return tokens with the specified state.
        schema:
          type:
          - string
          - 'null'
          enum:
          - all
          - active
          - inactive
          - null
        in: query
        example: active
      - name: created_before
        required: false
        description: Return tokens created on or before the specified time.
        schema:
          type:
          - string
          - 'null'
          format: date-time
        in: query
        example: '2022-01-01T00:00:00Z'
      - name: created_after
        required: false
        description: Return tokens created on or after the specified time.
        schema:
          type:
          - string
          - 'null'
          format: date-time
        in: query
        example: '2021-01-01T00:00:00Z'
      - name: last_used_before
        required: false
        description: Return tokens last used on or before the specified time.
        schema:
          type:
          - string
          - 'null'
          format: date-time
        in: query
        example: '2021-01-01T00:00:00Z'
      - name: last_used_after
        required: false
        description: Return tokens last used on or after the specified time.
        schema:
          type:
          - string
          - 'null'
          format: date-time
        in: query
        example: '2022-01-01T00:00:00Z'
      - name: expires_before
        required: false
        description: Return tokens that expire before the specified date.
        schema:
          type:
          - string
          - 'null'
          format: date
        in: query
        example: '2022-01-01'
      - name: expires_after
        required: false
        description: Return tokens that expire on or after the specified date.
        schema:
          type:
          - string
          - 'null'
          format: date
        in: query
        example: '2021-01-01'
      - name: search
        required: false
        description: Return tokens that include the specified value in their name.
        schema:
          type:
          - string
          - 'null'
        in: query
        example: token
      - name: sort
        required: false
        description: Sort results by the specified field and direction. Possible values are `created_asc`, `created_desc`, `expires_asc`, `expires_desc`, `last_used_asc`, `last_used_desc`, `name_asc`, and `name_desc`.
        schema:
          type:
          - string
          - 'null'
        in: query
        example: created_desc
      - name: page
        required: false
        description: Page number of results to retrieve.
        schema:
          type: integer
          default: 1
        in: query
        example: 1
      - name: per_page
        required: false
        description: Number of items to list per page.
        schema:
          type: integer
          default: 20
        in: query
        example: 20
      x-gitlab-tier: ultimate
  /api/v4/groups/{id}/manage/resource_access_tokens/{prat_id}:
    delete:
      operationId: deleteApiV4GroupsIdManageResourceAccessTokensPratId
      summary: Revoke a group or project access token for a group
      description: Revokes a specified group or project access token associated with a top-level group.
      tags:
      - Group credentials inventory
      responses:
        '204':
          description: No Content
        '400':
          description: Bad Request
        '404':
          description: Not Found
      parameters:
      - name: id
        required: true
        description: ID or URL-encoded path of the group.
        schema:
          oneOf:
          - type: string
          - type: integer
        in: path
      - name: prat_id
        required: true
        description: ID of the resource access token.
        schema:
          type: integer
        in: path
      - name: expires_at
        required: false
        description: Date when the access token expires. If omitted, the new token expires one week after rotation when [token expiry is enforced](https://docs.gitlab.com/user/profile/personal_access_tokens/#access-token-expiration), and does not expire otherwise. When expiry is enforced, the date must be no more than one year after rotation.
        schema:
          type:
          - string
          - 'null'
          format: date
        in: query
        example: '2021-01-31'
      x-gitlab-tier: ultimate
  /api/v4/groups/{id}/manage/resource_access_tokens/{prat_id}/rotate:
    post:
      operationId: postApiV4GroupsIdManageResourceAccessTokensPratIdRotate
      summary: Rotate a group or project access token for a group
      description: Rotates a specified group or project access token associated with a top-level group. This revokes the previous token and creates a new token.
      tags:
      - Group credentials inventory
      responses:
        '204':
          description: No Content
        '400':
          description: Bad Request
        '404':
          description: Not Found
      parameters:
      - name: id
        required: true
        description: ID or URL-encoded path of the group.
        schema:
          oneOf:
          - type: string
          - type: integer
        in: path
      - name: prat_id
        required: true
        description: ID of the resource access token.
        schema:
          type: integer
        in: path
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/postApiV4GroupsIdManageResourceAccessTokensPratIdRotateRequest'
      x-gitlab-tier: ultimate
  /api/v4/groups/{id}/manage/ssh_keys:
    get:
      operationId: getApiV4GroupsIdManageSshKeys
      summary: List all SSH keys for a group
      description: Lists all SSH public keys associated with enterprise users in a top-level-group. This feature was introduced in GitLab 17.9.
      tags:
      - Group credentials inventory
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIEntitiesSshKeyWithUserId'
        '404':
          description: Not Found
        '400':
          description: Bad Request
      parameters:
      - name: id
        required: true
        description: ID or URL-encoded path of the group.
        schema:
          oneOf:
          - type: string
          - type: integer
        in: path
      - name: created_before
        required: false
        description: Return SSH keys created on or before the specified time.
        schema:
          type:
          - string
          - 'null'
          format: date-time
        in: query
        example: '2022-01-01T00:00:00Z'
      - name: created_after
        required: false
        description: Return SSH keys created on or after the specified time.
        schema:
          type:
          - string
          - 'null'
          format: date-time
        in: query
        example: '2021-01-01T00:00:00Z'
      - name: expires_before
        required: false
        description: Return SSH keys that expire on or before the specified time.
        schema:
          type:
          - string
          - 'null'
          format: date-time
        in: query
        example: '2022-01-01T00:00:00Z'
      - name: expires_after
        required: false
        description: Return SSH keys that expire on or after the specified time.
        schema:
          type:
          - string
          - 'null'
          format: date-time
        in: query
        example: '2021-01-01T00:00:00Z'
      - name: page
        required: false
        description: Page number of results to retrieve.
        schema:
          type: integer
          default: 1
        in: query
        example: 1
      - name: per_page
        required: false
        description: Number of items to list per page.
        schema:
          type: integer
          default: 20
        in: query
        example: 20
      x-gitlab-tier: ultimate
  /api/v4/groups/{id}/manage/ssh_keys/{key_id}:
    delete:
      operationId: deleteApiV4GroupsIdManageSshKeysKeyId
      summary: Delete an SSH key for an enterprise user
      description: Deletes a specified SSH public key for an enterprise user associated with the top-level group.
      tags:
      - Group credentials inventory
      responses:
        '204':
          description: No Content
        '400':
          description: Bad Request
        '404':
          description: Not Found
      parameters:
      - name: id
        required: true
        description: ID or URL-encoded path of the group.
        schema:
          oneOf:
          - type: string
          - type: integer
        in: path
      - name: key_id
        required: true
        description: ID of the SSH key.
        schema:
          type: integer
        in: path
      x-gitlab-tier: ultimate
components:
  schemas:
    APIEntitiesSshKeyWithUserId:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 1
        title:
          type: string
          example: Sample key 25
        created_at:
          type: string
          format: date-time
          example: '2015-09-03T07:24:44.627Z'
        expires_at:
          type: string
          format: date-time
          example: '2020-09-03T07:24:44.627Z'
        last_used_at:
          type: string
          format: date-time
          example: '2020-09-03T07:24:44.627Z'
        usage_type:
          type: string
          example: auth
        user_id:
          type: integer
          format: int64
          example: 3
    APIEntitiesPersonalAccessTokenWithToken:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 2
        name:
          type: string
          example: John Doe
        revoked:
          type: boolean
        created_at:
          type: string
          format: date-time
        description:
          type: string
          example: Token to manage api
        scopes:
          type: array
          example:
          - api
        user_id:
          type: integer
          format: int64
          example: 3
        last_used_at:
          type: string
          format: date-time
          example: '2020-08-31T15:53:00.073Z'
        last_used_ips:
          type: array
          description: The five most recent 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.
          example:
          - 127.0.0.1
          - 127.0.0.2
          - 127.0.0.3
          items:
            type: string
        granular_scopes:
          type: array
          items:
            $ref: '#/components/schemas/APIEntitiesGranularScope'
        active:
          type: boolean
        granular:
          type: boolean
        expires_at:
          type: string
          format: date-time
          example: '2020-08-31T15:53:00.073Z'
        token:
          type: string
    postApiV4GroupsIdManageResourceAccessTokensPratIdRotateRequest:
      type: object
      properties:
        expires_at:
          type:
          - string
          - 'null'
          format: date
          description: Date when the access token expires. If omitted, the new token expires one week after rotation when [token expiry is enforced](https://docs.gitlab.com/user/profile/personal_access_tokens/#access-token-expiration), and does not expire otherwise. When expiry is enforced, the date must be no more than one year after rotation.
          example: '2021-01-31'
    postApiV4GroupsIdManagePersonalAccessTokensPatIdRotateRequest:
      type: object
      properties:
        expires_at:
          type:
          - string
          - 'null'
          format: date
          description: Date when the access token expires. If omitted, the new token expires one week after rotation when [token expiry is enforced](https://docs.gitlab.com/user/profile/personal_access_tokens/#access-token-expiration), and does not expire otherwise. When expiry is enforced, the date must be no more than one year after rotation.
          example: '2021-01-31'
    APIEntitiesGranularScope:
      type: object
      properties:
        access:
          type: string
          example: personal_projects
        permissions:
          type: array
          example:
          - read_job
        project_id:
          type: integer
          format: int64
          example: 3
        group_id:
          type: integer
          format: int64
          example: 5
  securitySchemes:
    http:
      type: http
      scheme: bearer
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://gitlab.com/oauth/authorize
          tokenUrl: https://gitlab.com/oauth/token
          refreshUrl: https://gitlab.com/oauth/token
          scopes:
            api: Grants complete read/write access to the API, including all groups and projects, the container registry, the dependency proxy, and the package registry.
            read_api: Grants read access to the API, including all groups and projects, the container registry, and the package registry.
            read_user: Grants read-only access to your profile through the /user API endpoint, which includes username, public email, and full name. Also grants access to read-only API endpoints under /users.
            create_runner: Grants create access to the runners.
            manage_runner: Grants access to manage the runners.
            k8s_proxy: Grants permission to perform Kubernetes API calls using the agent for Kubernetes.
            self_rotate: Grants permission for token to rotate itself.
            mcp: Grants read-write access to remote Model Context Protocol (MCP) server for tools execution.
            mcp_orbit: Grants access to the Orbit Knowledge Graph MCP server for graph queries and schema retrieval.
    apiKey:
      type: apiKey
      name: PRIVATE-TOKEN
      in: header