Skip to main content
Version: main 🚧

Brand a tenant

Each tenant can carry its own branding. Its users see the tenant's logo and colors in the Platform UI instead of the platform's. Only a platform admin sets a tenant's branding. Tenant admins can't set their own.

Tenant branding builds on the platform's own custom branding. The platform's settings are the starting point, and the tenant's settings replace them field by field.

How Platform chooses the branding​

Platform chooses the branding from the signed-in user, not from the hostname.

  • Tenant users see their tenant's branding once they sign in. Some unset fields fall back to the platform's and others don't. See Which platform settings carry over.
  • Everyone else sees the platform's branding. That covers platform admins, users outside any tenant, and platforms without tenants.
  • The sign-in page shows the platform's branding to everyone, including on a tenant's hostname. No user is known yet, so there's no tenant to choose.
  • Impersonation follows the impersonated user. A platform admin impersonating a tenant user sees that tenant's branding.

Changes take a few seconds to reach tenant users. Reload the page to see them.

Set branding in the UI​

The UI sets the logo, the colors, and custom sidebar links.

  1. Go to Platform > Tenants and click for the tenant.

  2. Click UI Customization.

  3. Set any of Logo, Primary color, Accent color, Sidebar background color, and Custom sidebar links. Leave a logo or color field empty to use the platform's value. Empty custom sidebar links show no custom links.

  4. Click .

  5. Sign in as one of the tenant's users, or impersonate one, and confirm the new logo and colors appear. A platform admin's own session keeps showing the platform's branding.

Set branding through the API​

The favicon, the small logo, custom CSS and JavaScript, legal text, and external URL settings have no UI field. Set them through the tenant's config subresource in the management.loft.sh/v1 API. Through the platform URL, the endpoint is /kubernetes/management/apis/management.loft.sh/v1/tenants/<tenant>/config. Read it with GET and write it with POST. The subresource doesn't support PUT or PATCH.

A write replaces the whole configuration

The subresource holds the tenant's whole configuration, including its hostnames. Any field left out of a write is cleared, so writing only uiSettings removes the tenant's hostnames. Read the current configuration first, change the fields you need, and write the whole object back.

The following example changes only the tenant's favicon. You need curl, jq, and a platform admin's access key. Your license must include Multi-Tenancy. Set ACCESS_KEY to that key in your shell.

Modify the following with your specific values to replace on the whole page and generate copyable commands:
  1. Set the platform URL and tenant name.

    Modify the following with your specific values to generate a copyable command:
    PLATFORM_URL="https://platform.example.com"
    TENANT_NAME="acme"
    TENANT_CONFIG_URL="${PLATFORM_URL%/}/kubernetes/management/apis/management.loft.sh/v1/tenants/${TENANT_NAME}/config"
  2. Read the whole configuration into a file. These files can contain tenant authentication secrets, so keep them private. The umask 077 command makes new files readable only by you, and it stays in effect for the rest of your shell session.

    umask 077
    curl --fail --silent --show-error \
    -H "Authorization: Bearer $ACCESS_KEY" \
    "$TENANT_CONFIG_URL" --output tenant-config.json
  3. Change the favicon while preserving hostnames and every other setting.

    Modify the following with your specific values to generate a copyable command:
    jq --arg favicon "https://acme.example.com/static/favicon.ico" \
    '.spec.uiSettings.faviconURL = $favicon' \
    tenant-config.json > tenant-config.updated.json
  4. Submit the whole modified object with POST.

    curl --fail --silent --show-error --request POST \
    -H "Authorization: Bearer $ACCESS_KEY" \
    -H "Content-Type: application/json" \
    --data-binary @tenant-config.updated.json \
    "$TENANT_CONFIG_URL" --output tenant-config.saved.json
  5. Read the configuration again and compare it with the requested settings. true confirms that the favicon changed and the other settings were preserved.

    curl --fail --silent --show-error \
    -H "Authorization: Bearer $ACCESS_KEY" \
    "$TENANT_CONFIG_URL" --output tenant-config.verified.json
    jq --exit-status --slurpfile expected tenant-config.updated.json \
    '.spec == $expected[0].spec' tenant-config.verified.json

Sign in as a tenant user and reload after a few seconds to confirm the new favicon appears. Keep the local files only as long as you need them.

The uiSettings fields are the same ones the platform config uses. See Custom branding for examples of colors, legal text, sidebar links, and custom CSS and JavaScript.

A tenant's configuration is deleted with the tenant. The platform backup in the UI includes every tenant and its configuration, but the vcluster platform backup management CLI command doesn't. To create a backup, go to Platform > Platform Config > Backup and Restore and click Export. The file holds the whole platform configuration, including each tenant's authentication settings, so store it like a secret.

Required permissions​

Only a platform admin sets a tenant's branding. The built-in Management Admin global role includes the permissions the config subresource needs. Users inside a tenant can't read or write it, tenant admins included.

Which platform settings carry over​

Each uiSettings field resolves independently for a tenant user.

FieldWhat a tenant user sees
logoURL, smallLogoURL, faviconURL, logoBackgroundColorThe tenant's value when set, otherwise the platform's.
primaryColor, sidebarColor, accentColorThe tenant's value when set, otherwise the platform's.
customCss, customJavaScriptThe tenant's own list only. The settings that a signed-in tenant user receives never include the platform's files. The sign-in page uses the platform's files for all users.
navBarButtonsThe tenant's own links only. The platform's links never appear.
legalTemplateThe tenant's own text only, on the account creation page that an invite link opens.
externalURLs.blockThe returned setting is true when either the platform or the tenant sets it.
externalURLs.allowThe returned setting contains the tenant's own list only.
loftVersionThe running platform's version. Tenant input has no effect.

A tenant that sets nothing still shows the platform's logo and colors. The platform's custom CSS, JavaScript, sidebar links, and legal text are the operator's own content, so they don't carry over to a signed-in tenant user.

Platform customizations don't reach tenant users

If your platform config loads custom JavaScript or CSS, or adds sidebar links, tenant users no longer get them after they sign in. That includes analytics, support widgets, and links to internal documentation. Add anything a tenant's users need to that tenant's own configuration.

The sign-in page shows legal text, and it always uses the platform's. A tenant's legalTemplate shows on the account creation page that an invite link opens. Without one, that page shows the product's default terms. Signing in with a password or SSO doesn't show a tenant's legal text.

Security policy header​

The Content-Security-Policy header always comes from the platform config. A tenant's externalURLs settings are returned in the UI settings but aren't enforced. They don't change the header. If the platform blocks external URLs, a tenant's allow list can't reopen them.

License behavior​

Reading and writing a tenant's configuration needs the Multi-Tenancy feature. If that entitlement lapses, tenant users keep their branding. The branding entitlements apply to what every user sees, including a tenant's own settings.

  • Without Custom Branding, users don't see the logo, small logo, favicon, or logo background color.
  • Without Advanced UI Customizations, users don't get custom CSS or custom JavaScript. Custom sidebar links can be removed as well in this version, so don't rely on your license to show or hide them.

A tenant's logo needs Custom Branding even when the platform config sets no logo of its own.

When branding can't be loaded​

If a tenant user's branding can't be loaded, for example while the tenant is being deleted, they see the platform's logo and colors. They still don't get the platform's custom CSS, JavaScript, sidebar links, or legal text.

Next steps​