Skip to main content
Version: 2.1.19

Branding Service API Specification

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.

In order to upload a logo, you must first generate an upload link using the Create a logo upload link 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.

This is a straightforward DELETE request via the Delete a logo endpoint.

Retrieving logo(s)​

Perform a GET request to the 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.

Authentication​

Security Scheme Type:

oauth2

OAuth Flow (clientCredentials):

Scopes:

  • info: Scopes are endpoint-specific, see each endpoint for required scope.

OAuth Flow (authorizationCode):

Scopes:

  • info: Scopes are endpoint-specific, see each endpoint for required scope.