GitLab Tokens API

openapi: 3.2.0
info:
  title: GitLab OAuth 2.0 Tokens API
  description: The GitLab OAuth 2.0 API enables third-party services to access GitLab resources on behalf of users using the OAuth 2.0 protocol. It supports authorization code with PKCE, device authorization grant, and resource owner password credentials flows. Applications must first be registered in GitLab user settings before using these endpoints.
  version: '4'
  contact:
    name: GitLab Support
    url: https://about.gitlab.com/support/
  termsOfService: https://about.gitlab.com/terms/
servers:
- url: https://gitlab.com
  description: GitLab.com Production Server
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:
    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
    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
    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
  securitySchemes:
    oauthToken:
      type: http
      scheme: bearer
      description: OAuth 2.0 access token obtained via the authorization flow.
externalDocs:
  description: GitLab OAuth 2.0 API Documentation
  url: https://docs.gitlab.com/api/oauth2/