Skip to main content

Branding

A branding is the visual identity (logos and colors) associated with a provider or a customer. It's exposed as a singular sub-resource under its parent, not as a top-level collection.

Where branding lives​

Each provider and each customer has at most one optional branding. A freshly created provider or customer has no branding until you POST one.

Fields​

A branding carries a light-mode and a dark-mode set:

FieldDescriptionExample
lightLogoLogo URL shown in light modehttps://cdn.acme.example/logo-light.svg
lightPrimaryColorPrimary color in light mode#1a73e8
lightSecondaryColorSecondary color in light mode#fbbc04
darkLogoLogo URL shown in dark modehttps://cdn.acme.example/logo-dark.svg
darkPrimaryColorPrimary color in dark mode#8ab4f8
darkSecondaryColorSecondary color in dark mode#fdd663

Logos must be valid URLs. Colors are 3- or 6-digit hex values, with or without a leading # (e.g. #abc, abc, #1a2b3c, 1a2b3c).

On POST and PUT every field is required. On PATCH any field may be omitted (leave unchanged) or sent as null (clear).

Authorization​

Branding is not its own authorization resource. All branding operations are gated on the parent. read on the provider lets you read its branding, and update on the provider lets you create, replace, patch, or delete its branding. Same for customer.

Lifecycle​

  • POST /providers/{id}/branding creates a branding and associates it with the provider. 409 Conflict if one already exists.
  • PUT /providers/{id}/branding replaces all six fields. 400 Bad Request if no branding is set yet. Use POST first.
  • PATCH /providers/{id}/branding updates a subset of fields. 404 Not Found if no branding is set.
  • DELETE /providers/{id}/branding clears the association and soft-deletes the underlying row.

All four verbs exist at /customers/{id}/branding with identical semantics.

The branding's own id is server-assigned and stable across PUT replaces. The same row is mutated in place.

When a provider or customer response includes a branding link, clients can follow it to fetch the branding. The link is always present in the _links section; following it when no branding has been set yet returns 404.

More info​