A form is one screen of the sign-in flow that auth renders in the browser: the login field, the password, the one-time code, consent and so on. The Forms screen lists them, keeps their versions, lets you switch the active version and manages the themes that style them. Read the section on what the console can and cannot change before you edit a form.
Before you start
Forms sits under GLOBAL in the sidebar. Forms and locales are shared by all tenants; themes can be global or belong to one tenant, so the theme list follows the tenant selected in the sidebar. You need forms:read to see the screen. Creating a version, switching the active version and creating, editing or deleting a theme need forms:manage.
How forms reach the sign-in screens
Each form has an ID, and auth asks for forms by fixed ID. A form is made of:
- a compiled Solid.js script, the part that runs in the browser;
- its source (TSX), stored next to it;
- a CSS file for the form;
- translations, one set of strings per language;
- backend properties, the values the backend passes into the form.
The built-in forms are written in the central-ui/forms/ directory of the product repository. npm run build:forms there compiles each one and places the script, source, CSS and translations in the resources of central, which loads them into the database on start.
| Form ID | Shown when |
|---|---|
credential | The user enters a login, email or phone number, or chooses a passkey. |
password | The user enters a password. |
set-password | The user must set a new password, for example after signing in with a temporary one. |
otp | The user enters a one-time code. |
passkey-enroll | auth offers to register a passkey. |
consent | The client asks the user to approve scopes. |
access-denied | The user is blocked, for example after too many failed attempts. |
conversation-expired | The sign-in took too long and the conversation is gone. |
service-unavailable | auth cannot continue. |
confirm-logout | /logout asks the user to confirm. |
signed-out | The user has been signed out. |
auth-settings | The account page with the user’s sessions and passkeys. |
auth renders only the active version of a form, with the translations of the languages that are active on the Locales page. If a form is missing, auth answers with a plain “not found” page.
The list
Click a card to see its versions, newest first. Each version shows its number (v1), an Active badge on the one auth serves, and Set Active on the others. Expand a version to see the Theme selector, the controls for its backend properties and a Preview button.
Preview renders the form in a frame. You can change the theme, the language, the width and the values of the backend properties to see each state. The preview runs the stored compiled script.
Versions and rollback
| Action | What happens |
|---|---|
| Save a version | Save as new version adds the next number (v2, v3, and so on). It does not activate it, except for the first version of a form, which is active at once. |
| Set Active | Makes that version the active one and deactivates the others. It works on any listed version, so it is also the rollback. |
| Retention | Central keeps the five newest versions and the active one. Older inactive versions are deleted when you save. |
A version is never edited in place. To change a form, click the ＋ on its card (New Version), edit, save, then Set Active on the new version. If it misbehaves, Set Active on the previous version. auth picks the change up on its next configuration sync, not instantly.
Edit a form
The ＋ next to Forms creates a form with a new ID. auth only asks for the IDs in the table above, so a form with another ID is stored but never shown.
| Section | What it holds |
|---|---|
| Solid.js Source (JSX/TSX) | The source of the form components. |
| Per-form CSS | Styles for this form, applied on top of the theme. |
| Localizations | One tab per language that exists on the Locales page. Each placeholder found in the template is a row; the value is the text for that language. |
| Backend Properties | Boolean, AnyOf (a list of allowed values) and Number properties, added with + Add Boolean, + Add AnyOf and + Add Number. The preview uses them. |
| Theme and Preview | A theme and a preview of the unsaved form. |
Note: The console has no compiler. Save as new version sends the compiled script of the version you started from unchanged, together with the text in the source editor. Changing the Solid.js source in the console therefore does not change what users see. CSS, translations and backend properties do take effect. To change the behaviour of a form, build it outside the console and send the compiled script in the
jsCompiledfield ofPUT /configuration/formsin the Central API.
The backend properties of the built-in forms are declared, but the values come from elsewhere. credential declares primaryCredentials, inlinePassword and passkey, which auth takes from the client’s sign-in settings. otp declares length and resendAfter, which come from the tenant’s challenge settings.
Warning: When the configuration of
centralhas abootstrapblock,centralcompares the active version of each built-in form with the copy bundled in its image on every start. If they differ, it saves the bundled copy as a new version and makes it active. Your edit stays in the version list and you can activate it again, but the next restart replaces it once more. Thecentral.confthatversola configuregenerates has abootstrapblock.
Themes
A theme is a block of CSS that styles every form. A client selects its theme in Forms Theme on its page (Client); a client that selects none, or whose theme is empty, gets the default theme.
Open Themes to see the global themes and, under This tenant, the themes of the selected tenant. The ＋ opens New Theme.
| Field | Meaning |
|---|---|
| Theme ID | The name clients select, for example acme-dark. Fixed after creation. |
| Scope | Global (every tenant) or This tenant (the tenant selected in the sidebar). Chosen when you create the theme. |
| CSS | The styles. |
Click a theme’s pencil to edit its CSS; Delete is on the edit page. You cannot delete the default theme, and a theme that a client still uses cannot be deleted either (the API answers with a conflict). On start, central also resets default to the stylesheet bundled in its image when the two differ, the same way as for forms. Put your own styles in a new theme and select it in the client instead of editing default.