Make brand the default
curl --request POST \ --url http://localhost:9090/api/v1/admin/brands/1/make-default \ --header 'Authorization: Bearer <token>'Make a brand the default. The pages of every client with no brand of its own, and the pages that belong to no client, are then drawn in it. A brand that already is the default is answered unchanged.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Brand ID
Responses
Section titled “Responses”The brand, now the default
object
object
Light or dark, or auto to follow each visitor’s device.
The key of one of the built-in themes getBrandThemes lists, or custom for a brand
drawn in its own palette.
How round the brand’s controls and panels are drawn.
The font family the brand’s text is drawn in, one of the six system families or the uploaded font.
How the brand’s background image fills the page behind the card.
Whether the app name’s text is hidden beside the brand’s logo.
The logo drawn above the app name on a card, or null.
object
Where the asset is served, to anyone, its content fingerprint in v. Served by that
fingerprint, it may be cached for a year.
Width in pixels, 0 for a font.
Height in pixels, 0 for a font.
The logo drawn in dark mode in place of logo, or null.
object
Where the asset is served, to anyone, its content fingerprint in v. Served by that
fingerprint, it may be cached for a year.
Width in pixels, 0 for a font.
Height in pixels, 0 for a font.
The favicon, or null.
object
Where the asset is served, to anyone, its content fingerprint in v. Served by that
fingerprint, it may be cached for a year.
Width in pixels, 0 for a font.
Height in pixels, 0 for a font.
The image behind the card, or null.
object
Where the asset is served, to anyone, its content fingerprint in v. Served by that
fingerprint, it may be cached for a year.
Width in pixels, 0 for a font.
Height in pixels, 0 for a font.
The uploaded font’s regular file, or null.
object
Where the asset is served, to anyone, its content fingerprint in v. Served by that
fingerprint, it may be cached for a year.
Width in pixels, 0 for a font.
Height in pixels, 0 for a font.
The uploaded font’s bold file, or null.
object
Where the asset is served, to anyone, its content fingerprint in v. Served by that
fingerprint, it may be cached for a year.
Width in pixels, 0 for a font.
Height in pixels, 0 for a font.
The links drawn under the brand’s card, in the order they are drawn. Empty when the brand has none.
One of a brand’s footer links. Sent back as it came, it is the same link.
object
The label drawn in a language the link has no label of its own for.
The label of each built-in language that has its own, by language tag. {} when none has.
object
The support email address the brand’s pages show, or an empty string.
The support page the brand’s pages link to, or an empty string.
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.
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
object
object
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
object
object
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.
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
The contrast ratio, cut to two decimals and never rounded up, so 4.496 reads 4.49.
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.
True for the default brand, the one a client with no brand of its own is drawn in.
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.
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 } ] }}Invalid request body or parameters
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
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.
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.
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.
Example generated
{ "error_code": "example", "error_description": "example", "error_field": "example"}Headers
Section titled “Headers”Bearer challenge when token transport is malformed; ordinary validation errors omit it.
Missing or invalid access token (ACCESS_TOKEN_REQUIRED, INVALID_TOKEN), or a refused DPoP proof (INVALID_DPOP_PROOF)
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
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.
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.
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.
Example generated
{ "error_code": "example", "error_description": "example", "error_field": "example"}Headers
Section titled “Headers”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
authserverresource to a client’s introspection resources; - reads an administrator client’s secret, or reads or sets the
secret of a client listed for the
authserverresource 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 anadministrator_change_refusedaudit record.
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
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.
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.
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.
Example generated
{ "error_code": "example", "error_description": "example", "error_field": "example"}Headers
Section titled “Headers”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.
Resource not found
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
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.
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.
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.
Example generated
{ "error_code": "example", "error_description": "example", "error_field": "example"}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.
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
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.
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.
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.
Example generated
{ "error_code": "example", "error_description": "example", "error_field": "example"}