Tenants and tenant settings

A tenant is an isolated identity realm with its own issuer (https://id.example.com/t/acme), users, clients, keys and settings. This page covers creating and managing tenants and every key of the tenant settings document. For what a tenant is, see Tenants and issuers.

The master tenant

Every deployment has a master tenant, created by the first migration. Its users are global administrators (see Administrator access). It cannot be disabled or deleted. Keep ordinary users and applications in their own tenants; master is for the people who run the deployment.

Creating a tenant

Creating tenants needs ridm:tenants:create, which only a global owner holds.

POST /admin/tenants
Authorization: Bearer rpat_…
Content-Type: application/json

{ "slug": "acme", "display_name": "Acme Corp", "settings": { "registration": { "enabled": true } } }

• slug is 1–63 lowercase letters, digits or hyphens, not starting or ending with a hyphen. It is part of every URL of the tenant (/t/acme/…) and cannot change.
• display_name is 1–255 characters; it is shown on the login pages and in the console.
• settings is optional: anything left out takes the defaults below.
• data_region is optional: on a deployment with data regions, the region whose database keeps the tenant’s data (GET /admin/regions lists them; absent or home: the home database). It is fixed at creation; ridm-api move-tenant moves a tenant later.

A new tenant is seeded with the standard scopes (openid, profile, email, phone, address, offline_access, features), the urn:ridm:admin and urn:ridm:account resource servers, the six built-in admin roles, and the two built-in console clients (ridm-admin-console, ridm-account-console). Its first signing key is made on first use. It has no users: invite or create an administrator for it next (see Users, invitations and bulk import).

Managing a tenant

PATCH takes display_name, status (active or disabled) and settings. The settings are a JSON merge patch (RFC 7396) over the stored document: send only what changes, and null resets a key to its default. A field name the settings document does not have is refused with 400 (“unknown settings fields: …”) rather than silently dropped, because it is almost certainly a typo; that includes the removed registration.captcha. Tagged settings switch variant cleanly: {"mfa": {"mode": "optional"}} replaces a required_for_roles policy without clearing roles by hand.

curl -s -X PATCH "https://id.example.com/admin/tenants/acme" \
  -H "Authorization: Bearer $RIDM_TOKEN" -H "Content-Type: application/json" \
  -d '{"settings": {"password": {"min_length": 14}, "mfa": {"mode": "required_for_admins"}}}'

A disabled tenant refuses every sign-in and token request, and its tokens stop working at the admin API; administrators can still read it through the admin API and re-enable it. Deleting a tenant permanently removes it and everything in it, with no soft-delete period.

The console’s Settings page (/console/settings/) shows every setting on one page and saves as you go: changes are joined into one merge patch sent once typing pauses. The header shows “Unsaved changes”, “Saving…”, “Saved”, or the API’s reason for refusing, after which the stored settings are reloaded.

To keep settings in version control, export the tenant with ridm tenant export acme -o acme.json and apply edits with ridm tenant import; see Configuration as code.

The settings document

Every key has a default, and a stored document written by an older version keeps loading. The top-level keys:

password

The policy applies to users’ own changes, registration, invitations, admin-set passwords (unless skip_policy is sent) and imported plaintext passwords. Imported hashes are not checked, since the plaintext is unknown.

session

A client may set its own token lifetimes, which take precedence over these defaults (see Registering clients).

The session timeouts bound refresh tokens too. A refresh token issued without the offline_access scope belongs to the browser session it came from: it stops working once that session ends, whether by sign-out, idle_timeout_secs or absolute_timeout_secs, and each refresh counts as activity that extends the idle window. A refresh token issued with offline_access outlives the session’s timeouts and lasts its own refresh_token_ttl_secs, though an explicit sign-out still revokes it. Clients that need long-lived access without a browser, device-flow clients among them, should request offline_access. See Tokens.

auth

First-factor methods shown on the login page.

registration

Whether registration demands a CAPTCHA is captcha.on_registration (see Rate limits, IP rules and CAPTCHA); in the console it sits under Settings → Passwords & lockout. The earlier registration.captcha key is gone: a migration carried any true value over to captcha.on_registration, a PATCH naming it is refused, and a tenant import ignores it.

The fields a registrant fills in beyond username, email and password come from the tenant’s profile schema (see Users).

lockout

An administrator clears a lock with POST /admin/tenants/{slug}/users/{user}/unlock or the Unlock button on the user page.

notifications

Security notices sent to the user by email, or by text message when they have no email address. All default to true.

account

What users may do to their own account in the account console. These keys are not on the console’s Settings page; change them with PATCH /admin/tenants/{slug} or a tenant import.

locale

Tags are normalised on save (pt_BR becomes pt-BR); a malformed tag, or a default outside supported, is refused. An empty supported list becomes [default]. The language of a page or message is negotiated from the OIDC ui_locales parameter, then the user’s stored locale, then default; a tag matches exactly or by language (de-CH matches a supported de). Right-to-left languages (Arabic, Hebrew, Persian, Urdu and others) set dir="rtl". The flow state carries the result as locale, dir (ltr or rtl) and the selectable locales; every email or SMS the flow sends is rendered in that locale, and a self-registered user is stored with it.

The bundled UI ships English strings only (ui/src/i18n/en.json). An added bundle falls back key by key (de-CH, then de, then English), so a partial translation still renders; plurals follow Intl.PluralRules, and the stylesheets use logical properties so right-to-left languages mirror the layout. Message templates can be overridden per locale; see Email, SMS and templates.

branding

How the tenant looks: the sign-in pages, the account console, and the admin console while it administers this tenant. Settings → Appearance in the console edits it with a live preview.

Colours are checked on write: a value that is not a CSS colour literal is refused, and contrast_color must be hex. The console shows the contrast ratios the two colours achieve on the page and on buttons in both modes, and flags anything under 4.5:1, but it does not refuse a brand colour over it.

Branding, the display name, locales and the offered sign-in methods are published at GET /t/{slug}/branding, a public, cacheable document every end-user page loads. The console’s appearance editor (Settings → Appearance) frames the real login page in preview mode and applies each draft change as you type. Images are loaded from their URLs over https; the pages’ Content-Security-Policy allows images and fonts from any https origin, so host them anywhere.

keys

See Rotating keys.

discovery

audit

See Webhooks and the audit log.

features

A map of flag name to flag, default {}: each with enabled, an optional description and optional per-organization values. rIDM itself doesn’t act on them; applications read them through the features scope or GET /t/{slug}/features. Edit them on the console’s Feature flags page. See Feature flags.

{ "features": { "beta_dashboard": { "enabled": true, "organizations": { "globex": false } } } }

custom_domain

A hostname such as login.acme.example (optionally with a port), lower-cased on save. It must not be the deployment’s own host and must not be used by another tenant. Default null, meaning the issuer is {PUBLIC_URL}/t/{slug}. See Custom domains.

Settings kept outside the document

Some tenant configuration holds secrets and so lives behind its own endpoints, stored encrypted and never returned:

Limits

Some configuration is read whole (by the console, the tenant document and token issuance), so each tenant has a ceiling on it. Creating one more past the ceiling is a 400:

Users, clients, organizations and the audit log have no ceiling: their lists are paginated.