Appearance & Branding

Operator runbook for the organization theme: the product name, logo, colours and navigation labels that the IdentityMesh console shows to everyone in your organization, and the role filter that decides who sees which navigation entry.

With nothing saved the console looks exactly as shipped. Every setting below is optional.

Where it lives

Console → Settings → Appearance tab. The tab is visible to anyone holding the roles.write permission.

What can be themed

Each navigation entry can also be customised:

• Display name replaces the entry’s label.
• Icon. Top-level entries take a glyph from the icon set. Child entries take a two-letter mark.
• Visible to limits the entry to the roles you list. See the next section.

Defaults are the shipped look.

Who sees a navigation entry

The role filter sits on top of permissions. It never grants anything. A person sees an entry when both of these hold:

1. They hold the permission the entry requires.
2. Visible to is not set, or any of their roles is listed there. Role names are matched case-insensitively.

Things to know:

• Several roles count. A person can hold roles directly and through group mappings. A match on any one of them is enough.
• An empty list hides the entry for everyone. “Visible to” with no roles is different from “Visible to” not set.
• Hiding is not access control. A hidden entry is still reachable by URL for anyone who holds the permission. Use permissions and role mappings to restrict access, and the filter to keep the navigation tidy.

Lock-out guard

The Settings entry stays visible to anyone holding roles.write, whatever its “Visible to” says. You cannot hide the Appearance tab from the people who manage it, so a mistaken filter can always be corrected.

Unknown roles

A theme can name a role that no longer exists, for example after a group mapping is renamed. That never blocks saving. The editor shows the name as an unknown role chip, and it matches nobody. Remove the chip, or recreate the role, to clear it.

Logo

• PNG or JPEG only.
• Up to 256 KB.
• Up to 512 × 512 pixels.

Logo upload and removal apply immediately. They are not part of Save, and Save does not need to be pressed for a new logo to take effect.

Saving and resetting

• Save stores the theme. It applies to your own session at once. Other users receive it on their next page load.
• Reset to defaults removes the saved theme and the logo and returns the console to the shipped look.

Both actions are recorded in the admin audit trail.

Before sign-in

The theme is readable before sign-in so the login page carries your product name. The anonymous endpoint returns display names, colours and role names only. It carries no identity data and no permissions. The logo image is also served anonymously.

If your organization treats role names as sensitive, keep that in mind when naming roles in “Visible to”.

Upgrading an existing installation

The theme is stored in a new database table, IM_AppearanceSettings. The installer creates it. Follow the normal upgrade procedure; the MSI’s database step adds the table and there is nothing extra to do for this feature.

If your database is updated outside the installer, run the database step before the upgraded Admin API starts. See Running the database step yourself.

How to tell the table is missing. After the upgrade the Appearance tab shows the shipped look and Save reports an error. Run the database step, then restart the Admin API service.

API summary

For integrators. Everything under /api/appearance:

Every change is admin-audited.

Related

• authentication.md — how people sign in and how roles are assigned.
• admin-ui.md — the console.
• audit-retention.md — how long the admin audit trail is kept.