Portal

The portal is what an end user actually sees: the login page, the MFA challenge, the password reset, the email-verified confirmation. It is served by FerrisKey, on FerrisKey’s domain, which makes it the one surface where your users meet the IAM directly — and the one place where an unstyled default is immediately visible.

The portal module is how you stop it looking like someone else’s product. It splits in two:

• Themes carry the appearance: colours, typography, and the content of each page.
• Layouts carry the arrangement: the structure the pages are composed into.

Both are per realm, so two realms in one deployment can look nothing alike.

Themes

A realm can hold any number of themes, and exactly one is active at a time — the active one is what the portal renders. Everything else is a draft you can work on without touching what users see.

The twelve page types

A theme carries content for twelve pages. All of them:

Editing one page at a time:

PUT /realms/{realm_name}/portal/themes/{theme_id}/pages/{page_type}

Activation is gated on validity

A theme can only be activated when every page is valid — the console calls this “activatable”, and counts them for you. This is deliberate: a partially filled theme would render a broken page for whichever flow happens to hit the gap, and that flow might be password reset at 2am.

GET  /realms/{realm_name}/portal/page-requirements
POST /realms/{realm_name}/portal/themes/{theme_id}/activate

page-requirements tells you what each page still needs, which is what to show a designer rather than a bare “not activatable”.

Theme API

Required permissions: manage_realm, for reads as well as writes.

The public endpoint

GET /realms/{realm_name}/portal/active

Unauthenticated, because the login page has to be able to render before anyone has signed in. It returns the active theme’s appearance and nothing else — a theme is public by nature, so treat what you put in one accordingly.

Layouts

A theme with no layout renders its pages bare, and that is a valid composition rather than an error — the counters distinguish layouts that are attached to a theme from those that are merely deletable because nothing holds them.

Layouts hold the arrangement rather than the colours. Each carries a tree, and one layout per realm can be marked as the default, which is the one used when nothing else is specified.

The two public/ endpoints are unauthenticated for the same reason as portal/active.

Moving a theme between realms

GET  /realms/{realm_name}/portal/themes/{theme_id}/export
POST /realms/{realm_name}/portal/themes/import
GET  /realms/{realm_name}/portal-layouts/{layout_id}/export
POST /realms/{realm_name}/portal-layouts/import

A theme exports as a self-contained JSON envelope: its design tokens, all twelve page trees, and the layout it is framed by, carried by value. Importing it into another realm or another deployment recreates that layout and binds it to the new theme, so the file does not depend on anything already existing at the destination.

Layout import validates the tree before storing it, which the ordinary create endpoint does not — create is fed by the console’s builder and trusts its input. If you generate layouts from a script, import is the endpoint that will catch your mistakes.

Export & Import covers the whole portability surface, including email templates.

Working on a theme safely