openapi: 3.0.1
info:
  title: Branding Service API Specification
  description: |2
           The **Branding Service** allows to associate a company logo with a space. The service provides a standardized
           way for other components in the platform to retrieve logo(s) relevant to a given space. This can be for
           displaying in the user interface or, for example, for inclusion in documents generated by the platform.

           At the moment only one logo can be associated with a space; we call this the **primary** logo. Although
           each space can have at most one primary logo, a space can be associated with **partner spaces**, each
           potentially having their own logo. The Branding Service allows to retrieve the logo(s) of a given space and all
           its partner spaces in a single call.

           ----

           ### Uploading a logo

           In order to upload a logo, you must first generate an **upload link** using the [Create a logo upload link](./upload-branding)
           endpoint. This endpoint requires you to specify the file size of the logo and its image type.

           **Note**: Only `image/jpeg` and `"image/png` are supported as logo image type.

           When the call to the endpoint completes successfully, it returns a pre-signed URL that allows you to perform the
           actual image upload. This upload consists of a `PUT` request with the image bytes as body and the following
           mandatory request headers:
           * **`Content-Type`**: This must be set to `application/octet-stream` regardless of the image's actual type.
           * **`Content-Length`**: This is the size of the image in bytes and must be equal to the value that was
                                   previously specified in the upload link creation request.
           * **`x-goog-if-generation-match`**: The value for this header must be set to `0`.
           * **`x-upload-content-length`**: This is the size of the image in bytes and must be equal to the value that was
                                            previously specified in the upload link creation request.

           **Note**: A generated upload link is valid for a limited time and can only be used once to upload an image. It
           can not be reused to overwrite an earlier uploaded image.

           ### Deleting a logo

           This is a straightforward `DELETE` request via the [Delete a logo](./delete-branding) endpoint.

           ### Retrieving logo(s)

           Perform a `GET` request to the [Retrieve branding](./retrieve-branding) endpoint. The response contains the URLs of the space's
           logo(s) (currently only one: 'primary') and potentially a list of partners containing, for each partner, the
           partner's space ID and the partner's logo URL(s).

           ### Permissions

           In order to be able to upload or delete logos, the client needs the `space_foundation_manage_branding` scope on the space for which a logo is
           uploaded or deleted.

           For reading a space's branding information, the client needs the `space_read` scope on that space. When the space has
           associated partner spaces, the logos associated with those partner spaces (if any) will also be returned. For this
           the client does not need any permissions on those partner spaces.

           The URLs of the actual images are public; they can be retrieved with an unauthenticated call, facilitating the
           use of these URLs in, for example, e-mails.
  version: 2.1.13
servers:
- description: ''
  url: https://api.cve.btx.eu.banqup.com/platform/branding
paths: {}
components:
  schemas:
    UploadLogoRequest:
      type: object
      properties:
        fileSize:
          type: number
          description: The size in bytes of the image to be uploaded
          example: 15362
        contentType:
          type: string
          description: The media type of the image to be uploaded
          example: image/png
      description: An upload logo request body.
      example:
        fileSize: 500
        contentType: image/png
    ApiErrorProblemDetail:
      required:
      - error
      - requestId
      - timestamp
      type: object
      properties:
        status:
          type: integer
          format: int32
        error:
          type: string
        requestId:
          type: string
        timestamp:
          type: string
          format: date-time
        type:
          type: string
          format: uri
        title:
          type: string
        detail:
          type: string
        instance:
          type: string
          format: uri
        problems:
          type: array
          items:
            $ref: '#/components/schemas/NestedProblem'
        properties:
          type: object
          additionalProperties:
            type: object
    NestedProblem:
      required:
      - detail
      - error
      - title
      type: object
      properties:
        error:
          type: string
        title:
          type: string
        detail:
          type: string
        type:
          type: string
          format: uri
    UploadLogoResponse:
      type: object
      properties:
        uploadUrl:
          type: string
          description: A signed URL to be used in a PUT operation to upload the image
            bytes
    Branding:
      type: object
      properties:
        logos:
          $ref: '#/components/schemas/Logos'
        partners:
          type: array
          description: A list of partner information objects; one for each partner
            space associated with the specified space
          items:
            $ref: '#/components/schemas/Partner'
      description: Response body containing branding information
      example:
        logos:
          primary: 
            https://api.dev.btx.eu.banqup.com/core/asset/v1/assets/static/space/c8e99b0a-a60a-4719-94ce-9ddb3ddd25fa/branding/logos/primary
    Logos:
      type: object
      properties:
        primary:
          type: string
          description: The 'primary' logo for the space
      description: A set of logos associated with a space
      example:
        primary: 
          https://api.dev.btx.eu.banqup.com/core/asset/v1/assets/static/space/c8e99b0a-a60a-4719-94ce-9ddb3ddd25fa/branding/logos/primary
    Partner:
      type: object
      properties:
        logos:
          $ref: '#/components/schemas/Logos'
        spaceId:
          type: string
          description: The ID of a partner space
          format: uuid
      description: An object containing the ID of a partner's space and a set of their
        logos
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.cve.btx.eu.banqup.com/oauth2/client_credential/gettoken
          scopes:
            info: Scopes are endpoint-specific, see each endpoint for required scope.
        authorizationCode:
          authorizationUrl: https://api.cve.btx.eu.banqup.com/oauth2/auth
          tokenUrl: https://api.cve.btx.eu.banqup.com/oauth2/token
          scopes:
            info: Scopes are endpoint-specific, see each endpoint for required scope.
