Skip to content

Customize the pages and emails

This guide makes the pages your users see, and the emails they get, look and read like your product.

  1. In the admin console, open Admin, General and set App name, up to 30 characters. It’s shown at the top of the sign-in pages and ends their titles, as in “Sign in – Acme”. It also signs every email, and it’s the name authenticator apps list your users’ accounts under.

  2. Open Admin, Branding, and open the brand marked Default. Choose its Appearance and its Theme, add your logo, favicon, background image, font and corners if you like, and click Save.

  3. To give one client a look of its own, click New brand and create one, then choose it under Brand on the client’s Settings tab. See Clients for the pages it draws.

  4. Give each client a display name and a logo, so users see which app they’re signing in to. See Clients.

The sections below cover brands and themes, the brand kit, a custom palette, footer links and a support contact, custom CSS, and the emails’ look and words.

A brand is a look the pages are drawn in: a name, an appearance, a theme and its kit. A client’s pages are drawn in the brand chosen for it. The pages of a client with none, and the pages that belong to no client, are drawn in the default brand. A new install has one brand, Default, on Automatic and Blueberry.

The appearance is Automatic, Light or Dark. Automatic draws the pages light or dark, as each visitor’s device prefers.

The theme is one of eight built-in themes: Blueberry, Blackberry, Avocado, Plum, Tangerine, Guava, Coconut and High contrast. Each has a light and a dark palette whose text and borders meet WCAG 2.2 AA contrast. High contrast’s text meets 7:1. Or choose Custom, after them, to draw the brand in a custom palette of your own colors.

To change the default, open a brand and click Make default.

The default brand can’t be deleted, so make another one the default first.

The Admin API manages the same brands, from GET /api/v1/admin/brands, and GET /api/v1/admin/brand-themes lists each built-in theme’s colors. PUT /api/v1/admin/brands/{id} replaces the whole brand, so a member you leave out is emptied. To change one thing, send back the brand that GET /api/v1/admin/brands/{id} answers, with that change.

A custom palette draws a brand’s pages in colors you choose, light and dark.

  1. Open the brand and choose Custom under Theme. The Colors section opens under the theme cards, holding the colors of the theme you had chosen, to start from.

  2. Choose Basic or Advanced. In Basic, you set four colors for each mode: Background, Card, Text and Brand color. In Advanced, you set all 23.

  3. Type each color as # and six hexadecimal digits, such as #2456c4, or pick it in the color well beside its field. The preview draws it as you type.

  4. Read the list at the foot of the Colors section, and fix the pairs you can. See Contrast warnings.

  5. Click Save.

In Basic, the other 19 colors are worked out from your four when you save. The status colors, for danger, positive, caution and note messages, are Blueberry’s. To choose your own, use Advanced.

Saving a brand on a built-in theme deletes its custom palette.

Advanced shows the colors in four groups, Page, Text, Brand and Status, with each one’s token name, which the Admin API uses:

Color Token
Background canvas
Card surface
Subtle background subtle
Border line
Strong border line-strong
Text ink
Muted text ink-muted
Brand color brand
Strong brand color brand-strong
Text on brand color on-brand
Soft brand background brand-soft
Focus ring focus
Danger color danger
Strong danger color danger-strong
Text on danger color on-danger
Soft danger background danger-soft
Danger text danger-ink
Soft positive background positive-soft
Positive text positive-ink
Soft caution background caution-soft
Caution text caution-ink
Soft note background note-soft
Note text note-ink

Goiabada checks a brand’s colors against the pairs its pages draw text, boundaries and focus rings in: 35 pairs in each mode, such as muted text on the card or the focus ring on the background. Each pair has a minimum contrast ratio from WCAG 2.2 level AA:

Every built-in theme meets them. A pair below its minimum never stops a save.

Only the modes the brand’s appearance draws are checked: both under Automatic, the light colors alone under Light, and the dark ones alone under Dark.

Passing every pair doesn’t make your pages meet WCAG 2.2 AA. That’s a claim about whole pages, against every one of its criteria, and your logo and background image aren’t checked.

A custom palette is the theme custom with a palette member, in POST /api/v1/admin/brands and PUT /api/v1/admin/brands/{id}. palette holds mode, basic or advanced, and light and dark, each a map from a color’s token to its value:

Terminal window
curl -X PUT https://auth.example.com/api/v1/admin/brands/3 \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Acme",
"appearance": "auto",
"theme": "custom",
"corners": "rounded",
"font": "system-ui",
"backgroundFit": "cover",
"palette": {
"mode": "basic",
"light": {"canvas": "#f3f6f4", "surface": "#ffffff", "ink": "#17211b", "brand": "#1e7a4c"},
"dark": {"canvas": "#0f1512", "surface": "#17201b", "ink": "#e4ece7", "brand": "#5cc58f"}
}
}'

PUT /api/v1/admin/brands/{id} gives each member’s rules. A basic palette is worked out again from its four colors each time it’s saved.

A brand’s kit puts your logo, favicon, background image, font and corners on its pages. Each is optional: a brand you haven’t changed is drawn in Goiabada’s own look.

The auth server’s pages and the admin console’s home and its other card pages are drawn with the whole kit, and its Account pages with all of it but the background image. The admin console’s admin pages take only its colors and logo, as the admin console’s client explains.

Logo is drawn above the app name on the sign-in card, and before the app name in the admin console’s header and sidebar. Dark logo takes its place in dark mode. Without one, the logo is drawn in both modes.

Turn on Hide the app name for a logo that already shows the name. The logo then stands for the name, and screen readers announce it as the app name. Page titles keep the app name either way.

A client’s own logo still shows on its screens, below the brand’s.

Favicon is the icon in the browser’s tab. A page whose brand has one links it in place of Goiabada’s icons and web manifest.

Background image is drawn behind the sign-in card, over the theme’s background color. It’s drawn on card pages only: the auth server’s pages and the admin console’s home and card pages, not its Account pages. Choose how it fills the page:

  • Cover fills the page and may crop the image.
  • Contain shows the whole image, with the theme’s background color around it.
  • Tile repeats the image at its own size.

The card stays opaque over the image, so its text is as readable as on a page without one.

Font is one of six system families: System UI, Humanist, Geometric, Serif, Neo-grotesque and Rounded. Each is a list of fonts your visitors’ devices already have, so nothing is downloaded and text looks a little different from one device to another. Apple devices draw Rounded rounded. Windows and Android have no rounded font installed and draw it as an ordinary sans.

To use your own typeface, upload it under Font file and choose Uploaded font. One file is used for every weight, so a variable font works as it should, and a static one gets the browser’s own bold. Add a Bold font file too, and the font file draws the weights up to 500 and the bold one the heavier ones. Text shows in System UI while the font loads, and for any character it lacks. Code and other monospace text keep their own font.

Choosing another family keeps the files, so you can switch back without uploading them again.

Corners are Square, Rounded or Pill. Rounded is Goiabada’s own look. Pill rounds a button or a single-line field fully, and rounds the card and boxes of several lines only as far as their content stays clear of the curve.

Field Type Size Largest file
Logo, Dark logo PNG or JPEG 10 to 512 pixels a side 1 MiB
Favicon PNG, square 48 to 512 pixels a side 1 MiB
Background image PNG, JPEG or WebP 10 to 3840 pixels a side 2 MiB
Font file, Bold font file WOFF2 2 MiB

Animated images are refused, since a looping animation on or behind the sign-in card has no way to pause it. GIF and SVG are refused too.

A file no brand uses is deleted once it’s a day old, so save the brand the same day you upload it.

Every file you upload is public, whether a brand uses it or not: anyone can download it from /brand-assets/{id} on the auth server, and the ids are sequential. Don’t upload a file you aren’t ready to publish.

The Admin API sets the kit in two steps.

  1. Upload each file as a brand asset of its kind, in the multipart field file, with POST /api/v1/admin/brand-assets/logo, /favicon, /background or /font. A dark logo is uploaded as a logo, and both font files as a font. The answer holds the asset’s id:

    Terminal window
    curl -X POST https://auth.example.com/api/v1/admin/brand-assets/logo \
    -H "Authorization: Bearer $TOKEN" \
  2. Name the asset by its id in a slot of the brand, with POST /api/v1/admin/brands or PUT /api/v1/admin/brands/{id}. The slots are logo, darkLogo, favicon, background, regularFont and boldFont:

    Terminal window
    curl -X PUT https://auth.example.com/api/v1/admin/brands/3 \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
    "name": "Acme",
    "appearance": "auto",
    "theme": "blueberry",
    "corners": "rounded",
    "font": "uploaded",
    "backgroundFit": "cover",
    "hideAppName": true,
    "logo": {"id": 42},
    "regularFont": {"id": 43}
    }'

A brand can show up to three links under the card, such as your privacy policy, a status page or your company’s site, and a way for a stuck user to reach your support. Both are optional.

  1. Open Admin, Branding, and open the brand.

  2. Under Footer links, give Link 1 a Label and a URL, and fill in Link 2 and Link 3 if you want more.

  3. Open Label in each language under a link to give it a label in each language your users read.

  4. Under Support contact, fill in any of Email address, Support page URL and Phone number.

  5. Click Save.

The footer is drawn under the card on every page of the auth server, and on the admin console’s home and its other card pages. On the console’s Account pages it follows the page’s content. The console’s admin pages draw no footer. It’s small text on the page’s background color, and on a brand with a background image it sits on a panel in the card’s color, so it stays readable whatever the image.

A brand shows only its own links and contact. A client whose brand has none shows no footer, even when the default brand’s has one.

Everything in the footer is public, as the pages that draw it are.

The links are drawn in the order of their rows, and each one opens in a new tab, so a click during a sign-in leaves the sign-in page open.

  • Label is required, up to 40 characters, without < or >.
  • URL is required, up to 256 characters. It starts with https: and names a site, with no user name or password in it.
  • Label in each language holds one optional label for each built-in language, with the same limits as Label.

A page shows each link’s label in the language the page is written in. Where the link has none for that language, it shows Label. Goiabada can’t tell a screen reader which language that label is in, so fill in a label for each language your users read.

The footer’s contact line reads “Need help?”, followed by each value you set: the email address and the phone number as themselves, so they can be copied, and the URL as a link named “Support page”, which opens in a new tab.

  • Email address is up to 254 characters, in the shape any account’s address takes.
  • Support page URL follows the rule of a footer link’s URL.
  • Phone number is a +, the country code and the number, up to 15 digits in all, the first not 0. You can type it with spaces, hyphens, dots and parentheses, and they’re removed when you save, so the page shows the digits alone, such as +442079460958.

A brand carries the footer in four members, in POST /api/v1/admin/brands, PUT /api/v1/admin/brands/{id} and every brand they answer: footerLinks, the links in the order they’re drawn, and supportEmail, supportUrl and supportPhone. A link is an object with url, label and, optionally, labels, a label for each language by its tag, such as "pt-BR":

Terminal window
curl -X PUT https://auth.example.com/api/v1/admin/brands/3 \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Acme",
"appearance": "auto",
"theme": "blueberry",
"corners": "rounded",
"font": "system-ui",
"backgroundFit": "cover",
"footerLinks": [
{"url": "https://acme.example/privacy", "label": "Privacy", "labels": {"pt-BR": "Privacidade", "de": "Datenschutz"}},
{"url": "https://status.acme.example", "label": "Status"}
],
"supportEmail": "[email protected]",
"supportUrl": "https://acme.example/help",
"supportPhone": "+44 20 7946 0958"
}'

A brand’s custom CSS restyles its pages beyond what its other choices do, such as a page’s layout, a heading’s size or a card’s border.

  1. Open Admin, Branding, and open the brand.

  2. Under Custom CSS, write your rules. Write them against the styling contract: its variables, page names and classes stay the same from one release to the next, so your rules keep matching after an upgrade.

  3. Click Save.

  4. Open a page in the brand to see your rules. If a page becomes unusable, safe mode draws it without your CSS.

body[data-page="sign-in"] .auth-card {
border: 2px solid var(--color-brand);
}

The CSS goes after the brand’s own styles, so a rule of yours wins over a built-in one of the same specificity. It’s on every page of the auth server, and on the admin console’s Account pages, its home page, and its error and sign-out pages. It’s never on the console’s admin pages.

Custom CSS can’t make a browser load anything, so it can’t send a visitor’s data anywhere:

  • It’s up to 64 KB.
  • It can’t hold @import.
  • It can’t hold a URL, except a data: image in url(), such as url("data:image/svg+xml,…"). Upload a background, a logo or a font in the brand’s kit instead.

A brand carries its custom CSS as one string, customCss, in POST /api/v1/admin/brands, PUT /api/v1/admin/brands/{id} and every brand they answer:

Terminal window
curl -X PUT https://auth.example.com/api/v1/admin/brands/3 \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Acme",
"appearance": "auto",
"theme": "blueberry",
"corners": "rounded",
"font": "system-ui",
"backgroundFit": "cover",
"customCss": "body[data-page=\"sign-in\"] .auth-card {\n border: 2px solid var(--color-brand);\n}\n"
}'

An answer carries customCss as it was saved, with each line break turned into a line feed, or "" for a brand with none, blank CSS included.

Every email the auth server sends is drawn in a brand, so a password reset looks like the sign-in it came from.

An email is a card on the brand’s background color, with the brand’s Logo above the app name, as on the sign-in card. Hide the app name hides the name there too, and the logo then carries the app name as its alternative text, which a mail client that blocks images shows in its place. The card takes the brand’s colors, its Corners and its Font. An Uploaded font is drawn in System UI, since an email can’t load a font file.

The password reset link, the activation link, a new user’s setup email and the welcome email can each show a button in the brand’s color, where their body holds {{button}}, and every other link is in the brand’s color too. The brand’s footer links and support contact are drawn under the card. The background image, the favicon and the custom CSS never reach an email.

An email doesn’t follow the reader’s light or dark mode, since many mail clients ignore it. A brand whose Appearance is Dark is drawn in its dark colors, with its Dark logo if it has one. Light and Automatic brands are drawn in their light colors.

Some mail clients, Outlook among them, redraw a light email in dark colors when the reader uses dark mode. They leave the logo as it is, so a logo in dark ink on a transparent background can be hard to read there. Give it a background of its own, or a light outline, and it reads in both.

Every email is sent as plain text too, for mail clients that show no HTML: its text, its links written out, and the footer.

Where an email is sent from decides its brand:

Sent from Drawn in Emails
The pages of a sign-in to your app The client’s brand When someone registers, the activation link, the welcome email and the notice that the address already has an account. The password reset link, and the notice that the password was reset. The notices that two-factor authentication was set up, that a recovery code was used, and that the authenticator was disabled after too many wrong codes.
The Account pages, or the Account API The brand of the client the access token was issued to, which for the admin console’s Account pages is the admin console’s own client’s brand The verification code. The notices that the email address or the password was changed, that two-factor authentication was set up or turned off, that the recovery codes were replaced, that the account was deleted, and that the authenticator was disabled after too many wrong codes while confirming a deletion.
An administrator’s action The default brand A new user’s setup email. The notices that an administrator changed the password, turned off two-factor authentication or deleted the account. The test email from Send test email.

A client with no brand of its own gives the default brand, as its pages do: see Clients. So does the forgot password page opened on its own, outside a sign-in, and a reset link opened in another browser or after the sign-in ended: the notice that the password was reset is then in the default brand too.

Safe mode draws the pages without a brand’s custom CSS, in the built-in Blueberry colors in place of a custom palette, and in System UI in place of an uploaded font. Nothing saved changes. Use it to sign in and fix a brand whose pages you can’t read or use.

  1. Open an admin console address with ?goiabada_safe_mode=true at the end, such as https://admin.example.com/admin/settings/branding?goiabada_safe_mode=true.

  2. Sign in if you’re asked to. The admin console’s pages are now in safe mode, and its admin pages say so.

  3. Fix the brand under Admin, Branding.

  4. Sign out to leave safe mode, and check the pages.

You can also turn it on:

  • For one sign-in to your app, with goiabada_safe_mode=true on the authorization request. Every page of that sign-in is drawn in safe mode.
  • For every page of both servers, for everyone, with GOIABADA_AUTHSERVER_BRAND_SAFE_MODE set to true on the auth server. It lasts until you unset it and restart the auth server, and signing out doesn’t end it.

The pages come in English, Portuguese (Brazil), Spanish, French, Italian and German. On the auth server’s pages and in the admin console, the language is the first of these that names one:

  1. The user’s Page language, which they choose under Account, Profile in the admin console. An administrator can set it too, on the user’s Profile page.
  2. A ui_locales parameter: one or more language tags in order of preference, separated by single spaces, such as ui_locales=es pt-BR. On the auth server, it’s the authorization request’s or the sign-out’s. It’s kept for the rest of that sign-in, and applies to the error page the auth server shows when it refuses the request outright. In the admin console, it’s ?ui_locales= in the page’s address.
  3. The browser’s Accept-Language header.
  4. English.

A user on Automatic, where everyone starts, skips the first. So does a page drawn for nobody Goiabada knows yet, which is why your app’s ui_locales still matters:

  • The admin console uses the page language once the user has signed in to it.
  • The auth server uses it once the user has entered their password: on the one-time code, recovery code and consent pages, on signing out, and on every page shown to a browser that’s signed in.
  • A browser that isn’t signed in gets the sign-in, forgot password, registration and activation pages in the language of the other sources, since the auth server doesn’t know who’s there. The email address typed on the sign-in page never picks the language, so the page can’t reveal an account’s language to whoever types it.
  • The password reset page, opened from the email, is in the page language of the user the link is for.

The auth server reads the page language each time it draws a page, so a change shows on its next page. The admin console reads it when the user signs in to it. A change they save there shows on their next page, and one made elsewhere, such as by an administrator, reaches them when they next sign in or open their profile.

For ui_locales and Accept-Language, the first of their languages Goiabada has text for wins, or English when it has none of them: ui_locales=sv fr shows French, and ui_locales=sv alone shows English. A regional tag reads its language, so fr-CA shows French.

An email to a user is written in their page language. On Automatic, it’s the Language and region on their profile, or English when they haven’t picked one. A regional language reads its language’s email, so fr-CA gets the French one, and a language with no built-in emails gets the English one. The activation link and the welcome email a user gets when they register are written in the language of the page they registered on, since their account has no language yet.

An email template is what one of the auth server’s 19 emails says: its subject, its body and, for the four with a button, the button’s label. Each comes in the six built-in languages, and you can reword any of them in the admin console. How an email looks is its brand’s: see Branded emails.

  1. Open Admin, Email, and the Email templates tab. The list shows every email, when it’s sent, and which languages you’ve edited.

  2. Open an email. It opens in the language you read the admin console in, or in English. Choose another language above the form.

  3. Edit Subject, Button label and Body. The body must hold the placeholders marked required.

  4. Check the Preview beside the form. Choose a Brand to see it in another one.

  5. To see it in a mail client, type an address under Send test email and send it.

  6. Click Save. The next email sent in that language uses it.

Each language is saved, and reset with Reset to default, on its own.

Only the fields you change are kept. A field you leave as it was follows the built-in text when you upgrade, so a release that rewords a body still reaches your users when you’ve changed only the subject.

An edit applies to every brand and every client.

The body is written in a small set of Markdown:

  • A blank line starts a paragraph, and a single line break is kept.
  • **bold** and *italic*.
  • [link text](https://example.com), drawn in the brand’s color. A link leads to an https:, http:, mailto: or tel: address. Any other, such as javascript:, keeps its text and loses its address.
  • Lines starting with - for a bulleted list, or 1. for a numbered one.

Anything else, such as a heading, a quote, a table, code or HTML, is shown as you typed it, and no image is loaded.

The subject is up to 200 characters, on one line, the button label up to 60 characters, and the body up to 20,000 characters. None of them can be empty. The subject and the button label are plain text, and the button label takes no placeholders.

A placeholder is a name between double braces, such as {{name}}, and the email writes its value there. {{ name }}, with spaces, reads the same. To write two braces, type \{{. A value is always written as text, so a name that looks like Markdown or HTML shows as it is.

Placeholder What it writes
{{app_name}} The App name under Admin, General.
{{name}} The user’s full name, or the address the email is sent to when they have none.
{{link}} The email’s link. On its own, the address drawn as a link to itself. As the whole address of a link, [Reset your password]({{link}}), that link.
{{button}} The brand’s button to the link, with the Button label on it. It goes on a line of its own.
{{code}} The verification code. Alone in its paragraph, it’s drawn in a box. In a sentence or the subject, it’s the code as text.
{{expiry}} How long the link or the code lasts, in the email’s language, such as “5 minutes”.
{{codes_left}} How many unused recovery codes are left, as a number.
Email Identifier Placeholders Required
Password reset link password_reset_link {{app_name}}, {{name}}, {{link}}, {{button}}, {{expiry}} {{link}}
Activation link activation_link {{app_name}}, {{link}}, {{button}}, {{expiry}} {{link}}
Welcome welcome {{app_name}}, {{link}}, {{button}} None
Address already has an account registration_existing_account {{app_name}}, {{link}} None
New user’s setup new_user_setup {{app_name}}, {{name}}, {{link}}, {{button}}, {{expiry}} {{link}}
Verification code verification_code {{app_name}}, {{name}}, {{code}}, {{link}}, {{expiry}} {{code}}
Test email test {{app_name}} None
Email address changed email_address_changed {{app_name}}, {{name}} None
Password changed password_changed {{app_name}}, {{name}} None
Password changed by an administrator password_changed_by_administrator {{app_name}}, {{name}} None
Password reset password_reset {{app_name}}, {{name}} None
Two-factor authentication set up otp_enabled {{app_name}}, {{name}} None
Two-factor authentication turned off otp_disabled {{app_name}}, {{name}} None
Two-factor authentication turned off by an administrator otp_disabled_by_administrator {{app_name}}, {{name}} None
Authenticator disabled otp_lockout {{app_name}}, {{name}} None
Recovery code used recovery_code_used {{app_name}}, {{name}}, {{codes_left}} None
Recovery codes replaced recovery_codes_replaced {{app_name}}, {{name}} None
Account deleted account_deleted {{app_name}}, {{name}} None
Account deleted by an administrator account_deleted_by_administrator {{app_name}}, {{name}} None
Operation Route Scope
List every email, with each language’s status GET /api/v1/admin/email-templates authserver:admin-read, authserver:manage-settings or authserver:manage
Read one email: its placeholders and, for each language, its built-in text, the editor’s text and its status GET /api/v1/admin/email-templates/{email} authserver:admin-read, authserver:manage-settings or authserver:manage
Save one language PUT /api/v1/admin/email-templates/{email}/{language} authserver:manage
Reset one language DELETE /api/v1/admin/email-templates/{email}/{language} authserver:manage
Preview a text, saved or not, with sample values POST /api/v1/admin/email-templates/{email}/{language}/preview authserver:admin-read, authserver:manage-settings or authserver:manage
Send a test of a text, saved or not POST /api/v1/admin/email-templates/{email}/{language}/send-test authserver:manage

{email} is the email’s identifier, and {language} one of en, de, es, fr, it and pt-BR.

A save sends the whole text of the language, with buttonLabel only for an email with a button:

Terminal window
curl -X PUT https://auth.example.com/api/v1/admin/email-templates/password_reset_link/en \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"subject": "Reset your {{app_name}} password",
"buttonLabel": "Choose a new password",
"body": "Hello {{name}},\n\n{{button}}\n\n{{link}}\n\nThe link expires in {{expiry}}."
}'

Each language has a status: default with no edit, edited when its edit is sent, and invalid when its edit breaks a rule and the built-in text is sent instead, with the problems listed. Saves, resets and test sends leave entries in the audit log.