openapi: 3.0.3

info:
  title: Collibra OAuth 2.0 Authorization API
  description: |
    Allows authorization of OAuth 2.0 clients running at your premises and needing to call Collibra APIs.

    The API supports the client credentials grant flow, where the client is a machine-to-machine application that
    can authenticate and authorize itself using its client ID and client secret.
  version: 1.0.0
  x-audience: public

externalDocs:
  description: OAuth 2.0 Authorization Framework
  url: https://datatracker.ietf.org/doc/html/rfc6749

servers:
  - url: /rest/oauth/v2

tags:
  - name: OAuth 2 Authorization
    description: Authorize your Collibra API calls.

paths:
  /token:
    post:
      summary: Request an access token.
      description: Obtain an access token that can be used to authorize Collibra API calls.
      operationId: requestToken
      tags: [ OAuth 2 Authorization ]
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/AccessTokenRequest'
            examples:
              Client credentials:
                summary: Client credentials grant flow.
                value:
                  grant_type: client_credentials
                  client_id: urn:sys:env:f40896da-f739-4c07-8058-d3dcd2f3332d:i:1qg8zne
                  client_secret: ntRC8O68kfL_5d13Ye8vnk7XbRN43GJWtd8K0cZ0n10n-lyNzQ0NREDvTmMoDz3K
      responses:
        '200':
          description: Token successfully generated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessTokenResponse'
              example:
                access_token: eyJraWQiOiJsb2NhbCIsImFsZyI6IlJTMjU2In0.eyJqdGkiOiIwNDQ3ZWUyMS1jNDlkLTQ0YTQtYTMyYi1hZDBjZjViMjQ0ZTYiLCJzdWIiOiJ1cm46c3lzOmVudjpmNDA4OTZkYS1mNzM5LTRjMDctODA1OC1kM2RjZDJmMzMzMmQ6aToxcWc4em5lIiwiYXVkIjoiY29sbGlicmEiLCJzY29wZSI6WyJkZ2MuYWRtaW4iLCJkZ2MuZ2xvYmFsLW1hbmFnZS1hbGwtcmVzb3VyY2VzIl0sImlzcyI6Imh0dHA6Ly9hdXRoLmlhbSIsImlhdCI6MTczNjQ5NjI4MCwibmJmIjoxNzM2NDk2MjgwLCJleHAiOjE3MzY0OTY1ODAsImVudiI6ImY0MDg5NmRhLWY3MzktNGMwNy04MDU4LWQzZGNkMmYzMzMyZCJ9.F4ervk_PeN01Dju0Dx4S2evLvbXMtQ9aQ9zzGzhQqTCvBMnXmJZky822XegNODU6g0FsmhDZJH14Agx-IsJseGoRe2IHZJGznAZZ0ng3FYbgF3dslkXp2OUkcF5Gk7t-FYNBrypjY9LrOU9YRGO-RjvwqVb7n--t5H-8TwSFLsB0aLWvM2kL4J98kvfPkxCcf5S-O5bcOSN6Z78dQlmeE9SBPNz9zeWg-NgIq8erDiLWFgIW80HE1JkbTsUhylno6mSxcLlRWMz73hL_90d-cz8UMQNCFRdt0FGilJRwvrqszGsT7ZXEox9WJRreWBE1P0gaAVdMVkrs61TgUV5ebqxayIw64GHb35ZadQqVV7oxIxowq8n6FrrVNdSgpYItQO2IWuA9-F5-ocsM-toyZtJFJWyvjAkMXGMSK5nwDCd_oieX1_FVNmc30clfM3KxAUkxkb3OQGHTHvPl8Y_wRgYNM2rittim2EbAsjlJuiEsKfwhSKavKnMemhGExgI6
                token_type: Bearer
                expires_in: 300
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      security:
        - basicAuth: [ ]
components:
  responses:
    BadRequest:
      description: The token request was invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OAuth2Error'
    Unauthorized:
      description: The client credentials are invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OAuth2Error'
  securitySchemes:
    basicAuth:
      description: |
        Collibra REST API authentication with Basic HTTP Authentication (RFC 7617).

        The client identifier is used as the username and the client secret is used as the password.
      type: http
      scheme: basic

  schemas:
    AccessTokenRequest:
      type: object
      description: See [Section 4.4.2 of RFC 6749](https://datatracker.ietf.org/doc/html/rfc6749#section-4.4.2).
      properties:
        grant_type:
          type: string
          description: Type of authorization. The only supported grant type is `client_credentials`.
      required:
        - grant_type

    AccessTokenResponse:
      type: object
      description: See [Section 5.1 of RFC 6749](https://datatracker.ietf.org/doc/html/rfc6749#section-5.1).
      properties:
        access_token:
          type: string
          description: The Base64 encoded access token.
        token_type:
          type: string
          description: The type of access token returned. The only supported type is "Bearer".
        scope:
          type: string
          description: |
            The scopes that have been granted for the client.
            
            This field is omitted if the client did not request any specific scopes,
            in which case the default scopes for the client will have been granted.
        expires_in:
          type: integer
          format: int64
          description: The time in seconds until the access token is no longer valid.

    OAuth2Error:
      type: object
      description: See [Section 5.2 of RFC 6749](https://datatracker.ietf.org/doc/html/rfc6749#section-5.2)
      properties:
        error:
          type: string
          description: OAuth 2.0 error code defined in RFC 6749 Section 5.2.
        error_description:
          type: string
          description: Human-readable description of the error.
        error_uri:
          type: string
          format: uri
          description: A URI identifying a human-readable web page with information about the error.
