openapi: 3.0.1
info:
  title: GitLab api/v4/ Admin Tokens API
  version: v4
  description: Needs description.
  termsOfService: https://about.gitlab.com/terms/
  license:
    name: CC BY-SA 4.0
    url: https://gitlab.com/gitlab-org/gitlab/-/blob/master/LICENSE
servers:
- url: https://www.gitlab.com/api/
security:
- ApiKeyAuth: []
tags:
- name: Tokens
  description: Endpoints for exchanging, refreshing, and revoking OAuth tokens.
paths:
  /oauth/token:
    post:
      operationId: exchangeToken
      summary: GitLab Exchange Code for Access Token
      description: Exchanges an authorization code, device code, or refresh token for an OAuth 2.0 access token. Supports authorization_code, refresh_token, device_code, and password grant types. Access tokens are valid for two hours. Includes CORS support for browser-based applications.
      tags:
      - Tokens
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/TokenRequest'
      responses:
        '200':
          description: Token issued successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        '400':
          description: Invalid grant or request parameters.
        '401':
          description: Invalid client credentials.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /oauth/revoke:
    post:
      operationId: revokeToken
      summary: GitLab Revoke an OAuth Token
      description: Revokes an existing OAuth access token or refresh token. After revocation the token can no longer be used to access GitLab resources. Supports CORS for browser-based applications.
      tags:
      - Tokens
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/RevokeTokenRequest'
      responses:
        '200':
          description: Token revoked successfully.
        '401':
          description: Invalid or expired token.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /oauth/token/info:
    get:
      operationId: getTokenInfo
      summary: GitLab Get Token Information
      description: Returns information about the current OAuth access token, including the scopes it was granted and its expiration time. Useful for validating that a token is still active.
      tags:
      - Tokens
      security:
      - oauthToken: []
      responses:
        '200':
          description: Token information returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenInfo'
        '401':
          description: Invalid or expired token.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    TokenResponse:
      type: object
      properties:
        access_token:
          type: string
          description: The OAuth 2.0 access token.
          example: glpat-example-token
        token_type:
          type: string
          description: The type of token. Always Bearer.
          example: glpat-example-token
        expires_in:
          type: integer
          description: Token lifetime in seconds. Typically 7200 (2 hours).
          example: 42
        refresh_token:
          type: string
          description: The refresh token for obtaining new access tokens.
          example: main
        scope:
          type: string
          description: Space-separated list of granted scopes.
          example: example_value
        created_at:
          type: integer
          description: Unix timestamp of when the token was created.
          example: 42
    TokenInfo:
      type: object
      properties:
        resource_owner_id:
          type: integer
          description: The ID of the user who authorized the token.
          example: 42
        application:
          type: object
          description: Information about the OAuth application.
          properties:
            uid:
              type: string
              description: The application client ID.
        scope:
          type: array
          description: List of scopes the token has been granted.
          items:
            type: string
        expires_in_seconds:
          type: integer
          description: Remaining lifetime of the token in seconds.
          example: 42
        created_at:
          type: number
          description: Unix timestamp of when the token was created.
          example: 42.5
    RevokeTokenRequest:
      type: object
      required:
      - client_id
      - client_secret
      - token
      properties:
        client_id:
          type: string
          description: The application ID registered in GitLab.
          example: '123456'
        client_secret:
          type: string
          description: The application secret.
          example: example_value
        token:
          type: string
          description: The access token or refresh token to revoke.
          example: glpat-example-token
    TokenRequest:
      type: object
      required:
      - grant_type
      - client_id
      properties:
        grant_type:
          type: string
          enum:
          - authorization_code
          - refresh_token
          - device_code
          - password
          description: The grant type for the token request.
          example: authorization_code
        client_id:
          type: string
          description: The application ID registered in GitLab.
          example: '123456'
        client_secret:
          type: string
          description: The application secret. Required for confidential clients using authorization_code or refresh_token grant types.
          example: example_value
        code:
          type: string
          description: The authorization code received from the authorize endpoint.
          example: example_value
        redirect_uri:
          type: string
          format: uri
          description: The redirect URI used in the original authorization request.
          example: example_value
        code_verifier:
          type: string
          description: The PKCE code verifier corresponding to the code_challenge.
          example: example_value
        refresh_token:
          type: string
          description: The refresh token to exchange for a new access token.
          example: main
        device_code:
          type: string
          description: The device code from the device authorization response.
          example: example_value
        username:
          type: string
          description: Resource owner username. Only for password grant type.
          example: Example Project
        password:
          type: string
          description: Resource owner password. Only for password grant type.
          example: example_value