Skip to content

List brands

GET
/api/v1/admin/brands
Code sample: Shell / cURL
curl --request GET \
--url http://localhost:9090/api/v1/admin/brands \
--header 'Authorization: Bearer <token>'

Every brand, sorted by name. The default brand, the one a client with no brand of its own is drawn in, has isDefault true. Each brand’s clientCount says how many clients are drawn in it.

Brands list

Media typeapplication/json
object
brands
required
Array<object>
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

{
"brands": [
{
"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
}
]
}
]
}

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"
}