Set a client's brand
curl --request PUT \ --url http://localhost:9090/api/v1/admin/clients/1/brand \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "brandId": 7 }'Give the client a brand of its own, or with null put it back on the default brand.
The client’s sign-in, sign-out and form_post pages are drawn in its brand. A client with
no brand of its own is drawn in the default brand, and follows it when another brand is
made the default. A brand given explicitly stays given, also the default brand. A new
client starts with none.
brandId is required: a body without it is refused rather than read as null.
The route admits authserver:manage-clients and authserver:manage; on an
administrator client, only authserver:manage. The answer is the client as it now is.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Client ID
Request Bodyrequired
Section titled “Request Bodyrequired”object
The id of the brand to give the client, or null to put it back on the default brand. Required; a body without it is refused
Example
7Responses
Section titled “Responses”Brand saved
object
object
The client’s website URL
The client’s own privacy policy, linked from the consent screen whenever set; empty when it has none
The client’s own terms of service, linked from the consent screen whenever set; empty when it has none
A user-friendly name for the client
Whether a user’s earlier approval skips the consent screen for this client. Always true for a confidential client. A public client starts with it off, so users are asked whenever the consent screen is owed, even if they approved the app before.
Where the auth server POSTs a logout token when a session the client was on ends; empty when it has none. Set through PUT /api/v1/admin/clients/{id}/backchannel-logout
Whether the client requires the session identifier (sid) in every logout token. Set through PUT /api/v1/admin/clients/{id}/backchannel-logout
Whether the client requires DPoP for token requests: a token request without a DPoP proof is refused, and so are the implicit response types that return an access token. Set through PUT /api/v1/admin/clients/{id}/dpop, or by dynamic client registration’s dpop_bound_access_tokens
Read-only. True when the client registered itself through /connect/register
Read-only. True when the client may request the administrative authserver scopes on a user’s behalf; always true for the admin console’s own client. Switched through PUT /api/v1/admin/clients/{id}/administrative-scopes, with authserver:manage alone
The brand the client’s pages are drawn in, or null when the client has no brand of its own and follows the default brand. Set through PUT /api/v1/admin/clients/{id}/brand
When true, the client logo is displayed on sign-in and consent screens
When true, the display name is shown instead of the client identifier
When true, the client description is displayed on sign-in and consent screens
When true, the client website URL is displayed on sign-in and consent screens
Read-only. The token_endpoint_auth_method a confidential client registered through /connect/register, client_secret_basic or client_secret_post. The client authenticates at the token, revocation and introspection endpoints with that method only, and a secret sent the other way is refused with invalid_client. Empty for a client not held to one method, which accepts both. Switching the client to public through PUT /api/v1/admin/clients/{id}/authentication clears it
Null inherits the global setting, true requires PKCE, false makes it optional. Ignored for public clients, which always require PKCE
Null inherits the global setting, true enables the implicit flow, false disables it. Deprecated in OAuth 2.1
Null inherits the global setting, true enables grant_type=password (RFC 6749 section 4.3), false disables it. Deprecated in OAuth 2.1
“on” includes the OpenID Connect claims in this client’s access tokens, “off” leaves them out, “default” follows the global setting of the same name.
“on” includes the OpenID Connect claims in this client’s ID tokens, “off” leaves them out, “default” follows the global setting of the same name.
Null when this collection was not loaded for the response.
The redirectURIs entries of ClientResponse.
The schema name is unchanged, but the shape below is not what releases up to and
including v1.6.0 put on the wire: this position carried the persistence row directly,
so its keys arrived capitalised and its createdAt arrived as a two-field
{"Time":...,"Valid":...} object. The keys below are the ones every published
contract has always declared.
object
The client’s sign-out redirect URIs, the addresses a sign-out may return to. Null when this collection was not loaded for the response.
The postLogoutRedirectURIs entries of ClientResponse: one of the client’s sign-out redirect URIs, in the shape of a redirect URI.
object
Null when this collection was not loaded or the client has no web origins.
The webOrigins entries of ClientResponse. Its keys moved in the same release and for
the same reason as RedirectURI above.
object
Example
{ "client": { "includeOpenIDConnectClaimsInAccessToken": "on", "includeOpenIDConnectClaimsInIdToken": "on" }}Error_code is VALIDATION_ERROR for a malformed ID, INVALID_REQUEST_BODY for a body
that is not a JSON object or a brandId that is not a whole number or null,
handler.client_brand.brand_id_required for a body without brandId, or
handler.client_brand.brand_not_found for a brand that does not exist.
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"}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"}