openapi: 3.0.3

info:
  title: Collibra OAuth 2.0 Client Management API
  description: |
    Allows registration and management of OAuth 2.0 clients
    running at your premises and needing to authenticate against Collibra services.
  version: 1.2.0
  x-audience: public

tags:
  - name: Client Registration
    description: Register clients.
    externalDocs:
      description: OAuth 2.0 Dynamic Client Registration Protocol
      url: https://datatracker.ietf.org/doc/html/rfc7591
  - name: Client Management
    description: Manage registered clients.
    externalDocs:
      description: OAuth 2.0 Dynamic Client Registration Management Protocol
      url: https://datatracker.ietf.org/doc/html/rfc7592

servers:
  - url: /rest/auth/v1
  - url: /rest/auth/v1/platform

paths:
  /clients:
    get:
      operationId: findClients
      summary: Read all client registrations.
      description: |
        Read all clients registrations available in your Collibra instance.
        
        This endpoint is proprietary, rather than part of the OAuth 2.0 family of standards.
      tags:
        - Client Registration
      responses:
        '200':
          description: Client registrations retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientRegistrations'
    post:
      operationId: registerClient
      summary: Register client
      description: |
        Register a client installed at your premises.
        
        Collibra assigns the registered client a unique client identifier,
        assigns a client secret, and associates the metadata
        provided in the request to the registered client.
      tags: [ Client Registration ]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterClient'
      responses:
        '201':
          description: Client registered successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientRegistration'
        '400':
          $ref: '#/components/responses/400'

  /clients/{client_id}:
    get:
      operationId: getClient
      summary: Read client registration
      description: Read the current client registration data stored by Collibra.
      tags:
        - Client Management
      parameters:
        - $ref: '#/components/parameters/client_id'
      responses:
        '200':
          description: Client data retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientInformation'
        '401':
          $ref: '#/components/responses/401'
        '403':
          description: Not authorized to retrieve the requested client data.

    delete:
      operationId: deleteClient
      summary: Delete client registration
      description: |-
        Deletes a registered client.

        A successful delete action will invalidate the `client_id` and
        `client_secret` for this client, meaning the client will no longer be able
        to authenticate with those credentials.
      tags:
        - Client Management
      parameters:
        - $ref: '#/components/parameters/client_id'
      responses:
        '204':
          description: Client registration deleted successfully.
        '401':
          $ref: '#/components/responses/401'
        '403':
          description: The provided client is not allowed to delete this record.

    put:
      operationId: updateClient
      summary: Update client registration
      description: |-
        Updates a registered client.
      tags:
        - Client Management
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateClient'
      parameters:
        - $ref: '#/components/parameters/client_id'
      responses:
        '200':
          description: Client updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientRegistration'
        '401':
          $ref: '#/components/responses/401'
        '403':
          description: The provided client is not allowed to update this record.

components:
  securitySchemes:
    httpBasicAuth:
      type: http
      scheme: basic
      description: Collibra REST API authentication with Basic HTTP Authentication (RFC 7617).
    jwtAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Collibra REST API authentication with JSON Web Token.

  responses:
    '400':
      description: Client registration request is invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClientRegistrationError'
    '401':
      description: This client doesn't exist on this server, or the provided access token is invalid
      headers:
        WWW-Authenticate:
          description: The registration access token used to make this request is not valid or doesn't exist
          schema:
            properties:
              error:
                type: string
              error_description:
                type: string

  schemas:
    RegisterClient:
      type: object
      description: Request to register a new client.
      allOf:
        - $ref: '#/components/schemas/ClientWriteableInformation'
      properties:
        software_id:
          type: string
          description: Identifier of the Collibra software bundle that implements the client.
          example: datalineage-harvester
      required: [ client_name ]

    ClientRegistration:
      allOf:
        - $ref: '#/components/schemas/ClientInformation'
      type: object
      description: |
        Data associated to the registered client.

        The client secret returned in this response cannot be read through any API call.
        Thus you should store the client secret returned in this response.
      properties:
        client_secret:
          type: string
          format: password
          description: Secret generated by Collibra for the registered client.

    ClientRegistrationError:
      type: object
      description: Error condition resulting from a client registration call.
      properties:
        error:
          type: string
          description: Error code.
        error_description:
          type: string
          description: Human-readable description of the error.

    ClientRegistrations:
      type: object
      description: Client registrations found.
      properties:
        registrations:
          type: array
          items:
            $ref: '#/components/schemas/ClientInformationSummary'

    ClientInformationSummary:
      type: object
      description: Contains abbreviated data about a registered client.
      properties:
        client_id:
          type: string
          description: Technical client identifier of the client.
        client_name:
          type: string
          description: Descriptive name of the client.
        client_id_issued_at:
          type: integer
          format: int64
          description: Time at which the client identifier was issued.
        grant_types:
          type: array
          items:
            type: string
          description: >-
            Authorization grants that the client is allowed to use at the token endpoint.
        redirect_uris:
          type: array
          items:
            type: string
            format: uri
          description: >-
            Redirection URI strings for use in the authorization code flow.
            Required when the client intends to use the authorization_code grant type.

    ClientInformation:
      type: object
      description: Contains all data known for a registered client.
      allOf:
        - $ref: '#/components/schemas/ClientReadOnlyInformation'
        - $ref: '#/components/schemas/ClientWriteableInformation'

    ClientReadOnlyInformation:
      type: object
      properties:
        client_id:
          type: string
          description: Technical client identifier returned by the Authorization Server when the client is registered.
        client_id_issued_at:
          type: integer
          format: int64
          description: |-
            Time at which the client identifier was issued.

            The time is represented as the number of seconds from
            1970-01-01T00:00:00Z as measured in UTC until the date/time of
            issuance.

    ClientWriteableInformation:
      type: object
      properties:
        client_name:
          type: string
          description: |
            Descriptive name of the client.

            Two different clients cannot have the same name.

            This should be a name that reveals the purpose of the client.
          example: Techlin Harvester (us-west-1)
        grant_types:
          type: array
          items:
            type: string
          description: >-
            Authorization grants that the client is allowed to use.
        redirect_uris:
          type: array
          items:
            type: string
            format: uri
          description: >-
            Redirection URI strings for use in the authorization code flow.
            Required when the client intends to use the authorization_code grant type.

    UpdateClient:
      type: object
      description: Request to update registered client data.
      allOf:
        - $ref: '#/components/schemas/ClientWriteableInformation'
      required: [ client_name ]

  parameters:
    client_id:
      name: client_id
      description: Client identifier generated by Collibra when the client was registered.
      in: path
      required: true
      schema:
        type: string
