Logos and backgrounds

A brand's logo shows on its hosted sign-in pages and in the email it sends, and an advanced theme can put a background image behind its sign-in page. The dashboard uploads both from a brand's page; your own code does it the same way, through the management API.

The image never goes through the API. You ask for an upload, PUT the bytes straight to the URL Synq signs for that one file, then ask Synq to finish it. Synq reads the file back, checks it and keeps a new copy of it.

What Synq takesCopy Anchor Link

PNG, JPEG, WebP and GIF only, known by the file's first bytes rather than what the upload says it is. SVG is never taken: export a PNG instead. An animated GIF or WebP keeps its first frame. What Synq keeps is a new image made from the pixels alone, so EXIF and GPS data, colour profiles and anything hidden after the image are gone.

UploadingCopy Anchor Link

$SYNQ_API here is the management API, https://api.synq.build, and $KEY an API key with org.brands.edit.

1. Start an upload with its purpose, content_type and exact content_length. The answer is the file, pending, and its upload: a URL signed for 5 minutes, and the headers to send.

   Copy Text

   curl -X POST "$SYNQ_API/v1/orgs/$ORG/brands/$BRAND/files" \
     -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
     -d '{"purpose": "brand_logo", "content_type": "image/png", "content_length": 48213}'

2. PUT the bytes to upload.url with upload.headers, and nothing of Synq's: no Authorization header. The signature covers the length and the type, so the store refuses anything else.

   Copy Text

   curl -X PUT "$UPLOAD_URL" -H 'Content-Type: image/png' --data-binary @logo.png

3. Finish the upload within the hour. Synq checks and keeps the image, and it becomes what its purpose says at once: a brand_logo is the brand's logo_url, a theme_background its theme's background_image_url. The answer is the file, ready, with its url on Synq's media host. Finishing it again answers the same.

   Copy Text

   curl -X POST "$SYNQ_API/v1/orgs/$ORG/brands/$BRAND/files/$FILE/finalize" \
     -H "Authorization: Bearer $KEY"

From a browser, as the dashboard does, your server starts and finishes the upload with its key, and hands the browser only the signed URL. Synq's storage accepts PUTs from Synq's own dashboard only, so a browser upload from your own site goes through your server instead.

When finishing fails:

• upload_incomplete: the bytes haven't arrived yet. PUT them, then finish again.
• file_rejected: the file isn't one Synq takes, and nothing of it was kept. reason says why: type, size, dimensions or unreadable.
• upload_expired: it wasn't finished within the hour. Start another.

A brand has at most 5 uploads of each purpose waiting to be finished, and at most 20 files of each, counting those Synq still keeps after they were replaced (upload_limit_reached). An org starts at most 60 uploads an hour (rate limits). Get a file to see where an upload stands.

Removing and replacingCopy Anchor Link

Uploading another logo or background replaces the one before. Remove the logo or the background to show none. Synq keeps a logo it no longer shows for 30 days, for email already sent, and a background for 7, then deletes it. Deleting a brand, or its org, deletes its files at once.

Every upload is in the audit log: file.uploaded when Synq kept it, file.rejected when it didn't, and brand.updated for the logo or background it changed.