Skip to content

Create brand

POST
/api/v1/admin/brands
Code sample: Shell / cURL
curl --request POST \
--url http://localhost:9090/api/v1/admin/brands \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "name": "example", "appearance": "auto", "theme": "example", "corners": "square", "font": "system-ui", "backgroundFit": "cover", "hideAppName": false, "logo": { "id": 1 }, "darkLogo": { "id": 1 }, "favicon": { "id": 1 }, "background": { "id": 1 }, "regularFont": { "id": 1 }, "boldFont": { "id": 1 }, "footerLinks": [ { "url": "example", "label": "example", "labels": { "additionalProperty": "example" } } ], "supportEmail": "example", "supportUrl": "example", "supportPhone": "example", "palette": { "mode": "basic", "light": { "additionalProperty": "example" }, "dark": { "additionalProperty": "example" } }, "customCss": "example" }'

Create a brand. It is not the default until it is made the default. Each asset slot names a file uploaded first as a brand asset of the slot’s kind: uploadBrandLogo for logo and darkLogo, uploadBrandFavicon, uploadBrandBackground, and uploadBrandFont for regularFont and boldFont. A slot left out or null is empty. The footer links and the support contact are optional: each left out or null is none. The theme custom takes a palette. A basic palette’s other colors are worked out when the brand is saved. Every answer carries colors, the colors the brand is drawn in, and contrastWarnings, the pairs below their minimum contrast. A warning never stops a save. Custom CSS is checked when the brand is saved, and is refused if it could make a browser load anything.

Media typeapplication/json
object
name
required

Unique among brands, at most 60 characters, without < or >. Surrounding spaces are ignored.

string
<= 60 characters
appearance
required
string
Allowed values: auto light dark
theme
required

The key of one of the built-in themes getBrandThemes lists, or custom for a brand drawn in its own palette, which palette then holds.

string
corners
required
string
Allowed values: square rounded pill
font
required

The uploaded font is refused while the brand has no regular font file.

string
Allowed values: system-ui humanist geometric serif neo-grotesque rounded uploaded
backgroundFit
required
string
Allowed values: cover contain tile
hideAppName
boolean
logo

A stored asset of kind logo. Left out or null for none.

object
id
required
integer format: int64
darkLogo

A stored asset of kind logo, drawn in dark mode. Refused without a logo.

object
id
required
integer format: int64
favicon

A stored asset of kind favicon.

object
id
required
integer format: int64
background

A stored asset of kind background.

object
id
required
integer format: int64
regularFont

A stored asset of kind font. The uploaded font is drawn from it.

object
id
required
integer format: int64
boldFont

A stored asset of kind font, for the heavier weights. Refused without a regular font file.

object
id
required
integer format: int64
footerLinks

Up to three links drawn under the brand’s card, in the order given. Left out, null or empty for none; a fourth link is refused. A refusal about a link names the member it is about in error_field, such as /footerLinks/1/url.

Array<object>
nullable <= 3 items

One of a brand’s footer links, as a create or an update names it. The URL and the labels are trimmed.

object
url
required

An https: URL with a host and no user name or password, at most 256 characters.

string
<= 256 characters
label
required

The label drawn in a language the link has no label of its own for: at most 40 characters, without < or >.

string
<= 40 characters
labels

The label of each built-in language the link has its own label in, by language tag: en, de, es, fr, it or pt-BR, each with the bounds of label. Left out, null or {} for none. A blank label is dropped, and any other tag is refused.

object
key
additional properties
string
<= 40 characters
supportEmail

A support email address, of the shape an account’s address takes, at most 254 characters. Left out, null or empty for none.

string
nullable <= 254 characters
supportUrl

A support page: an https: URL with a host and no user name or password, at most 256 characters. Left out, null or empty for none.

string
nullable <= 256 characters
supportPhone

A support phone number in international format: + and the country code, then the number, at most 15 digits in all, the first not zero. Spaces, hyphens, dots and parentheses are accepted and removed, so +44 20 7946 0958 is stored as +442079460958. Left out, null or empty for none.

string
nullable
palette

The brand’s custom palette: required when theme is custom, and refused with a built-in theme, where it is left out or null. Saving a built-in theme drops a stored palette. A refusal about the palette names the member it is about in error_field, such as /palette/light/brand.

object
mode
required

basic: each mode holds exactly canvas, surface, ink and brand, and the other 19 colors are worked out when the brand is saved, again at each save. advanced: each mode holds all 23 colors.

string
Allowed values: basic advanced
light
required

The light mode’s colors. Any other name, or a missing one, is refused at that member.

object
key
additional properties
string
/^#[0-9A-Fa-f]{6}$/
dark
required

The dark mode’s colors, named as light is.

object
key
additional properties
string
/^#[0-9A-Fa-f]{6}$/
customCss

CSS appended to the brand’s full stylesheet, which the auth server’s pages and the admin console’s end-user pages link, and never its admin pages. Left out, null or blank for none. It is stored as written, with each CRLF and CR made a line feed, and is refused when, as stored, it is over 65,536 bytes of UTF-8; holds an @import; holds a URL that is not a data:image/ URL; uses src(), image() or image-set(), under any vendor prefix, whatever they hold; or does not read cleanly as CSS, such as a comment, string or url() left open. Escapes count: @\69mport is an @import. Each refusal has error_field /customCss, and each but the size names its line.

string
nullable

Brand created

Media typeapplication/json
object
brand
required
object
id
required
integer format: int64
name
required
string
appearance
required

Light or dark, or auto to follow each visitor’s device.

string
Allowed values: auto light dark
theme
required

The key of one of the built-in themes getBrandThemes lists, or custom for a brand drawn in its own palette.

string
corners
required

How round the brand’s controls and panels are drawn.

string
Allowed values: square rounded pill
font
required

The font family the brand’s text is drawn in, one of the six system families or the uploaded font.

string
Allowed values: system-ui humanist geometric serif neo-grotesque rounded uploaded
backgroundFit
required

How the brand’s background image fills the page behind the card.

string
Allowed values: cover contain tile
hideAppName
required

Whether the app name’s text is hidden beside the brand’s logo.

boolean
logo
required

The logo drawn above the app name on a card, or null.

object
id
required
integer format: int64
kind
required
string
Allowed values: logo favicon background font
url
required

Where the asset is served, to anyone, its content fingerprint in v. Served by that fingerprint, it may be cached for a year.

string
contentType
required
string
Allowed values: image/png image/jpeg image/webp font/woff2
width
required

Width in pixels, 0 for a font.

integer
height
required

Height in pixels, 0 for a font.

integer
darkLogo
required

The logo drawn in dark mode in place of logo, or null.

object
id
required
integer format: int64
kind
required
string
Allowed values: logo favicon background font
url
required

Where the asset is served, to anyone, its content fingerprint in v. Served by that fingerprint, it may be cached for a year.

string
contentType
required
string
Allowed values: image/png image/jpeg image/webp font/woff2
width
required

Width in pixels, 0 for a font.

integer
height
required

Height in pixels, 0 for a font.

integer
favicon
required

The favicon, or null.

object
id
required
integer format: int64
kind
required
string
Allowed values: logo favicon background font
url
required

Where the asset is served, to anyone, its content fingerprint in v. Served by that fingerprint, it may be cached for a year.

string
contentType
required
string
Allowed values: image/png image/jpeg image/webp font/woff2
width
required

Width in pixels, 0 for a font.

integer
height
required

Height in pixels, 0 for a font.

integer
background
required

The image behind the card, or null.

object
id
required
integer format: int64
kind
required
string
Allowed values: logo favicon background font
url
required

Where the asset is served, to anyone, its content fingerprint in v. Served by that fingerprint, it may be cached for a year.

string
contentType
required
string
Allowed values: image/png image/jpeg image/webp font/woff2
width
required

Width in pixels, 0 for a font.

integer
height
required

Height in pixels, 0 for a font.

integer
regularFont
required

The uploaded font’s regular file, or null.

object
id
required
integer format: int64
kind
required
string
Allowed values: logo favicon background font
url
required

Where the asset is served, to anyone, its content fingerprint in v. Served by that fingerprint, it may be cached for a year.

string
contentType
required
string
Allowed values: image/png image/jpeg image/webp font/woff2
width
required

Width in pixels, 0 for a font.

integer
height
required

Height in pixels, 0 for a font.

integer
boldFont
required

The uploaded font’s bold file, or null.

object
id
required
integer format: int64
kind
required
string
Allowed values: logo favicon background font
url
required

Where the asset is served, to anyone, its content fingerprint in v. Served by that fingerprint, it may be cached for a year.

string
contentType
required
string
Allowed values: image/png image/jpeg image/webp font/woff2
width
required

Width in pixels, 0 for a font.

integer
height
required

Height in pixels, 0 for a font.

integer
footerLinks
required

The links drawn under the brand’s card, in the order they are drawn. Empty when the brand has none.

Array<object>

One of a brand’s footer links. Sent back as it came, it is the same link.

object
url
required
string
label
required

The label drawn in a language the link has no label of its own for.

string
labels
required

The label of each built-in language that has its own, by language tag. {} when none has.

object
key
additional properties
string
supportEmail
required

The support email address the brand’s pages show, or an empty string.

string
supportUrl
required

The support page the brand’s pages link to, or an empty string.

string
supportPhone
required

The support phone number the brand’s pages show, in international format: + and the digits, with no separators, such as +442079460958. An empty string when unset.

string
palette
required

The custom palette as it was written, null for a brand on a built-in theme. Sent back unchanged, it is the same palette.

object
mode
required
string
Allowed values: basic advanced
light
required
object
key
additional properties
string
/^#[0-9a-f]{6}$/
dark
required
object
key
additional properties
string
/^#[0-9a-f]{6}$/
colors
required

Read only: the 23 colors of each mode the brand is drawn in, a custom brand’s stored colors or a built-in theme’s own. A write ignores it. Null for a custom brand whose stored palette cannot be read.

object
light
required
object
key
additional properties
string
/^#[0-9a-f]{6}$/
dark
required
object
key
additional properties
string
/^#[0-9a-f]{6}$/
contrastWarnings
required

Read only: each pair of the brand’s colors below its minimum contrast, in the modes the appearance draws (both under auto), light before dark. Empty when no pair fails, as for every built-in theme. Computed on each answer from the stored colors, so a write ignores it.

Array<object>

A pair of a brand’s colors below its minimum: the foreground token drawn on the background token. The minimums are WCAG 2.2’s level AA contrast ratios, 4.5 for text (SC 1.4.3) and 3 for a boundary or the focus ring (SC 1.4.11). A pair below its minimum never stops a save.

object
mode
required
string
Allowed values: light dark
foreground
required
string
background
required
string
ratio
required

The contrast ratio, cut to two decimals and never rounded up, so 4.496 reads 4.49.

number
minimum
required
number
Allowed values: 4.5 3
customCss
required

The brand’s custom CSS as stored: as it was written, with each CRLF and CR made a line feed. An empty string when the brand has none. It is appended to the brand’s full stylesheet, after its colors and kit.

string
isDefault
required

True for the default brand, the one a client with no brand of its own is drawn in.

boolean
clientCount
required

How many clients are drawn in the brand. Those given it and, for the default brand, those with no brand of their own too, so the counts of all brands add up to every client.

integer
createdAt
required
string format: date-time
nullable
updatedAt
required
string format: date-time
nullable

Example

{
"brand": {
"appearance": "auto",
"corners": "square",
"font": "system-ui",
"backgroundFit": "cover",
"logo": {
"kind": "logo",
"contentType": "image/png"
},
"darkLogo": {
"kind": "logo",
"contentType": "image/png"
},
"favicon": {
"kind": "logo",
"contentType": "image/png"
},
"background": {
"kind": "logo",
"contentType": "image/png"
},
"regularFont": {
"kind": "logo",
"contentType": "image/png"
},
"boldFont": {
"kind": "logo",
"contentType": "image/png"
},
"palette": {
"mode": "basic"
},
"contrastWarnings": [
{
"mode": "light",
"minimum": 4.5
}
]
}
}

Error_code is INVALID_REQUEST_BODY for a body that is not JSON, or one of handler.brand.name_required, handler.brand.name_too_long, handler.brand.name_angle_brackets, handler.brand.name_in_use, handler.brand.appearance_invalid, handler.brand.theme_invalid, handler.brand.corners_invalid, handler.brand.font_invalid, handler.brand.background_fit_invalid, handler.brand.uploaded_font_regular_required, handler.brand.dark_logo_logo_required, handler.brand.bold_font_regular_required, and, for a slot naming no stored asset of its kind, handler.brand.logo_asset_invalid, handler.brand.dark_logo_asset_invalid, handler.brand.favicon_asset_invalid, handler.brand.background_asset_invalid, handler.brand.regular_font_asset_invalid and handler.brand.bold_font_asset_invalid. For the footer links, one of handler.brand.footer_links_too_many, handler.brand.footer_link_label_required, handler.brand.footer_link_label_too_long, handler.brand.footer_link_label_angle_brackets, handler.brand.footer_link_language_invalid, handler.brand.footer_link_language_label_too_long, handler.brand.footer_link_language_label_angle_brackets, handler.brand.footer_link_url_required, handler.brand.footer_link_url_too_long and handler.brand.footer_link_url_invalid, with error_field naming the member, such as /footerLinks/1/url; error_description names the link by its number, counted from

  1. For the support contact, one of handler.brand.support_email_invalid, handler.brand.support_email_too_long, handler.brand.support_url_invalid, handler.brand.support_url_too_long and handler.brand.support_phone_invalid. For the palette, one of handler.brand.palette_required, handler.brand.palette_not_custom, handler.brand.palette_mode_invalid, handler.brand.palette_colors_required, handler.brand.palette_color_required, handler.brand.palette_color_unknown, handler.brand.palette_color_not_basic and handler.brand.palette_color_invalid, with error_field naming the member, such as /palette/light/brand. For the custom CSS, one of handler.brand.custom_css_too_large, handler.brand.custom_css_import, handler.brand.custom_css_url, handler.brand.custom_css_function and handler.brand.custom_css_malformed, with error_field /customCss; error_description names the line it is about, counted from 1, except for the size.
Media typeapplication/json

Admin/account API error envelope. Routing by HTTP status code: 4xx is a client-correctable failure (validation, not found, permission denied, rate limited); 5xx is a server-side problem. The body provides a stable error_code and an error_description for people to read. Protocol endpoints (/auth/token, /auth/authorize, /connect/register, /userinfo) use their RFC-defined error envelopes instead of this one.

object
error_code

Stable identifier for the failure. UPPER_SNAKE for legacy codes (e.g. VALIDATION_ERROR), dotted lowercase for codes named after the sentence’s catalog key (e.g. validator.email.required). Never translated, whatever the request’s language.

string
error_description
required

A sentence for people to read: in the request’s language, from the ui_locales query parameter or else the Accept-Language header, when the server has the sentence in that language, and in English otherwise. Route on error_code, not on this text.

string
error_field

A JSON Pointer (RFC 6901) to the member of the request body the refusal is about, such as /footerLinks/1/url, /footerLinks/0/labels/pt-BR or /palette/light/brand. Left out when the refusal names no member. It’s set by the refusals of a brand’s footer links, palette and custom CSS, and of an email template’s text and brandId.

string

Example generated

{
"error_code": "example",
"error_description": "example",
"error_field": "example"
}

Missing or invalid access token (ACCESS_TOKEN_REQUIRED, INVALID_TOKEN), or a refused DPoP proof (INVALID_DPOP_PROOF)

Media typeapplication/json

Admin/account API error envelope. Routing by HTTP status code: 4xx is a client-correctable failure (validation, not found, permission denied, rate limited); 5xx is a server-side problem. The body provides a stable error_code and an error_description for people to read. Protocol endpoints (/auth/token, /auth/authorize, /connect/register, /userinfo) use their RFC-defined error envelopes instead of this one.

object
error_code

Stable identifier for the failure. UPPER_SNAKE for legacy codes (e.g. VALIDATION_ERROR), dotted lowercase for codes named after the sentence’s catalog key (e.g. validator.email.required). Never translated, whatever the request’s language.

string
error_description
required

A sentence for people to read: in the request’s language, from the ui_locales query parameter or else the Accept-Language header, when the server has the sentence in that language, and in English otherwise. Route on error_code, not on this text.

string
error_field

A JSON Pointer (RFC 6901) to the member of the request body the refusal is about, such as /footerLinks/1/url, /footerLinks/0/labels/pt-BR or /palette/light/brand. Left out when the refusal names no member. It’s set by the refusals of a brand’s footer links, palette and custom CSS, and of an email template’s text and brandId.

string

Example generated

{
"error_code": "example",
"error_description": "example",
"error_field": "example"
}
WWW-Authenticate
string

A Bearer challenge, then a DPoP challenge naming the accepted proof algorithms, on token refusals, the error in the challenge of the scheme the token was sent with: Bearer realm="goiabada", error="invalid_token", error_description="...", DPoP realm="goiabada", algs="ES256 ...". An operation may also return a handler-level 401 without this header.

The token is valid but does not authorise this request. A caller tells the refusals apart by error_code.

INSUFFICIENT_SCOPE comes from the route’s authorisation middleware, before the handler runs: an Admin operation needs one of the scopes its route names, and an Account operation needs authserver:manage-account.

USER_CONTEXT_REQUIRED comes from the same middleware on the Account operations, which also require the token to have been issued for a user: one obtained through the client credentials grant carries no auth_time claim and is refused here.

FORBIDDEN comes from the handler, on the account endpoints that resolve a resource by id and then check it belongs to the caller, so a valid token for the wrong user reaches this rather than a 404.

CLIENT_NOT_ALLOWED comes from the route on the two Account operations only the admin console’s own client may call, deleteAccount and exportAccount. ACCOUNT_DELETION_DISABLED comes from deleteAccount while an administrator has turned off Let users delete their own account.

MANAGE_SCOPE_REQUIRED comes from the handler, on the Admin operations the administrative policy guards. Only authserver:manage creates an administrator, changes one, or changes what reaches one, so no granular scope will ever be enough: the remedy is a token holding authserver:manage, not requesting the route’s scope as for INSUFFICIENT_SCOPE. An administrator is a user, group or client holding any of the six administrative permissions (manage, admin-read, manage-users, manage-clients, manage-settings, browser-sessions), a user directly or through any of its groups, the admin console’s own client whatever it holds, and a client allowed to request the administrative scopes. A granular scope is refused here when it:

  • grants or revokes an administrative permission, directly or by moving a user into or out of a group that holds one, or deletes such a group;
  • writes to an administrator user (profile, credentials, enabled, sessions, consents, attributes, memberships, permissions, deletion), an administrative group (settings, attributes, members, permissions, deletion), or an administrator client (settings, authentication, flows, redirect URIs, sign-out redirect URIs, back-channel logout, DPoP, web origins, token settings, permissions, introspection resources, logo, deletion);
  • switches whether a client may request the administrative scopes, on or off, on any client;
  • adds the authserver resource to a client’s introspection resources;
  • reads an administrator client’s secret, or reads or sets the secret of a client listed for the authserver resource among its introspection resources;
  • sets or changes a client’s back-channel logout URI;
  • changes the email or the audit-log settings;
  • changes an administrative permission’s description. Granular scopes still read administrators. The refusal is answered after the request’s 400 and 404, writes nothing, carries the insufficient_scope challenge of the scheme the token was sent with, such as WWW-Authenticate: Bearer realm="goiabada", error="insufficient_scope", error_description="...", scope="authserver:manage", and leaves an administrator_change_refused audit record.
Media typeapplication/json

Admin/account API error envelope. Routing by HTTP status code: 4xx is a client-correctable failure (validation, not found, permission denied, rate limited); 5xx is a server-side problem. The body provides a stable error_code and an error_description for people to read. Protocol endpoints (/auth/token, /auth/authorize, /connect/register, /userinfo) use their RFC-defined error envelopes instead of this one.

object
error_code

Stable identifier for the failure. UPPER_SNAKE for legacy codes (e.g. VALIDATION_ERROR), dotted lowercase for codes named after the sentence’s catalog key (e.g. validator.email.required). Never translated, whatever the request’s language.

string
error_description
required

A sentence for people to read: in the request’s language, from the ui_locales query parameter or else the Accept-Language header, when the server has the sentence in that language, and in English otherwise. Route on error_code, not on this text.

string
error_field

A JSON Pointer (RFC 6901) to the member of the request body the refusal is about, such as /footerLinks/1/url, /footerLinks/0/labels/pt-BR or /palette/light/brand. Left out when the refusal names no member. It’s set by the refusals of a brand’s footer links, palette and custom CSS, and of an email template’s text and brandId.

string

Example generated

{
"error_code": "example",
"error_description": "example",
"error_field": "example"
}
WWW-Authenticate
string

An insufficient_scope challenge in the scheme the token was sent with, Bearer or DPoP, on every refusal but FORBIDDEN and ACCOUNT_DELETION_DISABLED, which omit it.

The request failed inside the server, most often a storage error. error_code is INTERNAL_SERVER_ERROR: no detail about the failure, only the request id an operator can find the log line by, and retrying is reasonable. Key rotation’s 500 also answers KEY_SET_INCOMPLETE, which names its cause and no retry clears.

Media typeapplication/json

Admin/account API error envelope. Routing by HTTP status code: 4xx is a client-correctable failure (validation, not found, permission denied, rate limited); 5xx is a server-side problem. The body provides a stable error_code and an error_description for people to read. Protocol endpoints (/auth/token, /auth/authorize, /connect/register, /userinfo) use their RFC-defined error envelopes instead of this one.

object
error_code

Stable identifier for the failure. UPPER_SNAKE for legacy codes (e.g. VALIDATION_ERROR), dotted lowercase for codes named after the sentence’s catalog key (e.g. validator.email.required). Never translated, whatever the request’s language.

string
error_description
required

A sentence for people to read: in the request’s language, from the ui_locales query parameter or else the Accept-Language header, when the server has the sentence in that language, and in English otherwise. Route on error_code, not on this text.

string
error_field

A JSON Pointer (RFC 6901) to the member of the request body the refusal is about, such as /footerLinks/1/url, /footerLinks/0/labels/pt-BR or /palette/light/brand. Left out when the refusal names no member. It’s set by the refusals of a brand’s footer links, palette and custom CSS, and of an email template’s text and brandId.

string

Example generated

{
"error_code": "example",
"error_description": "example",
"error_field": "example"
}