Realm settings¶

Tune each realm's session behaviour, branding, languages and token audiences from a single tabbed configuration page.

What it is¶

A realm is a fully isolated tenant in HelixIAM — its own users, clients, keys and policy. The Realm settings screen is where you shape how that tenant behaves at runtime. Settings are scoped to the realm: changing one realm never affects another.

The page is organised into tabs:

Sessions — single sign-on session policy: idle timeout, maximum session lifetime, and whether remember-me is offered on the login page.
Login & branding — the human-facing identity of the realm's sign-in pages (see Login theming for the full white-label workflow).
Registration — whether this realm accepts self-service sign-ups, and what the closed state looks like.
Internationalization — the locales offered to end users, so login, email and account pages render in the right language.
Resource Indicators — an audience allow-list (RFC 8707) that constrains which resource values clients may request in a token, keeping access tokens narrowly scoped.

In the console¶

Open Manage → Realms → Realm settings.
Pick a tab and edit the fields.
Save — changes apply to new sessions and token requests immediately.

Sessions¶

Field	Effect
Idle timeout	A session ends after this period of inactivity.
Max session lifetime	Hard cap on a session's age regardless of activity.
Remember me	Lets returning users keep a longer-lived session from the login page.

These policies are enforced across every application in the realm and underpin silent SSO and re-authentication prompts.

Registration¶

Field	Effect
Allow self-registration	Lets people create their own account for this realm at `/register`.

Self-registration only runs when both switches agree: the platform-wide USER_REGISTRATION_ENABLED environment variable (Configuration) and this realm's Allow self-registration toggle. If either one is off, the realm's /register page shows a "registration closed" panel and no sign-up is accepted.

When it's on, /register uses the same per-realm login branding as the sign-in page — logo, colours, welcome text and custom CSS. The fields on the sign-up form, and which of them are required, are not set here: they come from the realm's claim catalogue. See Self-registration fields.

Post-registration redirect. The Registration tab also sets where a new user goes after signing up (postRegistrationRedirectUrl, an absolute http(s) URL; the console checks it before sending and shows the server's origin refusal on the field).

Switches with their own endpoints, saved after the realm settings and only when changed:

Field	Effect	Endpoint
Sign in with an emailed link	the magic-link sign-in	`/settings/magic-link` (`{"enabled": …}`)
Require a verified email	users must verify their email address	`/settings/verify-email` (`{"enabled": …}`)
MFA skip-grace days	0–90 days a user may skip MFA enrolment, next to Require MFA (only `skipGraceDays` is sent)	`/settings/mfa`

Account console¶

What users may do in the account console:

Field	Effect
Authenticator removal	users may remove their own MFA devices (default on)
Data export	users may export their personal data (default on)
Account deletion	users may delete their own account (default off)
Self-editable profile attributes	the profile attributes users may edit themselves (Edit details in the account console); reserved claims are refused

/settings/account-console holds allowAuthenticatorRemoval, allowDataExport and allowAccountDeletion; /settings/self-editable-attributes holds {"attributes": [...]}. When a save stored the settings but a switch was refused, the console says what was saved and what was not, with the reason.

Branding¶

The five branding fields of the settings object (logoUrl, primaryColor, backgroundColor, welcomeText, customCss) are part of the realm theme: the tab shows them read-only, with a link to Login theming.

Internationalization¶

Enable the locales your tenant serves. End users get login, notification and account-console content in their preferred language; unsupported locales fall back to the realm default.

Resource Indicators (RFC 8707)¶

Add the audiences clients are permitted to request. When a client asks for a resource that is not on the allow-list, the request is rejected with invalid_target — so a token minted for one API can't be replayed against another.

Over the API¶

All four tab groups are one RealmSettingsDto resource under /admin/realms/{realm}/settings. The examples below assume you have set $HELIX_URL / $REALM and logged in — see Authenticating to the API.

Read the settings¶

The response carries the full realm configuration — session policy, password rules, lockout, CAPTCHA, adaptive-risk thresholds and branding — in one object (abridged here):

curl -s -b cookies.txt "$HELIX_URL/admin/realms/$REALM/settings"

{
  "realmId": "acme",
  "displayName": "Acme",
  "issuer": null,
  "accessTokenTtlSeconds": 3600,
  "refreshTokenTtlSeconds": 5184000,
  "reuseRefreshTokens": false,
  "requireMfa": false,
  "ssoSessionIdleTimeoutSeconds": 1800,
  "ssoSessionMaxLifetimeSeconds": 36000,
  "rememberMe": false,
  "rememberMeLifetimeSeconds": 2592000,
  "lockoutEnabled": false,
  "maxLoginFailures": 5,
  "lockoutDurationSeconds": 900,
  "passwordMinLength": 12,
  "breachedPasswordCheck": false,
  "captchaProvider": "none",
  "maxConcurrentSessions": 0,
  "riskPolicyEnabled": false,
  "riskMediumThreshold": 40,
  "riskHighThreshold": 70,
  "logoUrl": null,
  "primaryColor": null,
  "backgroundColor": null,
  "welcomeText": null,
  "customCss": null,
  "registrationEnabled": true
}

Update the settings¶

Submit the full settings object (a PUT replaces it). Refresh CSRF after the read:

# Refresh CSRF after any GET, then PUT (see the auth guide for the helper)
curl -s -b cookies.txt -c cookies.txt "$HELIX_URL/admin/realms/$REALM/settings" >/dev/null
CSRF=$(awk '($6=="__Host-XSRF-TOKEN"||$6=="XSRF-TOKEN")&&$7~/^r1\./{t=$7} END{print t}' cookies.txt)

curl -s -b cookies.txt -X PUT \
  -H "Content-Type: application/json" \
  -H "X-XSRF-TOKEN: $CSRF" \
  -d '{
        "displayName": "Acme",
        "ssoSessionIdleTimeoutSeconds": 900,
        "rememberMe": true,
        "lockoutEnabled": true,
        "maxLoginFailures": 10,
        "breachedPasswordCheck": true,
        "registrationEnabled": true
      }' \
  "$HELIX_URL/admin/realms/$REALM/settings"

The response echoes the updated RealmSettingsDto.

Resource Indicators live at the realm level too

The RFC 8707 audience allow-list is edited on the Resource Indicators tab and enforced on token requests. See Resource Indicators (RFC 8707) above.

Full endpoint set¶

Method & path (under `/admin/realms/{realm}`)	Purpose
`GET /settings` · `PUT /settings`	Read / replace the full realm settings object
`GET` · `PUT /settings/magic-link`	Sign-in with an emailed link
`GET` · `PUT /settings/verify-email`	Require a verified email address
`GET` · `PUT /settings/mfa`	Require MFA, skip-grace days (0–90)
`GET` · `PUT /settings/registration`	Post-registration redirect URL
`GET` · `PUT /settings/account-console`	Account console permissions
`GET` · `PUT /settings/self-editable-attributes`	Profile attributes users may edit